A standalone locker sync primitive: versioned, subscribable per-room key/value blobs ("lockers") with real-time, per-session fan-out over gRPC (unary over HTTP, streaming over WebSockets). A locker is an opaque payload identified by (room, keyspace, lockerId) and carrying a monotonic version for optimistic concurrency. Clients subscribe to a room and receive live events as lockers change.

Scope: this repo is the primitive only — durable storage, sessions, subscriptions, and push fan-out. Higher-level features (chat, profiles, games, …) are add-ons layered on top by consumers and are intentionally out of scope.

Proto codegen shells out to protoc-gen-kt (the Kotlin protoc plugin, a Go binary) which must be on your PATH. Install the pinned version (matching CI):

go install latenighthack.com/protoc-gen-kt@v0.0.0-20251214023608-0fa742406fbf
# ensure "$(go env GOPATH)/bin" is on your PATH

Then:

./gradlew build                 # compile everything + run all tests
./gradlew :connector:jvmTest    # acceptance gate: integration tests vs. an in-process server
./gradlew :server:test          # server-side unit tests (persistence, config, rate limiter)
./gradlew detekt                # static analysis (advisory)

./gradlew :server:run:run       # boots on :8080

Configuration is read from the environment at startup (12-factor). Every value has a safe local-dev default; production must set at least LOCKERS_DB_URL.

Durable storage uses ktstore's Postgres-backed StoreDelegate (SqlStoreDelegate over a JDBC driver, BYTEA blobs). Set LOCKERS_DB_URL to a Postgres JDBC URL, e.g.:

export LOCKERS_DB_URL="jdbc:postgresql://localhost:5432/lockers?user=lockers&password=secret"

With no LOCKERS_DB_URL, the server falls back to an in-memory store and prints a warning — convenient for local dev, not durable across restarts. The server:test PersistenceTest proves data survives a store "restart" through the SQL delegate.

• Metrics: Prometheus exposition at GET /metrics (Micrometer). All metrics are namespaced lockers.*.
• Health: GET /healthz (liveness) and GET /readyz (readiness).
• Logs: structured JSON to stdout (logback + logstash encoder), directly ingestible by Loki/Promtail, ELK, or Datadog.

The client wraps lockers as typed values. See connector/src/jvmTest/.../LockerClientTests.kt for complete, runnable examples.

val typed = TypedLockerClient(
    lockerClient,
    keyspace = LockerKeyspace { value = MY_KEYSPACE },
    writer = MyValue::toByteArray,
    reader = MyValue.Companion::fromByteArray,
)

// optimistic, versioned update
typed.updateLocker(roomId, lockerId) { current -> current.mutate() }

// live, per-room view that folds change events into a map
typed.watchAll(roomId).collect { lockers -> render(lockers) }

The Stream reconnect loop retries transient session-open failures with backoff and surfaces terminal failures (rejected key, rejected session id, upgrade required) via Stream.fatalError instead of crashing.

api and connector publish via maven-publish:

./gradlew :api:publishToMavenLocal :connector:publishToMavenLocal

• Authorization & tenant isolation — session open is signature-verified, but room and locker operations are not yet authorized per-identity. Design pending.
• iOS/JS targets — api and connector are structured for Kotlin Multiplatform but currently build the JVM target only. Upstream libraries have iOS/JS variants, so adding targets is a follow-up, not a rewrite.
• Distributed tracing — structured logs and Prometheus metrics are in place; OpenTelemetry span instrumentation (or attaching the OTel Java agent) is the next step for end-to-end traces.

MIT — see LICENSE. (Chosen as a permissive default; change if your project requires otherwise.)