Library / SDK
ThreeDotsLabs/watermill avatar
ThreeDotsLabs/watermill

Watermill's handler signature is the whole contract, and the examples carry the rest

Building event-driven applications the easy way in Go.

9,963 stars514 forksGoMIT

At a glance

What is it?
Watermill is a Go library for event-driven applications built on one handler type and two small Pub/Sub interfaces. Twelve adapters plug in behind it, only SQLite is marked Beta, and the delivery semantics you actually care about live in examples, middlewares and a hands-on training course.
Who is it for?
Watermill fits a Go team that wants message handling to read like an HTTP router and is willing to own delivery semantics itself. Before you commit, read the per adapter pages at https://watermill.io/pubsubs/, confirm your broker has an implementation and at which major version, and accept that ordering, deduplication and exactly once behaviour come from your handlers and middlewares rather than from the library.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 18 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ThreeDotsLabs/watermill9,963 ★ · +63
Star history
Repository2026-09-222026-11-15
ThreeDotsLabs/watermill9.9k10k

63 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One function type carries the whole programming model

The contract fits on a single line:

go
func(*Message) ([]*Message, error)

A handler receives a message and decides whether to publish new message(s) or return an error. Nothing in that signature can say how many of the new messages were actually delivered, whether a consumer already saw one of them, or whether the incoming message belongs before or after something the handler is publishing. What happens after an error, whether a retry, a drop, or a duplicate, depends on which middlewares you attached.

That is a clean division of labour with a price attached. The topic list for the project's hands-on training runs: handling at-least-once delivery, asynchronous read models, events and commands, observability, message ordering, sagas. Those are course topics rather than library features. The library gives you a function type; guarantees, ordering and instrumentation are things you assemble in components/ and in your own handlers.

The upside of the narrow signature is that a transport adapter only has to satisfy four methods, and a handler is an ordinary function you can unit test by handing it a message.

Every transport is four methods, and shutdown is yours to trigger

Both sides of every adapter are two method interfaces:

go
type Publisher interface {
	Publish(topic string, messages ...*Message) error
	Close() error
}

type Subscriber interface {
	Subscribe(ctx context.Context, topic string) (<-chan *Message, error)
	Close() error
}

Four methods across two interfaces is the entire surface a broker has to implement, and that is what keeps each adapter small. It is also the boundary. There is no Ack, no Nack, no health probe and no reconnect method on either interface, because those concerns are transport specific and therefore live outside this contract. Subscribe takes a context.Context, which gives you the cancel path, and Close gives you shutdown. How in-flight messages are drained on shutdown is not expressed anywhere here.

So lifecycle is manual, and that manual work lands in your main function: deciding when to close the publisher, when to close the subscriber, and in which order relative to the handlers still draining their channels. A program that returns without calling Close leaves the broker connection to be torn down by process exit rather than by the library, which is fine in a short lived tool and a different matter in a service that reloads or restarts often.

Retry, circuit breaking and an HTTP router all arrive in the core module

go.mod declares go 1.25.0 and a short list of direct requires: cenkalti/backoff/v5, sony/gobreaker, go-chi/chi/v5, prometheus/client_golang, google/uuid, lithammer/shortuuid/v3, oklog/ulid, gogo/protobuf, golang/protobuf, google.golang.org/protobuf, pkg/errors and stretchr/testify.

Two of those say more about the core than about any adapter. backoff and gobreaker are retry and circuit breaking libraries, and they are direct requirements of this module rather than of any Pub/Sub repository, so those middlewares ship with the core and are available whichever broker you pick. prometheus/client_golang is what makes the metrics example possible. chi is a third example of the same point: an HTTP router sits in the core module even though the HTTP Pub/Sub lives in a separate repository, watermill-http/v2. A service that only ever talks to Kafka still carries an HTTP router in its module graph. That is the bill for the universality goal, cheap in bytes and awkward the first time a dependency audit asks why chi is there.

