Custom pub/sub

Use a custom pub/sub backend when subscriptions must share events across processes or use infrastructure that is not provided by the built-in memory backend.

Start with the pubsub.PubSub interface in the API reference. Then define delivery, cancellation, buffering, and failure behavior for your backend.

The interface is:

type PubSub interface {
	Publish(ctx context.Context, topic string, payload []byte) error
	Subscribe(ctx context.Context, topic string) (<-chan Message, error)
	Close() error
}

Message.Payload is opaque to the backend. The publisher must not mutate or reuse the payload after Publish returns. A subscriber that needs to retain or modify bytes must copy them.

Choose the delivery model firstCopy Anchor Link

• An in-memory backend is process-local and best effort.
• A shared backend can deliver events to several service replicas.
• A durable broker can support replay or recovery, but the resolver contract still needs clear behavior for duplicates and disconnected clients.

Document whether your backend guarantees ordering, duplicate suppression, durability, and delivery after a subscriber reconnects.

Backend responsibilitiesCopy Anchor Link

A backend must handle topic ownership, subscriber cancellation, cleanup after disconnects, safe payload ownership, and errors from the underlying broker. Bound channel buffers and backpressure deliberately. Do not let one slow subscriber block unrelated publishers.

For multi-replica deployments, read Deployment and scaling with Realtime subscriptions.