Documentation
¶
Overview ¶
Package notifier provides check notification implementations for different database backends.
Index ¶
- Constants
- func ListenerCount(n EventNotifier) int
- type EventNotifier
- type ListenerCounter
- type LocalEventNotifier
- func (n *LocalEventNotifier) Close() error
- func (n *LocalEventNotifier) Listen(eventType string) <-chan string
- func (n *LocalEventNotifier) ListenerCount() int
- func (n *LocalEventNotifier) Notify(ctx context.Context, eventType string, payload string) error
- func (n *LocalEventNotifier) Unlisten(eventType string, target <-chan string)
- type PgEventNotifier
- func (n *PgEventNotifier) Close() error
- func (n *PgEventNotifier) Listen(eventType string) <-chan string
- func (n *PgEventNotifier) ListenerCount() int
- func (n *PgEventNotifier) Notify(ctx context.Context, eventType string, payload string) error
- func (n *PgEventNotifier) ReconnectEvents() <-chan struct{}
- func (n *PgEventNotifier) Unlisten(eventType string, target <-chan string)
- type ReconnectNotifier
Constants ¶
const ListenerBuffer = 16
ListenerBuffer is the per-listener channel capacity handed out by Listen. Delivery is best-effort (Notify never blocks: a full channel drops the payload), so this buffer bounds how bursty publishing may get before a slow consumer starts losing events. A capacity of 1 was enough for the job.created wakeup (dropped wakeups coalesce by design), but org-scoped realtime hints arrive in multi-org bursts where each dropped payload is a DIFFERENT org's update — observed as CI-only realtime test failures when the -race scheduler let two back-to-back hints outrun the draining goroutine.
Variables ¶
This section is empty.
Functions ¶
func ListenerCount ¶
func ListenerCount(n EventNotifier) int
ListenerCount returns n's registered listener-channel count, or 0 if n does not implement ListenerCounter.
Types ¶
type EventNotifier ¶
type EventNotifier interface {
// Notify sends an event of the specified type with a payload.
// This is a best-effort notification - errors may be logged but not propagated.
Notify(ctx context.Context, eventType string, payload string) error
// Listen returns a channel that receives payloads for events of the specified type.
// Consumers can select on this channel to wake up when events occur.
Listen(eventType string) <-chan string
// Unlisten deregisters a channel previously returned by Listen for the given
// event type, so it stops receiving payloads and its listener slot is
// reclaimed. Callers that subscribe per-call (e.g. GetJobWait, which Listens
// on every invocation) MUST Unlisten — otherwise one channel leaks per call
// and the listener slices grow without bound (see the 2026-07-11 realtime
// silence incident). Deregister-only: the channel is left for GC rather than
// closed, so there is no double-close race with Close(). Passing a channel
// that was never registered (or was already unlistened) is a safe no-op.
Unlisten(eventType string, target <-chan string)
// Close releases resources used by the notifier.
Close() error
}
EventNotifier provides a generic event notification system. It supports multiple event types with payload data, allowing checkrunners and other components to wake up immediately instead of polling.
func New ¶
New creates an EventNotifier appropriate for the database type. For PostgreSQL, it uses NOTIFY/LISTEN for optimal performance. For SQLite and other databases, it uses in-memory channels.
Parameters:
- db: The database connection
- dbType: Database type ("postgres", "sqlite", etc.)
- connString: Connection string (required for PostgreSQL LISTEN)
- logger: Optional logger (uses slog.Default() if nil)
type ListenerCounter ¶
type ListenerCounter interface {
ListenerCount() int
}
ListenerCounter is implemented by notifiers that can report how many listener channels are currently registered. Both LocalEventNotifier and PgEventNotifier satisfy it; the memory surface uses a type assertion so the EventNotifier interface itself stays minimal.
type LocalEventNotifier ¶
type LocalEventNotifier struct {
// contains filtered or unexported fields
}
LocalEventNotifier uses in-memory channels for notifications. This implementation works for any database (SQLite, PostgreSQL, etc.) and is particularly useful for single-process deployments.
func NewLocalEventNotifier ¶
func NewLocalEventNotifier() *LocalEventNotifier
NewLocalEventNotifier creates a new channel-based notifier.
func (*LocalEventNotifier) Close ¶
func (n *LocalEventNotifier) Close() error
Close closes all notification channels.
func (*LocalEventNotifier) Listen ¶
func (n *LocalEventNotifier) Listen(eventType string) <-chan string
Listen returns a channel that receives payloads for events of the specified type.
func (*LocalEventNotifier) ListenerCount ¶
func (n *LocalEventNotifier) ListenerCount() int
ListenerCount returns the total number of registered listener channels across all event types. Each Listen call appends a channel; a listener that is never drained/deregistered leaks both the channel and its goroutine, so this count is the memory-analysis signal for the event-listener hypothesis.
func (*LocalEventNotifier) Notify ¶
Notify sends a notification to all listeners of the specified event type. Uses non-blocking send to prevent API slowdown if channels are full.
func (*LocalEventNotifier) Unlisten ¶
func (n *LocalEventNotifier) Unlisten(eventType string, target <-chan string)
Unlisten deregisters a channel previously returned by Listen. See the EventNotifier interface for the contract. Deregister-only: the channel is not closed here (Close closes every remaining channel), which avoids a double-close race. Unknown channels are a no-op.
type PgEventNotifier ¶
type PgEventNotifier struct {
// contains filtered or unexported fields
}
PgEventNotifier uses PostgreSQL LISTEN/NOTIFY for notifications. This provides optimal performance for PostgreSQL databases by using native database pub/sub instead of polling.
func NewPgEventNotifier ¶
func NewPgEventNotifier(db *bun.DB, connString string, logger *slog.Logger) (*PgEventNotifier, error)
NewPgEventNotifier creates a new PostgreSQL LISTEN/NOTIFY based notifier. connString should be a PostgreSQL connection string (DSN).
func (*PgEventNotifier) Close ¶
func (n *PgEventNotifier) Close() error
Close releases resources used by the PostgreSQL listener.
func (*PgEventNotifier) Listen ¶
func (n *PgEventNotifier) Listen(eventType string) <-chan string
Listen returns a channel that receives payloads for events of the specified type. If this is the first listener for this event type, it subscribes to the PostgreSQL channel.
func (*PgEventNotifier) ListenerCount ¶
func (n *PgEventNotifier) ListenerCount() int
ListenerCount returns the total number of registered listener channels across all event types. Mirrors LocalEventNotifier.ListenerCount so the memory surface can report listener cardinality regardless of the DB backend.
func (*PgEventNotifier) Notify ¶
Notify sends a NOTIFY signal to PostgreSQL with the payload. This is a best-effort operation - errors are logged but not propagated.
func (*PgEventNotifier) ReconnectEvents ¶
func (n *PgEventNotifier) ReconnectEvents() <-chan struct{}
ReconnectEvents registers and returns a channel signaled each time the underlying pq.Listener reconnects after a connection drop. Buffered (size 1) with non-blocking sends so reconnect bursts coalesce into a single pending signal. Closed by Close. Implements notifier.ReconnectNotifier.
func (*PgEventNotifier) Unlisten ¶
func (n *PgEventNotifier) Unlisten(eventType string, target <-chan string)
Unlisten deregisters a channel previously returned by Listen. See the EventNotifier interface for the contract. Deregister-only: the channel is not closed here (Close closes every remaining channel), which avoids a double-close race. The underlying pq.Listener LISTEN is intentionally left in place — the set of event types is small and fixed, so re-subscribing is not worth the churn. Unknown channels are a no-op.
type ReconnectNotifier ¶
type ReconnectNotifier interface {
// ReconnectEvents returns a channel that receives a signal each time the
// transport reconnects after a drop. The channel is buffered (size 1) and
// signals are delivered non-blocking, so a burst of reconnects coalesces
// into one pending signal. The channel is closed when the notifier closes.
ReconnectEvents() <-chan struct{}
}
ReconnectNotifier is implemented by notifiers whose underlying transport can drop and re-establish its subscription (PgEventNotifier's pq.Listener). Consumers subscribe to reconnect events to trigger a resync after a potential notification gap: anything NOTIFYed while the session was down is lost, so hint consumers must assume they missed events. LocalEventNotifier intentionally does not implement it — in-process channels cannot gap.