Watermill

kubemq-watermill is a production-ready Watermill pub/sub plugin for KubeMQ. It implements Watermill's message.Publisher and message.Subscriber interfaces across three KubeMQ messaging patterns — Events, EventsStore, and Queues — plus a native CQPublisher for Commands and Queries (request-reply). Drop it into an existing Watermill application and your Router, handlers, and middleware run unchanged on top of KubeMQ.

It is a native gRPC client built on the kubemq-go/v2 SDK — not an HTTP connector. If you need protocol bridging instead (REST, MCP, A2A, CloudEvents), see the Connectors overview. For the messaging model behind the patterns, see the core docs: Events, Events Store, Queues, and RPC.

Why Watermill on KubeMQ

• Three messaging patterns — Events (fire-and-forget), EventsStore (persistent with replay), and Queues (reliable with explicit ack/nack), each behind the same Watermill Publisher/Subscriber interfaces.
• Native CQPublisher — wraps KubeMQ's Commands and Queries APIs directly for low-latency request-reply, with execution confirmation and query caching.
• Full Watermill compatibility — works with the Watermill Router and the entire standard middleware stack (Retry, Throttle, CorrelationID, Poison Queue, CircuitBreaker).
• Ack/Nack bridged to KubeMQ — Watermill msg.Ack()/msg.Nack() map to KubeMQ queue settlement; a Nack returns the message to the queue for redelivery.
• Built-in DLQ, OTel, and metrics — native dead-lettering via QueueMessagePolicy, W3C Trace Context propagation through KubeMQ Tags, and Watermill's Prometheus component.
• Verified compatibility — passes the full Watermill pubsub/tests.TestPubSub suite.

Architecture

Your Watermill Router, Publisher, and Subscriber call the plugin, which uses kubemq-go/v2 to open a gRPC connection to the KubeMQ broker on port 50000. There is no HTTP connector and no server-side translation layer — the broker's gRPC server is always on, so the plugin works as soon as a broker is reachable.

The plugin maps Watermill's Publisher/Subscriber model onto KubeMQ patterns over the native gRPC SDK on port 50000.

Capabilities

Each Publisher and Subscriber serves exactly one KubeMQ pattern, selected with the Pattern field. Commands and Queries use the standalone CQPublisher.

Pattern selection

KubeMQ supports three messaging patterns. Each Publisher/Subscriber instance serves exactly one — pick the one that matches your delivery and persistence needs:

For request-reply, reach for the native CQPublisher (single hop, lower latency) or Watermill's requestreply component over Queues (middleware-compatible) — see Commands & Queries.

Supported runtime

Install the plugin with go get:

go get github.com/kubemq-io/watermill-kubemq

Next steps

New to KubeMQ? Start with the What is an integration? mental model, then the KubeMQ Getting Started guide.