x/messaging/pubsub · x/messaging/mq Primer
x/messaging/pubsub · x/messaging/mq Primer
Section titled “x/messaging/pubsub · x/messaging/mq Primer”Experimental — API compatibility is not frozen. Evaluate before adopting in production. Check Release Posture for current maturity status.
Open this page after x/messaging Primer when the change is narrowly about in-process publish-subscribe broker primitives (x/messaging/pubsub) or durable queue task coordination (x/messaging/mq). Both are subordinate packages within the x/messaging capability family.
x/messaging/pubsub — Publish-Subscribe Broker Primitives
Section titled “x/messaging/pubsub — Publish-Subscribe Broker Primitives”x/messaging/pubsub owns in-process topic fan-out, broker primitives, and debug-friendly broker support. It is consumed by x/messaging, x/messaging/webhook (for pub-sub-to-HTTP bridging), and x/observability/devtools (for local broker inspection).
Start here when
Section titled “Start here when”- you are implementing or modifying topic fan-out broker behavior (
broker.go) - you are adding consumer group coordination or competing-consumer delivery (
consumergroup.go) - you are building acknowledgement, backpressure, or dead-letter queue support (
ack.go,backpressure.go,dlq.go) - you are adding deduplication for in-flight messages (
dedup.go) - you are building a distributed pubsub adapter (
distributed.go)
Do not start here when
Section titled “Do not start here when”- the work is app-facing messaging feature discovery — start from x/messaging Primer
- the change is about HTTP webhook delivery for pubsub events — that belongs in
x/messaging/webhook - the work introduces a global broker registered via package init — brokers must be injected explicitly
First files to read
Section titled “First files to read”x/messaging/pubsub/module.yamlx/messaging/pubsub/broker.gox/messaging/pubsub/consumergroup.gox/messaging/pubsub/ack.go
x/messaging/mq — Durable Queue Primitives
Section titled “x/messaging/mq — Durable Queue Primitives”x/messaging/mq owns durable queue implementations, task persistence, worker coordination, dead-letter handling, and queue deduplication adapters. It provides the queue substrate that x/messaging and x/messaging/scheduler coordinate on top of.
Start here when
Section titled “Start here when”- you are implementing or modifying durable task queue behavior (
broker.go,persistence.go) - you are adding dead-letter queue handling for failed tasks (
deadletter.go) - you are building deduplication adapters for queue tasks (
dedupe.go,dedupe_kv.go,dedupe_sql.go) - you are implementing priority queue scheduling (
priority.go) - you are adding acknowledgement semantics for task delivery (
ack.go)
Do not start here when
Section titled “Do not start here when”- the work is app-facing messaging feature discovery — start from x/messaging Primer
- the change is about cron or delayed job scheduling — that belongs in
x/messaging/scheduler - the work introduces business workflow orchestration — keep that in application code
- the change requires stable root entrypoints
First files to read
Section titled “First files to read”x/messaging/mq/module.yamlx/messaging/mq/broker.gox/messaging/mq/persistence.gox/messaging/mq/deadletter.go
Why this primer covers both packages
Section titled “Why this primer covers both packages”Both x/messaging/pubsub and x/messaging/mq are subordinate to x/messaging. They are different layers: x/messaging/pubsub handles fan-out delivery semantics; x/messaging/mq handles durable task persistence and worker coordination. Separating them prevents coupling — an event that only needs fan-out does not require durable persistence, and a durable task queue does not need topic fan-out semantics unless explicitly bridged.