ReckonDB

Concepts

Documentation

API Reference

ReckonDB is reached through reckon-gateway, which exposes the store two ways over the same port range:

  • HTTP/JSON on :8080, for quick use from any language and from the shell.
  • gRPC on :50051, for typed clients and streaming. The contract is reckon-proto; generate a client for your language from it, or use the native Go client reckon-go.

Every path is scoped to a store: :store_id selects which event store you are talking to. A base URL for the HTTP examples:

BASE=localhost:8080/v1/stores/my_store

HTTP/JSON endpoints

Streams

Method Path Purpose
GET /v1/stores/:store_id/streams List streams
POST /v1/stores/:store_id/streams/:stream_id/events Append events (with expected_version)
GET /v1/stores/:store_id/streams/:stream_id/events Read a stream forward (?from=&limit=, dir=backward reverses)
GET /v1/stores/:store_id/streams/:stream_id/version Current stream version
DELETE /v1/stores/:store_id/streams/:stream_id Delete a stream 
# Append
curl -sX POST $BASE/streams/account-1/events \
  -H 'content-type: application/json' \
  -d '{"expected_version":"no_stream","events":[
        {"event_type":"account_opened_v1","data":{"owner":"Alice"}}]}'
# => {"version":0,"count":1}

# Read forward
curl -s "$BASE/streams/account-1/events?from=0&limit=100"

expected_version is the optimistic-concurrency guard: no_stream, any, or an exact integer; a mismatch returns HTTP 409.

Cross-stream indexed reads

Method Path Purpose
GET /v1/stores/:store_id/events/by-type?types=a,b Events of given types
GET /v1/stores/:store_id/events/by-tags?tags=a,b&match= Events by tag (all/any)
GET /v1/stores/:store_id/events/by-metadata?key=&value= Events by metadata key
GET /v1/stores/:store_id/events/global?offset=&limit= The global event log

These hit the write-maintained secondary indexes, so they are lookups, not scans.

DCB and CCC

Method Path Purpose
POST /v1/stores/:store_id/dcb/context Read the consistency context for a filter
POST /v1/stores/:store_id/dcb/append Conditional append (append-if-no-match)
GET /v1/stores/:store_id/dcb/log The DCB event log (paginated)
GET /v1/stores/:store_id/dcb/tags Tag index with counts
GET /v1/stores/:store_id/dcb/event-types Event-type index
GET /v1/stores/:store_id/dcb/by-payload CCC: read by payload field
POST /v1/stores/:store_id/dcb/by-payload-hash CCC: read by composite payload hash
GET /v1/stores/:store_id/dcb/payload-indexes Declared CCC payload indexes 
# Conditional append: only if no account already used this number
curl -sX POST $BASE/dcb/append \
  -H 'content-type: application/json' \
  -d '{"tag_filter":{"and":[
        {"event_type":"account_opened_v1"},
        {"match_any":["number:NL01-1002"]}]},
       "seq_cutoff":-1,
       "events":[{"event_type":"account_opened_v1",
                  "tags":["number:NL01-1002"],
                  "data":{"number":"NL01-1002","owner":"Bob"}}]}'
# => {"committed":{"last_seq":N}}  or  {"conflict":{"max_seq":N}}

See the DCB & CCC guide for the full model.

Stores and health

Method Path Purpose
GET /v1/stores List store instances
GET /v1/stores/:store_id One store’s instances
GET /v1/health Gateway health
GET /v1/health/:store_id Store health (leader, quorum, term)
GET /v1/server-info/:store_id Server info

gRPC services

The gRPC surface is broader than the REST one (streaming, subscriptions, schema, admin). All of it is defined in reckon-proto:

Service Key RPCs
StreamService AppendEvents, ReadStreamForward, ReadStreamBackward, StreamEventsForward (server stream), GetStreamVersion, ListStreams
DcbService AppendIfNoTagMatches, ReadDcbContext, CccReadByPayload, CccReadByPayloadHash
SubscriptionService Subscribe (server stream), AckEvent, CreateSubscription, RemoveSubscription, ListSubscriptions, GetSubscription, GetSubscriptionLag
SnapshotService RecordSnapshot, ReadSnapshot, DeleteSnapshot, ListSnapshots, ListAllSnapshots
SchemaService RegisterSchema, UnregisterSchema, GetSchema, ListSchemas, GetSchemaVersion, UpcastEvents
TemporalService ReadUntil, ReadRange, VersionAt
StoresService ListStores, GetStore, WatchStores (server stream)
AdminService GetStoreStats, GetStreamInfo, GetEventTypeSummary, Scavenge, link management, catalogue control
HealthService Check, Health, VerifyClusterConsistency, VerifyMembershipConsensus, CheckRaftLogConsistency, GetServerInfo

Clients

Go

reckon-go is the native client:

c, err := reckon.Connect(ctx, "localhost:50051", reckon.Insecure())
defer c.Close()

s := c.Streams("my_store")
res, err := s.Append(ctx, "account-1", streams.NoStream, []streams.ProposedEvent{
    {EventType: "account_opened_v1", Data: []byte(`{"owner":"Alice"}`)},
})
events, err := s.Read(ctx, "account-1", 0, 100)

streams.AnyVersion, streams.NoStream, and streams.StreamExists are the optimistic-concurrency sentinels; pass a non-negative version for an exact check. Live tail with s.Watch(ctx, streamID, startVersion, count).

reckon CLI

The reckon CLI (shipped with reckon-go) exposes the whole API as JSON-emitting subcommands for shell and CI use. The target is set with -e/--endpoint and -s/--store (or the RECKON_ENDPOINT / RECKON_STORE env vars):

# append (events read from stdin), then read back
echo '[{"event_type":"account_opened_v1","data":{"owner":"Alice"}}]' \
  | reckon -s my_store streams append account-1 --expect no-stream
reckon -s my_store streams read account-1 --count 100
reckon -s my_store health status

Other languages

Generate a client from reckon-proto with your language’s gRPC tooling, or use the HTTP/JSON endpoints above directly.

Next Steps

  1. Work through the bank-account tutorial
  2. Read the DCB & CCC guide
  3. Run the Examples