The identity helpers are split three ways: google/uuid, shortuuid, and ulid, which is time prefixed and lexicographically sortable. Ordering work in your own handlers often needs sortable keys, so knowing which one the core reaches for is worth doing before you bolt your own scheme on top.

Twelve adapters share one test suite, and only SQLite is called Beta

The adapter list carries the interesting part in its version suffixes. AMQP is watermill-amqp/v3, Google Cloud Pub/Sub is v2, HTTP is v2, Kafka is v3, NATS Jetstream is v2, and SQL, which covers MySQL and PostgreSQL, is v4. Bolt, Firestore, AWS SNS/SQS, Redis Stream and io.Reader/io.Writer carry no suffix at all. Exactly one entry is qualified: SQLite Pub/Sub is marked Beta. The core module itself is at v1.5.3, so the breaking changes that piled up over the years sit in the adapter repositories, not in the library.

That stability rests on a shared suite. Every implementation has to pass a set of Pub/Sub tests before it is merged to master, and the same tests also run in stress mode, described as running all of the tests 20x in parallel. One suite written once and pointed at twelve very different systems is a contract on behaviour, not on features. Per adapter documentation sits at https://watermill.io/pubsubs/, which is where the gaps in the core go to be answered.

If your broker is not on that list of twelve, the project points you elsewhere: Awesome Watermill collects unofficial integrations, with an edit link aimed straight at docs/content/docs/awesome.md in this repository.

The core API is frozen at v1.0, so missing features move outward

Stability is stated as a promise about one version line: Watermill v1.0.0 has been released and is production-ready, the public API is stable, and it will not change without a major version change.

The file list backs that promise up in a way you can read off directly. There are three upgrade guides, UPGRADE-0.3.md, UPGRADE-0.4.md and UPGRADE-1.0.md. There is no UPGRADE-1.1 or UPGRADE-2 in the file list. RELEASE-PROCEDURE.md sits beside them.

The consequence is structural. A capability the core does not express is more likely to show up as a middleware in components/, a patch to the adapter repository, or a fork. Your escape hatches are the adapter repositories on their own major version lines, which is why the v3 and v4 suffixes matter during a dependency bump, and the components/ directory here. Nothing in that arrangement gives you a semver range that covers the adapter you depend on, so a Watermill upgrade and a broker adapter upgrade are two separate decisions that have to be tested against each other.

Getting started is a URL, because a library needs no install line

The README's Getting Started list points to documentation rather than an install command, which is the expected shape for a library. The Getting Started list offers four choices: the quickstart at https://watermill.io/learn/quickstart/, the Getting Started guide at https://watermill.io/learn/getting-started/, the examples in the repository, and the full documentation at https://watermill.io/. The first thing it asks of you is a browser, not a terminal.

The module path is github.com/ThreeDotsLabs/watermill and the licence is MIT, so your toolchain resolves the package from that path, and the badge at the top of the README points at pkg.go.dev for generated API documentation. The go directive in go.mod is 1.25.0, so a team pinned to an older Go release line should check that before adopting it.

The same README also points at a hands-on training course. Under online hands-on training it links threedots.tech/event-driven and says Go Event-Driven goes beyond the Watermill Quickstart, covering at-least-once delivery, asynchronous read models, events and commands, observability, message ordering and sagas. The split is deliberate and worth noticing: the quickstart teaches you the function type, the course teaches you what to build with it.

Reconnection tests sit behind a build tag, so the default suite skips them

The Makefile is the clearest statement of how this project is checked, and two targets matter more than the rest:

code
test_stress:
	go test -tags=stress -timeout=30m ./...

test_codecov:
	go test -coverprofile=coverage.out -covermode=atomic ./...

test_reconnect:
	go test -tags=reconnect ./...

and the example tree has its own two:

code
update_examples_deps:
	go run dev/update-examples-deps/main.go

validate_examples:
	(cd dev/validate-examples/ && go run main.go)

