x/messaging Primer
x/messaging Primer
Section titled “x/messaging Primer”Beta (app-facing service layer) — API is stable within a minor version. Subordinate packages (
x/messaging/mq,x/messaging/pubsub,x/messaging/scheduler,x/messaging/webhook) remain experimental. Check Release Posture and Extension Maturity before adopting in production.
Open this page after x/* Family when the work is clearly about messaging-family ownership instead of the smallest runnable path.
x/messaging is the canonical app-facing entrypoint for queue, pubsub, scheduler, and webhook orchestration at the family level.
Stability and adoption
Section titled “Stability and adoption”Start from x/messaging for family-level decisions, then verify subordinate
package maturity before depending on x/messaging/mq, x/messaging/pubsub, x/messaging/scheduler, or
x/messaging/webhook directly. Check x/messaging/module.yaml,
Release Posture, and
Extension Maturity before production use.
Start here when
Section titled “Start here when”- the task is message send orchestration
- the change is app-facing queue, pubsub, scheduler, or webhook wiring
- the work needs a family-level messaging entrypoint instead of a lower-level primitive
Do not start here when
Section titled “Do not start here when”- the task is application bootstrap
- the work is really stable-root abstraction design
- the task is already known to be narrow low-level work in
x/messaging/mq,x/messaging/pubsub,x/messaging/scheduler, orx/messaging/webhook
First files to read in the current repository
Section titled “First files to read in the current repository”x/messaging/module.yamlx/messaging/entrypoints.gospecs/extension-taxonomy.yaml
Public entrypoints
Section titled “Public entrypoints”Use the family-level aliases and constructors before opening subordinate packages directly:
messaging.NewInProcBrokerplusBrokerMessageandBrokerSubscriptionfor in-process pubsub wiringmessaging.NewWebhookService,messaging.NewWebhookMemStore, andVerifyWebhookHMACfor webhook flowsmessaging.Newfor the app-facing messaging servicemessaging.NewMemReceiptStorefor receipt persistence in examples and testsmessaging.NewLogSMSProvider,NewLogEmailProvider, and HTTP provider constructors for delivery adapters
Concrete ownership examples
Section titled “Concrete ownership examples”Start in x/messaging when the work is about | Drop into a narrower sibling only when the work is already about |
|---|---|
| family-level app-facing queue, pubsub, scheduler, or webhook orchestration | durable queue primitives and worker coordination in x/messaging/mq |
| deciding the messaging entrypoint a service should open first | in-process broker primitives in x/messaging/pubsub |
| keeping orchestration explicit without redefining the canonical app path | scheduling primitives in x/messaging/scheduler |
| messaging-family ownership questions that are still broader than one protocol primitive | inbound verification or outbound delivery mechanics in x/messaging/webhook |
Why this primer exists
Section titled “Why this primer exists”x/messaging matters because it keeps readers from jumping into a sibling package too early. The family entrypoint exists so messaging work can start from the right scope before narrowing.