notifier

package
v0.0.0-...-1cad98a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package notifier provides check notification implementations for different database backends.

Index

Constants

View Source
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

func New(db *bun.DB, dbType string, connString string, logger *slog.Logger) (EventNotifier, error)

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

func (n *LocalEventNotifier) Notify(ctx context.Context, eventType string, payload string) error

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

func (n *PgEventNotifier) Notify(ctx context.Context, eventType string, payload string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址