Files
archie/internal/infrastructure/servicediscovery/nats/doc.go
T
sam 0bc65b680d feat(servicediscovery): scaffold ServiceRegistry contract and NATS KV implementation
Add a broker-neutral service registry contract (Endpoint, EventKind,
Event, ServiceRegistry, ErrNotInstalled) and a NATS JetStream KV
implementation, plus the registration side a service uses to announce itself.

The contract's governing semantic -- NotInstalled is not Down -- is modeled
by two buckets: a durable installed marker (never expires) distinct from
expiring heartbeat keys. Instances heartbeat their key on an interval; a
stopped process leaves via TTL expiry. Register writes the marker once then
heartbeats; Resolve returns ErrNotInstalled only when the marker is absent,
and an empty roster for installed-but-down. Watch dedupes heartbeat refreshes
so it emits membership changes, not liveness pings.

Unwired: no daemon/bootstrap path consumes it yet. Deliberately uses a dot
key separator instead of the research sketch's slash so per-service watch
wildcards match.
2026-09-05 03:11:43 +10:00

51 lines
2.6 KiB
Go

// Package nats is the NATS JetStream KV transport for service discovery.
//
// It implements the broker-neutral
// [servicediscovery.ServiceRegistry] contract against a JetStream KeyValue
// store, and additionally provides the registration side a service uses to
// announce itself. It is the fallback discovery mechanism for single-host,
// no-Kubernetes installs (Path B of
// docs/inspiration/service-discovery-research-2026-09-05.md); the
// Kubernetes-native primary is a sibling implementation of the same contract.
//
// # Two buckets: presence versus liveness
//
// The NotInstalled/Down distinction (the governing semantic of
// [servicediscovery]) requires modelling a service's presence separately from
// any instance's liveness. NATS KV cannot express that with one bucket,
// because a bucket-wide TTL (needed so stale heartbeats expire) would also
// expire the "installed" record, collapsing Down into NotInstalled. So the
// implementation uses two buckets:
//
// - Registry bucket (heartbeats): one key per live instance, refreshed on a
// heartbeat interval and expired by a bucket-wide TTL. Presence of a key
// here means the instance is live.
// - Installed bucket (marker): one key per service, written once at first
// registration with no TTL, never expires. Presence of this marker means
// the service was installed; absence means never installed => NotInstalled.
//
// A service that registered once but whose instances have all gone is still
// installed (its marker persists) and simply has zero live endpoints, so
// [Client.Resolve] returns an empty slice with no error. Only a service that
// never wrote a marker resolves to [servicediscovery.ErrNotInstalled].
//
// # Key scheme
//
// Instance heartbeat keys are "<service>.<instance-id>" (dot-separated), and
// the installed marker key is "<service>". The dot separator is a deliberate
// deviation from the research sketch's "<service>/<instance-id>": NATS KV
// watch filters match on dot-separated subject tokens, so a per-service watch
// of "curator.*" must see "curator.inst-1" as two tokens. A slash would make
// the whole key a single opaque token that no per-service wildcard can match.
// Consequently both service names and instance IDs must avoid the dot
// character; standard slugs and UUIDs satisfy that.
//
// Layout:
//
// config.go connection and bucket tuning, defaults and validation
// errors.go sentinel errors callers match on
// keys.go key scheme, pure and dependency-free
// registry.go the ServiceRegistry client (Resolve/Watch)
// registrar.go the registration side (announce + heartbeat)
package nats