### Local quickstart: ResizeMedia command with local sync route Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Smallest local command example. Defines a ResizeMedia payload, creates a command, builds a bus with a local sync route, binds a sender, and sends a message. Uses messenger.MustCommand, messenger.JSON, messenger.NewBuilder, messenger.WithSource, HandleCommandFunc, RouteCommand, NewLocalSyncRoute, and BindSender. ```go type ResizeMedia struct { JobID int64 `json:"jobId"` } resize := messenger.MustCommand("media.resize", 1, messenger.JSON[ResizeMedia]()) builder := messenger.NewBuilder(messenger.WithSource("urn:service:media-resizer")) builder.HandleCommandFunc(resize, "media-worker", func(_ context.Context, payload ResizeMedia) error { fmt.Println("resize", payload.JobID) return nil }) builder.RouteCommand(resize, messenger.NewLocalSyncRoute()) bus, _, err := builder.Build() if err != nil { return err } resizeSender := messenger.BindSender(bus, resize) _, err = resizeSender.Send(ctx, ResizeMedia{JobID: 42}) ``` -------------------------------- ### Install optional telemetry and CLI modules Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use these commands to install the optional observability module and the gomessengerctl CLI tool, both at version v0.4.0. ```sh go get github.com/assurrussa/gomessenger/observability@v0.4.0 ``` ```sh go install github.com/assurrussa/gomessenger/tools/gomessengerctl@v0.4.0 ``` -------------------------------- ### Run aggregate version example and regression tests Source: https://github.com/assurrussa/gomessenger/blob/master/docs/kafka.md Runs the aggregate-version example and focused regression tests from the repository root. The tests exercise application decisions and real envelope schema validation, but do not run Kafka, SQL, Inbox attempt accounting, or ACKs. ```sh GOWORK=off go test . -run '^(ExampleDeferAfter_aggregateVersion|TestAggregateVersion)' ``` -------------------------------- ### Selective routing with Outbox and direct brokers Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Go example showing how to mix transactional Outbox and direct broker routes in one builder. Critical events are staged atomically, high-volume telemetry goes directly to JetStream, and local commands run in-memory. ```go builder := messenger.NewBuilder(messenger.WithSource("urn:service:billing")) // 1. Critical event: staged atomically in PostgreSQL transaction (ReceiptStaged) builder.RouteEvent(OrderCreatedEvent, outboxProducer) // 2. High-volume audit/telemetry: published directly to JetStream without DB (ReceiptBrokerConfirmed) builder.RouteEvent(TelemetryMetricEvent, natsDirectRoute) // 3. Local in-process command: executed in-memory via GoBus (ReceiptCompleted) builder.RouteCommand(InvalidateLocalCache, messenger.NewLocalSyncRoute()) ``` -------------------------------- ### Run atomic-inbox-outbox example Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Runs the example command against a disposable PostgreSQL database. Requires GOMESSENGER_POSTGRES_DSN and GOWORK=off. Creates the gomessenger_atomic_example schema, applies migrations, and retains proof rows; never drops or truncates data. Can be repeated with fresh input identity. ```sh GOMESSENGER_POSTGRES_DSN='postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable' \ GOWORK=off go run ./cmd/atomic-inbox-outbox ``` -------------------------------- ### Run git diff --check Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Confirms that public docs contain no machine-local paths or development-only replace examples. ```text git diff --check ``` -------------------------------- ### Prepare transports layer for v0.4.0 with Outbox v0.17.0 Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Run these commands to prepare the transports (adapters/nats and adapters/kafka) plus the checkout-only E2E fixture's already-published root, Inbox and selected Outbox root/SQLite prerequisites. The fixture keeps its GoMessenger path replacements; other adapter requirements, the CLI, the external consumer and the durable example wait until the final layer. ```sh make release-ready VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=transports make release-readiness VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=transports make check ``` -------------------------------- ### Run Kafka publish comparison test Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/kafka-publish-comparison.md Command to reproduce the Kafka publish comparison from a clean checkout. Requires Go from go.work and Docker. Starts and removes disposable Kafka containers sequentially. ```sh KAFKA_TEST_MODE=publish-comparison make test-kafka ``` -------------------------------- ### Install GoMessenger with Kafka, Inbox, and Outbox adapters Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use this command to install the core module along with the Kafka, Inbox, and Outbox adapters for durable delivery with transactional Outbox integration. ```sh go get github.com/assurrussa/gomessenger@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/inbox@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/kafka@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/outbox@v0.4.0 ``` -------------------------------- ### Install GoMessenger for local commands, queries, and events Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use this command to install the core GoMessenger module for process-local messaging. Requires Go 1.27+. ```sh go get github.com/assurrussa/gomessenger@v0.4.0 ``` -------------------------------- ### Install GoMessenger with NATS JetStream, Inbox, and Outbox adapters Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use this command to install the core module along with the NATS, Inbox, and Outbox adapters for durable delivery with transactional Outbox integration. ```sh go get github.com/assurrussa/gomessenger@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/inbox@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/nats@v0.4.0 \ github.com/assurrussa/gomessenger/adapters/outbox@v0.4.0 ``` -------------------------------- ### Inspect and build local GoMessenger checkout with go.work Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Builds the example using the local GoMessenger checkout via the repository's go.work, while remaining dependencies are module-resolved. The workspace selects local GoMessenger modules but does not select a sibling Outbox checkout. Use go list -m all for the selected graph and go version -m on the exact binary for embedded versions and replacements. ```shell # Local GoMessenger checkout with the remaining dependencies module-resolved. ( set -e export GOWORK="$(pwd)/go.work" cd examples/durable-postgres-nats go list -m all go build -o gomessenger-durable-postgres-nats . go version -m ./gomessenger-durable-postgres-nats ) ``` -------------------------------- ### Run durable PostgreSQL + NATS demo Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Command to run the durable PostgreSQL + NATS demo. The example performs business write and Outbox stage in one PostgreSQL transaction, relays through JetStream, retries intentional handler failure, suppresses duplicate delivery, moves permanent failure to DLQ, and confirms replay. Default Docker build uses GOWORK=off. ```sh make demo-durable-postgres-nats ``` -------------------------------- ### Clone and test the current checkout Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use these commands to evaluate unreleased changes from the current checkout. The v0.4.0 Outbox adapter requires Outbox v0.17.0; the host selects and installs its matching database backend separately. ```sh git clone https://github.com/assurrussa/gomessenger.git ``` ```sh cd gomessenger ``` ```sh GOWORK=off go test ./... ``` -------------------------------- ### Inspect and build published-module graph with GOWORK=off Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Builds the example using the published module graph (GOWORK=off) and inspects the selected dependencies and embedded versions. The go.mod declares GoMessenger root, Inbox, NATS, and Outbox adapter v0.4.0, with Outbox root and PostgreSQL backend v0.17.0. Use go list -m all for the selected graph and go version -m on the exact binary for embedded versions and replacements. ```shell # Published-module graph with the declared Outbox root/PostgreSQL v0.17.0 tags. ( set -e cd examples/durable-postgres-nats export GOWORK=off go list -m all go build -o gomessenger-durable-postgres-nats . go version -m ./gomessenger-durable-postgres-nats ) ``` -------------------------------- ### Create batch producer and publish message batch Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use NewBatchProducer to stage an ordered set atomically in the caller's business transaction. Direct broker and local routes return ErrUnsupportedCapability from the batch facade. The example builds a messenger with a source and routes an event to the producer, then publishes a batch of two outgoing messages. ```go producer, err := outboxadapter.NewBatchProducer(outboxService, outboxadapter.ProducerConfig{ Name: "orders-outbox", }) if err != nil { return err } builder := messenger.NewBuilder(messenger.WithSource("urn:service:orders")) builder.RouteEvent(orderCreated, producer) app, _, err := builder.Build() if err != nil { return err } receipts, err := app.PublishMessageBatch(ctx, orderCreated, []messenger.Outgoing[OrderCreated]{ {Payload: first, Metadata: messenger.OutgoingMetadata{ID: firstID}}, {Payload: second, Metadata: messenger.OutgoingMetadata{ID: secondID}}, }) ``` -------------------------------- ### Run capacity frontier with normalized one-cell controller Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/README.md Starts a clean checkout and runs the normalized one-cell controller that searches a maximum sustainable rate by geometric ladder and 50 msg/s bisection, then requires three fresh-volume confirmations. Uses the full-batch variant, o2-c2 topology, small payload profile, and stock PostgreSQL profile. ```shell CAPACITY_FRONTIER_VARIANT=full-batch \ CAPACITY_FRONTIER_TOPOLOGY=o2-c2 \ CAPACITY_PAYLOAD_PROFILE=small \ CAPACITY_POSTGRES_PROFILE=stock \ make capacity-frontier ``` -------------------------------- ### Run schema check with baseline and SHA-256 Source: https://github.com/assurrussa/gomessenger/blob/master/docs/schema-baselines.md Manual example from tools/gomessengerctl. Checks a schema against a baseline file and its pinned SHA-256 digest. The expected document fingerprint for event/media.processed/v1 is 05a8b3cd9ea49d734240e3acd6daea223fe78615424c77be55265127872cb57e, with one preserved version and two candidate samples. ```sh go run . schema check \ --manifest testdata/schema/manifest.json \ --file testdata/schema/baseline.json \ --baseline testdata/schema/baseline.json \ --baseline-sha256 ed6467e74ea1fd496721d1d71e0f5a82592302d10afec2b5b4c035af36c5bb56 ``` -------------------------------- ### Catalog JSON example Source: https://github.com/assurrussa/gomessenger/blob/master/docs/schema-baselines.md Shows the required structure for a schema baseline catalog. The descriptor must include kind, name, schemaVersion, contentType, dataEncoding, schema URI, and an inline JSON Schema document. Samples are optional and must validate against the document. ```json { "specVersion": "1.0", "policy": "immutable-version-v1", "descriptors": [{ "kind": "event", "name": "media.processed", "schemaVersion": 1, "contentType": "application/json", "dataEncoding": "json", "schema": "urn:example:media.processed:1", "document": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {"mediaId": {"type": "string"}}, "required": ["mediaId"], "additionalProperties": false }, "samples": [{"mediaId": "media-1"}] }] } ``` -------------------------------- ### Finalize graph for v0.4.0 with Outbox v0.17.0 Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Run these commands to finalize the graph. The final layer aligns every GoMessenger requirement, removes development replacements from all published modules, the external consumer fixture and durable example, and adds matching local replacements to go.work. It requires root, Inbox, Outbox adapter, observability, NATS and Kafka tags plus the selected Outbox root/backend tags to resolve first. ```sh make release-ready VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 make release-readiness VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 make check ``` -------------------------------- ### Frontier mode combinations Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Lists the four mode combinations used by the frontier controller, named legacy, consumer-batch, relay-batch, and full-batch. Starts at 250 msg/s with a 100 msg/s fallback, climbs geometrically, bisects to a 50 msg/s step, and confirms the best candidate in three fresh-volume runs. ```sh OUTBOX_INGRESS_MODE=single OUTBOX_RELAY_MODE=single CONSUMER_MODE=single OUTBOX_INGRESS_MODE=single OUTBOX_RELAY_MODE=single CONSUMER_MODE=batch OUTBOX_INGRESS_MODE=single OUTBOX_RELAY_MODE=batch CONSUMER_MODE=batch OUTBOX_INGRESS_MODE=batch OUTBOX_RELAY_MODE=batch CONSUMER_MODE=batch ``` -------------------------------- ### Validate, plan, and apply Kafka topology with gomessengerctl Source: https://github.com/assurrussa/gomessenger/blob/master/docs/kafka.md Run these commands in order to validate, plan, and apply the topology from docs/examples/kafka-topology.json. Planning is read-only; apply may create topics or make monotonic increases to managed settings. A plan containing a conflict exits with code 3. ```sh gomessengerctl kafka topology validate --file docs/examples/kafka-topology.json gomessengerctl kafka topology plan \ --file docs/examples/kafka-topology.json \ --brokers kafka-1:9092,kafka-2:9092 \ --instance-id ops-host-a gomessengerctl kafka topology apply \ --file docs/examples/kafka-topology.json \ --brokers kafka-1:9092,kafka-2:9092 \ --instance-id ops-host-a ``` -------------------------------- ### Run make bench-all Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Runs benchmarks for dispatch, envelope, registry, or admission-path changes. The benchmark workflow records ten base/head samples, uploads raw data, and adds a pinned benchstat report without enforcing a machine-dependent performance threshold. ```text make bench-all ``` -------------------------------- ### Run Development and Verification Commands Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Use these commands to prepare the workspace, run checks, tests, and benchmarks. `make check-workspace` is the maximal pre-publication source gate covering all modules, static lint, race and checkptr builds, a 90% root coverage gate, and Docker-free durable pipeline E2E. `make test-e2e` reruns only the full Outbox-to-JetStream-to-Inbox path using embedded JetStream. `make test-kafka` is the local Docker entry point against Apache Kafka 4.1.2 and 4.3.1 images in KRaft mode. `make test-postgres` requires setting `GOMESSENGER_POSTGRES_DSN`. ```sh make prepare make check-workspace make test-e2e make test-integration make test-batch-integration make test-kafka GOMESSENGER_POSTGRES_DSN='postgres://...' make test-postgres make bench-all ``` -------------------------------- ### Run quick capacity profile Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Runs the quick capacity profile from the repository root using make capacity-nats. ```sh make capacity-nats ``` -------------------------------- ### Run make check-workspace Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Runs the Docker-free transactional Outbox-to-JetStream-to-Inbox E2E under the race detector. This command proves the local GoMessenger workspace graph. ```text make check-workspace ``` -------------------------------- ### Define and use a local typed query with Query[Q,R] Source: https://github.com/assurrussa/gomessenger/blob/master/docs/usage.md Shows how to define a query type and its result, create a query with MustQuery, build a handler, route it locally, and execute it. Requires exactly one handler and one LocalQueryRoute. Only LocalSyncRoute and LocalAsyncRoute are allowed. Messenger.Query waits for one result; the async route adds admission and backpressure but no public QueryAsync. ```go type FindOrder struct{ OrderID string } type OrderView struct { OrderID string Status string } findOrder := messenger.MustQuery[FindOrder, OrderView]( "orders.find", 1, messenger.JSON[FindOrder](), ) builder := messenger.NewBuilder(messenger.WithSource("urn:service:orders")) builder.HandleQueryFunc(findOrder, "orders.reader", func(ctx context.Context, query FindOrder) (OrderView, error) { return orderRepository.Find(ctx, query.OrderID) }) builder.RouteQuery(findOrder, messenger.NewLocalSyncRoute()) bus, _, err := builder.Build() if err != nil { return err } reader := messenger.BindQuerier(bus, findOrder) view, err := reader.Query(ctx, FindOrder{OrderID: "order-42"}) ``` -------------------------------- ### Run local method-call benchmarks Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Reproduces the benchmark snapshot for the synchronous local public path. Uses GOWORK=off and runs only BenchmarkMessengerLocal with benchmem and count=10. ```sh GOWORK=off go test -run '^$' -bench '^BenchmarkMessengerLocal' -benchmem -count=10 . ``` -------------------------------- ### Run make test-integration Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Reruns embedded JetStream/SQLite adapters and the durable pipeline. ```text make test-integration ``` -------------------------------- ### Compose transport, route, and consumer Source: https://github.com/assurrussa/gomessenger/blob/master/docs/kafka.md Shows how to create a Kafka transport, route, and event consumer, then build a messenger bus. The transport is configured with brokers, client ID, instance ID, logger, and connection options. The route is created with a namespace. The consumer uses a handler config with concurrency, timeout, and max attempts. The builder registers the transport and route, and builds the bus and runtime. ```go transport, err := kafkaadapter.NewTransport(kafkaadapter.TransportConfig{ Name: "kafka.orders", Brokers: []string{"kafka-1:9092", "kafka-2:9092"}, ClientID: "billing-service", InstanceID: hostInstanceID, Logger: messenger.AdaptSlog(slog.Default()), ConnectionOptions: []kafkaadapter.ConnectionOption{ kafkaadapter.DialTLSConfig(tlsConfig), kafkaadapter.SASL(saslMechanism), }, }) if err != nil { return err } route, err := kafkaadapter.NewRoute(transport, kafkaadapter.RouteConfig{ Name: "kafka.orders", Namespace: "prod", }) if err != nil { return err } consumer, err := kafkaadapter.NewEventConsumer( transport, inboxStore, contracts.OrderCreated, handleOrderCreated, kafkaadapter.HandlerConfig{ Namespace: "prod", ConsumerID: "billing-order-projector", Concurrency: 8, Timeout: 30 * time.Second, MaxAttempts: 5, }, ) if err != nil { return err } builder := messenger.NewBuilder(messenger.WithSource("urn:service:billing")) builder.Use(transport.Name(), transport) builder.RouteEvent(contracts.OrderCreated, route) builder.Use("consumer.billing-order-projector", consumer) bus, runtime, err := builder.Build() ``` -------------------------------- ### Prepare modules layer for v0.4.0 with Outbox v0.17.0 Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Run these commands to prepare the root-dependent modules (adapters/inbox, adapters/outbox, observability). This layer updates and removes development replacements, and advances the checkout-only E2E fixture's root requirement and selected Outbox root/SQLite pair to their already-published versions. ```sh make release-ready VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=modules make release-readiness VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=modules make check ``` -------------------------------- ### Configure middleware, logging, and tracing with builder Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Sets up a messenger builder with a slog adapter, source, logging observer, and trace context propagator, then registers a global middleware that simply calls next. Registration order determines execution order; the first middleware is outermost. Logging is disabled by default; AdaptSlog(nil) is a safe no-op, while WithLogger(nil) is a configuration error. ```go logger := messenger.AdaptSlog(slog.Default()) builder := messenger.NewBuilder( messenger.WithSource("urn:service:media-resizer"), messenger.WithLogger(logger), messenger.WithObserver(messenger.NewLoggingObserver(logger)), messenger.WithContextPropagator(observability.NewTraceContextPropagator()), ) builder.UseMiddleware(func( ctx context.Context, metadata messenger.Metadata, handlerID string, next messenger.HandlerFunc, ) error { return next(ctx) }) ``` -------------------------------- ### Prepare root layer for v0.4.0 with Outbox v0.17.0 Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Run these commands to prepare the root module for release. The root layer verifies published Outbox prerequisites, checks that the facade has no replacement, and tidies only the root module. The Makefile's release-ready target formats Go files across the checkout, excluding tmp; inspect any resulting changes. ```sh make release-ready VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=root make release-readiness VERSION=v0.4.0 OUTBOX_VERSION=v0.17.0 RELEASE_LAYER=root make check-workspace ``` -------------------------------- ### Register outbox relay and producer, then publish in transaction Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Sets up the NATS route, registers the outbox relay job, creates the outbox producer, and publishes inside a transaction. The repository write must use txCtx; the producer stages the envelope and the relay publishes it later. ```go natsRoute, err := natsadapter.NewRoute(natsConnection, natsadapter.RouteConfig{ Name: "nats.integration-events", Namespace: "prod", WireMode: natsadapter.WireNative, }) if err != nil { return err } relay, err := outboxadapter.NewRelayJob(natsRoute, outboxadapter.RelayJobConfig{}) if err != nil { return err } if err := outboxRuntime.Service().RegisterJob(relay); err != nil { return err } route, err := outboxadapter.NewProducer( outboxRuntime.Service(), outboxadapter.ProducerConfig{Name: "outbox.integration-events"}, ) if err != nil { return err } builder := messenger.NewBuilder( messenger.WithSource("urn:service:media-resizer"), ) builder.RouteEvent(mediaResized, route) bus, _, err := builder.Build() if err != nil { return err } err = outboxRuntime.Transactor().RunInTx(ctx, func(txCtx context.Context) error { if err := mediaRepository.Save(txCtx, media); err != nil { return err } _, err := bus.Publish(txCtx, mediaResized, MediaResized{JobID: media.ID}) return err }) ``` -------------------------------- ### Run batch proof and verdict Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Commands for the fixed PostgreSQL 18/NATS o2-c2 proof used for merge-decision claims about true Outbox batching. Requires clean GoMessenger and sibling Outbox checkouts. Compares consumer-batch with relay-batch and legacy with full-batch for small and mixed payloads, requires a 1.3x frontier ratio, and checks matched common-rate latency, PostgreSQL cost, actual batch sizes, resource use, and WAL waits. The launcher first runs Outbox make check-all and GoMessenger make check-workspace plus make test-batch-integration. Raw reports remain under ignored tmp/capacity/; after PASS, the compact Markdown verdict is copied to docs/performance/.md. ```sh make capacity-batch-proof make capacity-batch-proof-verdict \ PROOF_DIR=tmp/capacity/frontiers/ ``` -------------------------------- ### gomessengerctl CLI commands for schema, topology, and DLQ operations Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Lists the primary CLI commands for schema checking, manifest/topology validation, planning, applying, and DLQ inspection/replay for both NATS and Kafka. The topology plan command exits with code 3 when the plan contains a conflict. DLQ replay is offline by default and requires --confirm to republish; it does not support subject substitution, record deletion, or payload/header output. ```sh gomessengerctl schema check --manifest manifest.json --file schemas.json --baseline baseline.json --baseline-sha256 HEX gomessengerctl manifest validate --file manifest.json gomessengerctl topology validate --file topology.json gomessengerctl topology plan --file topology.json --server nats://localhost:4222 gomessengerctl topology apply --file topology.json --server nats://localhost:4222 gomessengerctl dlq inspect --file record.json gomessengerctl dlq replay --file record.json gomessengerctl dlq replay --file record.json --confirm --server nats://localhost:4222 gomessengerctl kafka topology validate --file kafka-topology.json gomessengerctl kafka topology plan --file kafka-topology.json --brokers localhost:9092 --instance-id ops-a gomessengerctl kafka topology apply --file kafka-topology.json --brokers localhost:9092 --instance-id ops-a gomessengerctl kafka dlq inspect --file kafka-record.json gomessengerctl kafka dlq replay --file kafka-record.json gomessengerctl kafka dlq replay --file kafka-record.json --confirm --brokers localhost:9092 --instance-id ops-a ``` -------------------------------- ### Reproduce historical pool A/B topology matrix Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/README.md Run the capacity matrix for the historical pool A/B topology. The script checks for a clean git status, prints the current HEAD, and iterates over pool configurations (9:1 and 8:2), rates (1000, 1500, 2000), and three runs each, invoking `make capacity-nats-site` with environment variables. Each run takes at least two minutes of precondition, waits for a checkpoint within five minutes, measures for two minutes, and drains within 60 seconds. ```bash test -z "$(git status --porcelain)" git rev-parse HEAD for pool in 9:1 8:2; do producer_connections="${pool%:*}" relay_connections="${pool#*:}" for rate in 1000 1500 2000; do for run in 1 2 3; do env \ CAPACITY_RUN_ID="v0.2.2-performance-batch16-producer${producer_connections}-relay${relay_connections}-${rate}-r${run}" \ CAPACITY_RATES="${rate}" \ CAPACITY_MIN_RATE="${rate}" \ OUTBOX_WORKERS=2 \ OUTBOX_RESERVATION_BATCH_SIZE=16 \ NATS_CONSUMER_CONCURRENCY=2 \ OUTBOX_PRODUCER_MAX_CONNS="${producer_connections}" \ OUTBOX_RELAY_MAX_CONNS="${relay_connections}" \ DB_MAX_OPEN_CONNS=10 \ make capacity-nats-site done done done ``` -------------------------------- ### Run fixed-rate capacity release verification with 200ms p95 SLO Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/release-verification.md Run from a clean GoMessenger checkout with Bash. Tests the stronger 200 ms p95 claim; the general capacity runner defaults to a 2-second p95 SLO. A failure at 200 ms is a failed latency claim even when integrity reconciles. The o2-c2 profile fixes two Outbox workers, two consumer invocations, producer/relay pools of 6+2, and an Inbox pool of 8. Each cell has two minutes of precondition, waits for the required checkpoint, measures for two minutes, and allows up to one minute of drain. Budget at least 24 minutes of warm-up/measurement for six cells, plus checkpoint waiting, builds, startup, and drain. The first failed cell stops the command and retains its artifacts for diagnosis. ```bash set -euo pipefail test -z "$(git status --porcelain)" test -z "$(git -C ../outbox status --porcelain)" git rev-parse HEAD git -C ../outbox rev-parse HEAD release_capacity_id="v0.3.0-1500-p95-200-$(date -u +%Y%m%dT%H%M%SZ)" release_capacity_root="$(pwd)/tmp/capacity/releases/${release_capacity_id}" for repetition in 1 2 3; do for payload in small mixed; do CAPACITY_RUN_ID="${release_capacity_id}-${payload}-r${repetition}" \ CAPACITY_RESULTS_ROOT="${release_capacity_root}" \ CAPACITY_CELL_RATE=1500 \ CAPACITY_MIN_RATE=1500 \ CAPACITY_CELL_VARIANT=full-batch \ CAPACITY_CELL_TOPOLOGY=o2-c2 \ CAPACITY_PAYLOAD_PROFILE="${payload}" \ CAPACITY_POSTGRES_PROFILE=stock \ CAPACITY_PRECONDITION_DURATION=120s \ CAPACITY_MEASURED_DURATION=120s \ CAPACITY_DRAIN_TIMEOUT=60s \ CAPACITY_E2E_P95_SLO=200ms \ CAPACITY_OUTBOX_BATCH_MAX_MESSAGES=100 \ CAPACITY_CONSUMER_BATCH_MAX_MESSAGES=100 \ bash scripts/run-capacity-cell.sh done done printf 'Capacity evidence: %s\n' "${release_capacity_root}" ``` -------------------------------- ### Minimal local query with messenger.MustQuery and NewLocalSyncRoute Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Defines query and view types, builds a messenger with a source, registers a query handler and a local sync route, then binds a querier and executes a query. Requires Go 1.27. The async route uses the caller context for admission, execution, and waiting, so cancellation returns ctx.Err(). ```go type FindArticle struct{ ID int64 } type ArticleView struct { ID int64 Title string } findArticle := messenger.MustQuery[FindArticle, ArticleView]( "article.find", 1, messenger.JSON[FindArticle](), ) builder := messenger.NewBuilder(messenger.WithSource("urn:service:catalog")) builder.HandleQueryFunc(findArticle, "article-reader", func(_ context.Context, query FindArticle) (ArticleView, error) { return ArticleView{ID: query.ID, Title: "CQRS in Go"}, nil }) builder.RouteQuery(findArticle, messenger.NewLocalSyncRoute()) bus, _, err := builder.Build() if err != nil { return err } reader := messenger.BindQuerier(bus, findArticle) article, err := reader.Query(ctx, FindArticle{ID: 42}) ``` -------------------------------- ### Compile and helper gate for NATS process tests Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/nats-process-operations.md Run from the repository root to compile and check small regressions before authorizing load. Keep operations opt-in and private helper environment variables unset, and keep GOMESSENGER_KAFKA_BROKERS unset. Do not add -race to the measured command; this helper uses race and includes a tiny local SQLite regression. ```sh cd testdata/e2e GOWORK=off go test -race -count=1 -timeout 5m -run '^TestNATSProcess(FixedAcceptance|ChildEnvironment|EffectIdentity|SaturationCriteria|P95|LoadSettled|CampaignReconciliation|WorkerProgress|ReportReservation|ExitedChild|ReportPaths|LedgerRoot)' ./... GOWORK=off golangci-lint run --timeout=5m --config ../../.golangci.yml ./... ``` -------------------------------- ### Run all companion regressions Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Runs all companion regressions from the repository root. Fails if the DSN is absent. Live tests create isolated temporary schemas and clean up only their own schema. ```sh GOMESSENGER_POSTGRES_DSN='postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable' \ make test-postgres-atomic ``` -------------------------------- ### Verify Published Release Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Run this command after all dependency-ordered module tags exist to verify a published release separately. ```sh make test-consumer-release VERSION=vX.Y.Z ``` -------------------------------- ### Commands to run for each nested module before tagging Source: https://github.com/assurrussa/gomessenger/blob/master/docs/release.md Run these commands after the module's dependencies resolve. Inspect and commit any go.sum update in a reviewed layer, and only then create the tag. GOWORK=off is used to avoid workspace mode. ```sh cd MODULE_DIRECTORY GOWORK=off go mod tidy GOWORK=off go test ./... git diff --check ``` -------------------------------- ### Apply Inbox migrations and create store Source: https://github.com/assurrussa/gomessenger/blob/master/docs/usage.md Applies additive Inbox migrations and creates the Inbox store. The host must create the PostgreSQL schema and grant access before migration. Both backends default to the 'gomessenger_' prefix; SQLite accepts WithTablePrefix but has no schema option. Always pass the same namespace options to Migrate and New. ```go const consumerConcurrency = 8 database.SetMaxOpenConns(consumerConcurrency + 4) inboxOptions := []inboxpgsql.Option{ inboxpgsql.WithSchema("messaging"), inboxpgsql.WithTablePrefix("site_"), } if err := inboxpgsql.Migrate(ctx, database, inboxOptions...); err != nil { return err } inboxStore, err := inboxpgsql.New(database, inboxOptions...) if err != nil { return err } ``` -------------------------------- ### Finalize and Check Complete Graph Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Run these commands after the root, Inbox, NATS, and Kafka tags resolve through the Go proxy. `release-ready` is the final-layer command; do not run it before the dependency tags exist. `make check` runs the same gate as `make check-workspace` but with `GOWORK=off` and intentionally remains blocked while a required contract has not been published and pinned. ```sh make release-ready VERSION=vX.Y.Z OUTBOX_VERSION=v0.17.0 make release-readiness VERSION=vX.Y.Z OUTBOX_VERSION=v0.17.0 make check ``` -------------------------------- ### Capacity experiment make targets Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Opt-in open-loop NATS capacity experiment commands over HTTP -> business transaction + Outbox -> JetStream -> Inbox -> business projection. Includes normalized frontier commands using PostgreSQL 18 and a PostgreSQL-only command isolating the Inbox ProcessAttempt transaction. ```sh make capacity-nats make capacity-nats-site make capacity-nats-site-single make capacity-nats-site-batch-1 make capacity-nats-site-batch-100 make capacity-frontier make capacity-frontier-matrix make capacity-inbox-postgres ``` -------------------------------- ### Capacity experiment pipeline overview Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Shows the end-to-end flow of the capacity experiment: k6 constant-arrival-rate HTTP POST to /orders or /orders/batch, then PostgreSQL transaction with orders rows and Outbox jobs, JetStream PubAck, PostgreSQL Inbox transaction, and unique order_projection business effect. ```text k6 constant-arrival-rate HTTP POST /orders or /orders/batch -> orders rows + Outbox jobs in one PostgreSQL transaction -> JetStream PubAck -> PostgreSQL Inbox transaction -> unique order_projection business effect ``` -------------------------------- ### Runtime lifecycle with signal handling and graceful shutdown Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Run managed services under the host supervisor, close admission on signal, and wait for accepted work within a 15-second deadline. Uses signal.NotifyContext for os.Interrupt and syscall.SIGTERM. Never call Shutdown from a handler executing on the same runtime. ```go signalCtx, stopSignals := signal.NotifyContext( context.Background(), os.Interrupt, syscall.SIGTERM, ) defer stopSignals() runErr := make(chan error, 1) go func() { runErr <- runtime.Run(context.Background()) }() select { case err := <-runErr: return err case <-signalCtx.Done(): } runtime.BeginDrain() shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) defer cancel() if err := runtime.Shutdown(shutdownCtx); err != nil { return err } return <-runErr ``` -------------------------------- ### Run capacity experiment quick profiles Source: https://github.com/assurrussa/gomessenger/blob/master/docs/e2e.md Runs the quick capacity profiles for the full POST /orders -> business transaction + Outbox -> JetStream -> Inbox -> order_projection path. The controller uses k6 constant-arrival-rate, performs a separate warm-up, samples stage-local progress plus PostgreSQL waits and JetStream state each second, drains after every stage, and stops at the first unsustainable rate. ```sh make capacity-nats make capacity-nats-site make capacity-frontier make capacity-frontier-matrix make capacity-inbox-postgres ``` -------------------------------- ### Equivalent docker compose command for durable demo Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Equivalent to the make target, runs the compose stack with build and abort-on-container-exit. Requires Docker with Compose v2. ```sh docker compose -f examples/durable-postgres-nats/compose.yaml \ up --build --abort-on-container-exit --exit-code-from demo ``` -------------------------------- ### Run merge-decision proof and verdict Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/README.md Runs the merge-decision proof that fixes the normalized o2-c2/stock profile, builds small and mixed frontiers for all four variants, and runs three interleaved repetitions at 80% of the lowest frontier rounded down to 50 msg/s. The verdict command requires PROOF_DIR pointing to the frontier directory. ```shell make capacity-batch-proof ``` ```shell make capacity-batch-proof-verdict \ PROOF_DIR=tmp/capacity/frontiers/ ``` -------------------------------- ### Create NATS route, relay job, and outbox producer Source: https://github.com/assurrussa/gomessenger/blob/master/docs/usage.md Sets up the broker-confirmed route, registers the relay capability on the Outbox service, and creates the staging route. The default relay job name and schema used by NewRelayJob match the defaults used by NewProducer. ```go natsRoute, err := natsadapter.NewRoute(natsConnection, natsadapter.RouteConfig{ Name: "nats.integration-events", Namespace: "prod", WireMode: natsadapter.WireNative, }) if err != nil { return err } relayJob, err := outboxadapter.NewRelayJob( natsRoute, outboxadapter.RelayJobConfig{}, ) if err != nil { return err } if err := outboxRuntime.Service().RegisterJob(relayJob); err != nil { return err } outboxRoute, err := outboxadapter.NewProducer( outboxRuntime.Service(), outboxadapter.ProducerConfig{Name: "outbox.integration-events"}, ) if err != nil { return err } builder := messenger.NewBuilder( messenger.WithSource("urn:service:order-service"), ) builder.RouteEvent(contracts.OrderCreated, outboxRoute) bus, _, err := builder.Build() if err != nil { return err } ``` -------------------------------- ### Run Outbox-only batch screen Source: https://github.com/assurrussa/gomessenger/blob/master/docs/performance/README.md Runs the first Outbox-only A/B comparing singleton Outbox ingress/relay (consumer-batch) with batch ingress/relay (full-batch) while keeping the batch consumer identical. The screen runs one mixed-payload cell per variant at 1,500 msg/s with 30s warm-up, 60s measured load, and 30s drain limit. ```shell make capacity-outbox-batch-screen ``` -------------------------------- ### Fast Outbox-only development comparison Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Runs a fast Outbox-only development comparison. Holds the consumer in batch mode and compares singleton Outbox ingress and relay (consumer-batch) with batch ingress and relay (full-batch). Default is one mixed cell per variant at 1,500 msg/s, with 30 seconds warm-up and 60 seconds measured load. Artifacts are marked development-screen and SCREEN_ONLY; dirty checkout provenance is retained. ```sh make capacity-outbox-batch-screen ``` -------------------------------- ### Run manual focused checks from tools/gomessengerctl Source: https://github.com/assurrussa/gomessenger/blob/master/docs/schema-baselines.md Verification commands for the schema module. Run from tools/gomessengerctl. Includes go mod tidy, targeted tests, race detector, and a fuzz test. These are verification instructions, not a record that the source candidate has passed them. ```sh GOWORK=off go mod tidy GOWORK=off go test -run 'TestSchema|TestStrictJSONRejectsUnknownFields|TestManifestAndTopologyOfflineValidation' . GOWORK=off go test -race . GOWORK=off go test -run '^$' -fuzz '^FuzzSchemaCatalog$' -fuzztime=10s . ``` -------------------------------- ### Supervise runtime with signal context and bounded drain Source: https://github.com/assurrussa/gomessenger/blob/master/docs/usage.md Sets up a signal context for SIGINT/SIGTERM, runs the runtime in a goroutine, waits for either a runtime error or a signal, then begins draining and shuts down with a 15-second timeout. Coordinate shutdown outside handlers running on the same runtime. ```go signalCtx, stopSignals := signal.NotifyContext( context.Background(), os.Interrupt, syscall.SIGTERM, ) defer stopSignals() runErr := make(chan error, 1) go func() { runErr <- runtime.Run(context.Background()) }() select { case err := <-runErr: return err // a managed service stopped unexpectedly case <-signalCtx.Done(): } runtime.BeginDrain() shutdownCtx, cancelShutdown := context.WithTimeout( context.Background(), 15*time.Second, ) defer cancelShutdown() if err := runtime.Shutdown(shutdownCtx); err != nil { return err } return <-runErr ``` -------------------------------- ### Create batch JetStream consumer with keyed results Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Uses NewBatchEventConsumer to process messages in batches, returning one keyed result per message and applying only the successful subset. The handler classifies the complete batch before writing successes. BatchConfig defaults to 100 messages, 4 MiB canonical bytes, and 25 ms. ```go batchConsumer, err := natsadapter.NewBatchEventConsumer( natsConnection, store, mediaResized, func(ctx context.Context, messages []messenger.Message[MediaResized]) (messenger.BatchResult, error) { result := messenger.BatchResult{Items: make([]messenger.BatchItemResult, len(messages))} successes := make([]messenger.Message[MediaResized], 0, len(messages)) for i, message := range messages { itemErr := validateMedia(message.Payload) result.Items[i] = messenger.BatchItemResult{ Key: messenger.BatchItemKey{Source: message.Metadata.Source, MessageID: message.Metadata.ID}, Err: itemErr, } if itemErr == nil { successes = append(successes, message) } } tx, ok := inbox.SQLTxFromContext(ctx) if !ok { return messenger.BatchResult{}, errors.New("missing inbox transaction") } if err := projection.ApplyBatchTx(ctx, tx, successes); err != nil { return messenger.BatchResult{}, err } return result, nil }, natsadapter.HandlerConfig{ Stream: "MESSAGES", Namespace: "prod", ConsumerID: "media-batch-projection", WireMode: natsadapter.WireNative, Concurrency: 4, Timeout: 30 * time.Second, AckWait: 30 * time.Second, MaxAttempts: 10, DLQSubject: "prod.dlq", }, messenger.BatchConfig{}, // 100 messages, 4 MiB canonical bytes, 25 ms ) ``` -------------------------------- ### Capacity profile variants Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Lists useful make targets and environment variable overrides for capacity experiments, including full profiles, frontier profiles, batch proofs, and down commands. ```sh make capacity-nats-full make capacity-nats-site make capacity-frontier make capacity-frontier-matrix make capacity-outbox-batch-screen make capacity-batch-proof make capacity-inbox-postgres CAPACITY_RATES=500 make capacity-nats CAPACITY_MIN_RATE=500 make capacity-nats make capacity-nats-down make capacity-inbox-postgres-down ``` -------------------------------- ### Create durable JetStream consumer with SQL inbox Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Sets up a durable NATS JetStream consumer with a SQL inbox, explicit concurrency and retry bounds, and a handler that applies a projection within the inbox transaction. Requires running inboxpgsql.Migrate before constructing the consumer. Each active worker holds one SQL transaction for the full handler invocation. ```go if err := inboxpgsql.Migrate(ctx, database); err != nil { return err } store, err := inboxpgsql.New(database) if err != nil { return err } consumer, err := natsadapter.NewEventConsumer( natsConnection, store, mediaResized, func(ctx context.Context, message messenger.Message[MediaResized]) error { tx, ok := inbox.SQLTxFromContext(ctx) if !ok { return errors.New("missing inbox transaction") } return projection.ApplyTx(ctx, tx, message.Metadata.ID.String(), message.Payload) }, natsadapter.HandlerConfig{ Stream: "MESSAGES", Namespace: "prod", ConsumerID: "media-projection", WireMode: natsadapter.WireNative, Concurrency: 8, Timeout: 30 * time.Second, FinalizationTimeout: 5 * time.Second, AckWait: 30 * time.Second, MaxAttempts: 10, DLQSubject: "prod.dlq", }, ) if err != nil { return err } consumerBuilder := messenger.NewBuilder( messenger.WithSource("urn:service:media-projection"), ) consumerBuilder.Use("consumer.media-projection", consumer) _, runtime, err := consumerBuilder.Build() if err != nil { return err } ``` -------------------------------- ### Route interface for custom adapters Source: https://github.com/assurrussa/gomessenger/blob/master/README.md Defines the minimal route boundary for delivering a single message. Implement this interface to create custom adapters without modifying GoMessenger. ```go type Route interface { Name() string Deliver(ctx context.Context, delivery Delivery) (Receipt, error) } ``` -------------------------------- ### Run capacity test with default consumer Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Runs the capacity test using the established consumer as the default. This is the baseline for the full pipeline A/B comparison. ```sh make capacity-nats-site-single ``` -------------------------------- ### Tear down durable demo containers Source: https://github.com/assurrussa/gomessenger/blob/master/examples/durable-postgres-nats/README.md Remove the stopped containers after a successful run. ```sh make demo-durable-postgres-nats-down ```