The stress tag is the one the stability claim leans on, and its 30 minute timeout is what a full parallel stress run has to fit inside. The reconnect tag is the one to watch. Reconnection behaviour is compiled only under that tag, which means the default target, go test ./..., never builds or runs it. A contributor editing an adapter can run the ordinary suite, watch it go green, and merge code that broke reconnection, because the test that would have caught it needs -tags=reconnect. The same split applies to the examples: validate_examples runs a program under dev/validate-examples, and update_examples_deps runs dev/update-examples-deps/main.go to refresh their dependencies.

The plain targets sit alongside these: test, test_v, test_short with -short, test_race with -short -race, test_codecov writing coverage.out in atomic mode, build, and fmt running go fmt and goimports. So the cost of the library staying small is visible here too: every extra guarantee is a tag someone has to remember to pass.

The examples directory is where the delivery semantics are shown

The _examples directory is where the semantics that the frozen core does not implement for you actually appear, and the file names are the argument. Under real-world examples there is an exactly-once delivery counter, alongside transactional events, a persistent event log, synchronizing databases, receiving webhooks and sending webhooks, and real-time HTTP updates with Server-Sent Events, both plain and with htmx. Under basic there is your first app, a realtime feed, a router, metrics, and CQRS with protobuf. Two complete projects sit outside this repository: a NATS example with live code reloading, and an event-driven example wiring RabbitMQ, webhooks and Kafka together.

The pubsubs examples carry their own caveat. They are described as part of the Getting Started guide, and they show usage of a single Pub/Sub at a time. So the topology where you consume from Kafka and write to PostgreSQL, or fan a webhook out across two brokers, is not what those examples teach, and the reading list you need for that is the one under the real-world examples instead.

The practical upshot for an evaluator: pick the broker pair you intend to run, then read the example that matches it rather than the quickstart, because the quickstart can only show you the shape of the code and the examples show you what the decisions cost.

Editorial conclusion

Watermill fits a Go team that wants message handling to read like an HTTP router and is willing to own delivery semantics itself. Before you commit, read the per adapter pages at https://watermill.io/pubsubs/, confirm your broker has an implementation and at which major version, and accept that ordering, deduplication and exactly once behaviour come from your handlers and middlewares rather than from the library. Then decide whether the delivery topics in the training are the only written treatment you intend to rely on.

Frequently asked questions

What is Watermill used for in a Go service?

Watermill is a Go library for working with message streams, intended for event driven applications such as event sourcing, RPC over messages, sagas and stream processing. Conventional pub/sub systems like Kafka or RabbitMQ fit, and so do HTTP or PostgreSQL if that suits the use case.

How does a Watermill handler actually work?

A handler is a func(*Message) ([]*Message, error). It receives a message and decides whether to publish new message(s) or return an error, and what happens next depends on the middlewares you have chosen.

What is Watermill, and where are its Pub/Sub adapters documented?

The core module is github.com/ThreeDotsLabs/watermill under the MIT licence, and each adapter lives in its own repository: AMQP, AWS SNS/SQS, Bolt, Firestore, Google Cloud Pub/Sub, HTTP, io.Reader/io.Writer, Kafka, NATS Jetstream, Redis Stream, SQL for MySQL and PostgreSQL, and SQLite marked Beta. Per adapter documentation is at https://watermill.io/pubsubs/.

How do I start using Watermill?

The README has no install line in its Getting Started list, because it is a library rather than a binary. That list sends you to the quickstart at https://watermill.io/learn/quickstart/ or the Getting Started guide, and the examples under _examples/ begin with 1-your-first-app. go.mod declares go 1.25.0.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. ThreeDotsLabs/watermill on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/threedotslabs-watermill.svg)](https://hysenlabs.com/projects/threedotslabs-watermill)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/threedotslabs-watermill.svg)](https://hysenlabs.com/projects/threedotslabs-watermill)

Was this useful?