util/eventbus: initial implementation of an in-process event bus

Updates #15160

Signed-off-by: David Anderson <dave@tailscale.com>
Co-authored-by: M. J. Fromberger <fromberger@tailscale.com>

util/eventbus/doc.go

@@ -0,0 +1,100 @@
+// Copyright (c) Tailscale Inc & AUTHORS
+// SPDX-License-Identifier: BSD-3-Clause
+
+// Package eventbus provides an in-process event bus.
+//
+// The event bus connects publishers of typed events with subscribers
+// interested in those events.
+//
+// # Usage
+//
+// To publish events, use [PublisherOf] to get a typed publisher for
+// your event type, then call [Publisher.Publish] as needed. If your
+// event is expensive to construct, you can optionally use
+// [Publisher.ShouldPublish] to skip the work if nobody is listening
+// for the event.
+//
+// To receive events, first use [Bus.Queue] to create an event
+// delivery queue, then use [Subscribe] to get a [Subscriber] for each
+// event type you're interested in. Receive the events themselves by
+// selecting over all your [Subscriber.Chan] channels, as well as
+// [Queue.Done] for shutdown notifications.
+//
+// # Concurrency properties
+//
+// The bus serializes all published events, and preserves that
+// ordering when delivering to subscribers that are attached to the
+// same Queue. In more detail:
+//
+//   - An event is published to the bus at some instant between the
+//     start and end of the call to [Publisher.Publish].
+//   - Events cannot be published at the same instant, and so are
+//     totally ordered by their publication time. Given two events E1
+//     and E2, either E1 happens before E2, or E2 happens before E1.
+//   - Queues dispatch events to their Subscribers in publication
+//     order: if E1 happens before E2, the queue always delivers E1
+//     before E2.
+//   - Queues do not synchronize with each other: given queues Q1 and
+//     Q2, both subscribed to events E1 and E2, Q1 may deliver both E1
+//     and E2 before Q2 delivers E1.
+//
+// Less formally: there is one true timeline of all published events.
+// If you make a Queue and subscribe to events on it, you will receive
+// those events one at a time, in the same order as the one true
+// timeline. You will "skip over" events you didn't subscribe to, but
+// your view of the world always moves forward in time, never
+// backwards, and you will observe events in the same order as
+// everyone else.
+//
+// However, you cannot assume that what your subscribers on your queue
+// see as "now" is the same as what other subscribers on other
+// queues. Their queue may be further behind you in the timeline, or
+// running ahead of you. This means you should be careful about
+// reaching out to another component directly after receiving an
+// event, as its view of the world may not yet (or ever) be exactly
+// consistent with yours.
+//
+// To make your code more testable and understandable, you should try
+// to structure it following the actor model: you have some local
+// state over which you have authority, but your only way to interact
+// with state elsewhere in the program is to receive and process
+// events coming from elsewhere, or to emit events of your own.
+//
+// # Expected subscriber behavior
+//
+// Subscribers are expected to promptly receive their events on
+// [Subscriber.Chan]. The bus has a small, fixed amount of internal
+// buffering, meaning that a slow subscriber will eventually cause
+// backpressure and block publication of all further events.
+//
+// In general, you should receive from your subscriber(s) in a loop,
+// and only do fast state updates within that loop. Any heavier work
+// should be offloaded to another goroutine.
+//
+// Causing publishers to block from backpressure is considered a bug
+// in the slow subscriber causing the backpressure, and should be
+// addressed there. Publishers should assume that Publish will not
+// block for extended periods of time, and should not make exceptional
+// effort to behave gracefully if they do get blocked.
+//
+// These blocking semantics are provisional and subject to
+// change. Please speak up if this causes development pain, so that we
+// can adapt the semantics to better suit our needs.
+//
+// # Debugging facilities
+//
+// (TODO, not implemented yet, sorry, I promise we're working on it next!)
+//
+// The bus comes with introspection facilities to help reason about
+// the state of the client, and diagnose issues such as slow
+// subscribers.
+//
+// The bus provide a tsweb debugging page that shows the current state
+// of the bus, including all publishers, subscribers, and queued
+// events.
+//
+// The bus also has a snooping and tracing facility, which lets you
+// observe all events flowing through the bus, along with their
+// source, destination(s) and timing information such as the time of
+// delivery to each subscriber and end-to-end bus delays.
+package eventbus