synapse

A Go event sourcing and CQRS toolkit. Composable primitives — aggregates, events, repositories, projections — plus the operational surface real services need: a Postgres backend, broker delivery for projections, sagas with timeouts, dead-letter handling, crypto-shredding, OpenTelemetry hooks, and an admin RPC for dump/restore.

Zero third-party dependencies in the root module. Anything that pulls in an external library (a SQL driver, a broker client, gRPC) lives as a sibling module so you opt in to what you use.

Pre-1.0. The public surface is still moving; expect minor breaking changes between tagged versions. The Postgres and SQLite stacks (events + snapshots + checkpoints + dead-letter + timeouts + keystore, one pool / one file) are shaping up production-ready but have not yet seen production traffic.

go get github.com/ianunruh/synapse

Requires Go 1.26 or newer.

package main

import (
    "context"

    jsoncodec "github.com/ianunruh/synapse/codec/json"
    "github.com/ianunruh/synapse/es"
    "github.com/ianunruh/synapse/eventstore/memory"
)

// Define an aggregate by embedding *es.AggregateBase.

type Counter struct {
    *es.AggregateBase
    Value int
}

func NewCounter(id es.StreamID) *Counter {
    return &Counter{AggregateBase: es.NewAggregateBase(id)}
}

type CounterIncremented struct {
    By int `json:"by"`
}

func (c *Counter) Apply(env es.Envelope) {
    if inc, ok := env.Payload.(CounterIncremented); ok {
        c.Value += inc.By
    }
}

func (c *Counter) Increment(by int) {
    c.Record("counter.incremented", CounterIncremented{By: by}, c.Apply)
}

func main() {
    ctx := context.Background()

    reg := es.NewRegistry()
    es.Register(reg, "counter.incremented", jsoncodec.For[CounterIncremented]())

    repo := es.NewRepository(memory.New(), reg, NewCounter)

    c := NewCounter("counter/hits")
    c.Increment(2)
    c.Increment(3)
    _ = repo.Save(ctx, c)

    loaded, _ := repo.Load(ctx, "counter/hits")
    _ = loaded.Value // == 5
}

A full walkthrough is in docs/getting-started.md. Runnable examples live under examples/.

Beyond the core aggregate/repository/projection trio, the toolkit ships:

• Storage backends — Postgres (ADR-0024) and SQLite (ADR-0017) for the event store, snapshot store, checkpoint store, dead-letter store, timeout store, and key store. Postgres uses a shared LISTEN/NOTIFY (ADR-0025) for live-tail; read-replica routing is opt-in (ADR-0038).
• Commands — Typed es.Handler[C, A] + es.Execute (ADR-0009) for in-process callers; es/commandbus for dispatching named, byte-encoded commands from HTTP/gRPC transports (ADR-0028).
• Process managers and sagas — es/process (ADR-0032) wraps a saga as a projection that emits commands. Saga timeouts are scheduled via outbox-style intent events on the saga's own stream, atomic with Save (ADR-0043).
• Broker delivery — outbox.Publisher (ADR-0042) + a NATS JetStream adapter; outbox/nats.Consumer (ADR-0044) lets projections subscribe to NATS instead of polling Postgres. End-to-end demo in examples/nats-postgres-projection.
• Dead-letter queue — projection.WithDeadLetter (ADR-0041) routes failed events to a persistent DLQ; the runner logs at Warn and continues. Admin RPCs and CLI subcommands surface entries for operators.
• Crypto-shredding — Per-subject AES-256-GCM via a KeyStore interface (ADR-0036). Shredding a key tombstones every event for that subject in place; the rest of the log keeps replaying.
• Observability — slog everywhere by default (ADR-0015); an opt-in otel sibling module emits spans + duration histograms around every persistence call (ADR-0034).
• Admin RPCs — synapse-admin and a gRPC service expose stream/checkpoint/snapshot/deadletter inspection plus dump/restore in JSONL (ADR-0033, ADR-0040).
• Liveness/readiness probes — synapse/health aggregates user-registered checks behind two HTTP handlers; stdlib only (ADR-0039).
• Event upcasters — Old event shapes evolve forward; Apply only ever sees the latest version (ADR-0023).

• Getting started — a 20-minute walkthrough that builds the Counter aggregate above into a service with commands, a projection, snapshots, and a SQLite backend.
• Architecture Decision Records — 45 records explaining why the library is shaped the way it is.
• Benchmarks — baseline numbers for the core hot paths and the included store backends.
• Releasing — the multi-module tagging procedure used for each cut.
• Package docs: pkg.go.dev/github.com/ianunruh/synapse/es.

The repo is a Go workspace. Core interfaces live in es; backends and contract suites are sibling packages — or sibling modules when they pull in third-party deps.

Sibling modules each have their own go.mod. A go.work file at the repo root ties them together for local development. The root module has zero third-party deps; the SQLite backends transitively pull in modernc.org/sqlite (pure Go, no CGo).

Recorded as Architecture Decision Records (starting at ADR-0001):

• Go 1.26 toolchain, language features and stdlib used to current capability.
• Zero third-party deps in the root module. Backends that need them live as sibling Go modules.
• Modernization-clean. gopls modernize ./... exits 0 in every module.
• Serialization-agnostic core. Codecs are registered per event type; the es package never imports a specific codec.
• Type safety and performance are co-equal goals. Where they point the same direction (most cases), take both. Where they conflict, prefer the perf-friendly option in hot paths and document the trade-off.
• Admin RPCs and a web UI, when they exist, will be optional sibling subpackages users opt into.

Apache 2.0. See LICENSE.