Infrastructure

KronosDB

The @kronos-ts/kronosdb package connects a Kronos application to a KronosDB server for its event store, snapshots, schedules, command bus, query bus and processor administration.

@kronos-ts/kronosdb is the client for KronosDB. It provides an event store, snapshot and scheduling tiers on top of that store, a command bus and a query bus that route through the server, and a control plane through which the server administers your event processors. Each piece is a plain function over one shared connection, so an application that only needs the event store builds only the event store.

The client needs a server that implements native protocol version 2 (KronosDB 0.12 or later). It connects over TCP, or over TLS on the same port.

Connecting

kronosDbConnection creates the connection handle. It does not touch the network: the socket opens when the first store or bus is used, and opens again after it closes unexpectedly. Every store and bus built from the handle shares that one socket.

const kdb = await kronosDbConnection({
  componentName: "toolstore-counter",
  serializer: jsonSerializer(),
  host: "kronosdb.internal",
  port: 50051,
  context: "toolstore",
  token,
})

componentName identifies the application in the KronosDB admin console, and serializer encodes every payload this client sends: events, snapshots, scheduled events, command payloads and query results. A payload the serializer cannot encode fails the call that carries it.

Composition

Stores and buses are functions of the handle. Build them, assemble the application with kronos(), and call kdb.start() once:

const eventStore = kronosDbSchedulingEventStore(
  kronosDbSnapshottingEventStore(kronosDbEventStore(kdb, "toolstore"), kdb, "toolstore"),
  kdb,
  "toolstore",
)
const commandBus = kronosDbCommandBus(localCommandBus(unitOfWork), kdb, "toolstore")
const queryBus = kronosDbQueryBus(localQueryBus(unitOfWork), kdb, "toolstore")

const app = kronos({
  commandHandlers: [{ ...addTool, eventStore, commandBus, queryBus }],
  queryHandlers: [{ ...getInventory, eventStore, queryBus }],
})

await kdb.start()

kdb.start() has to run after kronos(), because kronos() subscribes the handlers and each subscription registers the handler name with the server. start() waits until the server has acknowledged every handler, so a command dispatched right after it is routable. It waits at most startTimeoutMs, and repeated calls return the same promise.

FunctionProvides
kronosDbEventStoreThe event store of State and consistency over one context.
kronosDbSnapshottingEventStoreSnapshot storage for states that declare a snapshot policy. Wraps a store.
kronosDbSchedulingEventStoreScheduling, kept by the server. Wraps a store.
kronosDbCommandBus, kronosDbQueryBusBuses that route through the server. Wrap a local bus.
kronosDbControlPlaneLets the server administer your event processors. Optional.

Events read back carry their tags. A dispatch always goes to the server, even for a command this process handles. To handle such a command locally, wrap the bus in localFirstCommandBus(bus, local) or localFirstQueryBus(bus, local). Wrap the outermost bus in interceptingCommandBus(bus, correlation) so the intercept runs before the message is serialized.

Contexts and bus names

A context is a string that selects an event log on the server. kronosDbEventStore(kdb, "toolstore") and kronosDbEventStore(kdb, "billing") share the one socket and read different logs. A store with no context argument uses the connection's context. Contexts explains what a context holds on the server.

The command and query buses take a bus name instead of a context, as their third argument, which defaults to "default". A bus name addresses the server's messaging, which is separate from its event logs. The examples name the bus after the context; that is a choice you make at the call site. Messaging describes what a bus is on the server.

Handlers announce themselves under the connection's clientId. A restarted process that keeps its clientId replaces its previous registration. Two buses built for the same bus name on one connection are both kept.

Scheduling and snapshots

The server stores schedules and appends the event when it is due. A schedule is durable once schedule() resolves, it fires once across a leader failover, and a schedule that came due while the server was down fires on recovery. Scheduling does not join the caller's unit of work: a handler that schedules an event and then throws has still armed the schedule.

cancelSchedule returns cancelled, already-appended or not-found. scheduleIdempotent(event, at, token) takes a token you choose, so a retried call throws ScheduleAlreadyExistsError instead of arming a second schedule. listSchedules returns the pending schedules, soonest first. Scheduling and cancelling must reach the cluster leader, so a follower returns an unavailable error and the caller retries.

const eventStore = kronosDbSchedulingEventStore(kronosDbEventStore(kdb, "toolstore"), kdb, "toolstore")
const pending = await eventStore.listSchedules()
return pending.map((schedule) => `${schedule.token} fires ${new Date(schedule.dueAt).toISOString()}`)

A snapshot is written after the transaction it summarizes commits. A write that does not land costs a longer replay on the next load, and the load stays correct.

Subscription queries

subscriptionQuery on the query bus returns the initial result, then the updates handlers emit with ctx.emitUpdate.

const watching = subscriptionQuery(queryBus, GetCustomerRentals, { customerId: "ada" })
console.log("initial:", await watching.initialResult)

for await (const toolIds of watching.updates) {
  console.log("rented now:", toolIds)
  break
}

watching.close()

emitUpdate runs after the unit of work commits, and not at all if it rolls back. A bus holds at most 1024 subscriptions it opened and 1024 it serves. A subscription is not a durable feed: it ends when the socket does, and the subscriber has to query and subscribe again. Use an event processor for changes that must not be missed.

Control plane

The server can pause and start the event processors of a connected client, split, merge and release their segments, and show their status in the admin console. This is opt-in through kronosDbControlPlane. Create it before kdb.start(), so every instruction has a handler when it arrives.

const control = kronosDbControlPlane(kdb, app.processors)
await kdb.start()

A processor that throws on an instruction, for example splitting a segment that does not exist, is reported to the server as failed with the error's message. An instruction for an unknown processor changes nothing. Segments are described on the event processors page, and an instruction for one applies to that processor only.

Options

Prop

Type

The command and query buses take an options object as their fourth argument:

Prop

Type

A command's metadata can carry processingInstructions with a routingKey, a priority and a timeoutMs. Commands with the same routing key go to the same handler. Two concurrent dispatches on one bus with the same message identifier fail, so use a fresh identifier for each.

When the connection drops

The client opens a new socket on the next request after one dies, trying the configured servers in order. A request in flight on the lost socket fails with ConnectionFailedError, and the client does not send it again. A command or query that failed this way may or may not have run, so the caller decides whether to send it again, and handlers should be idempotent.

Handler registrations are restored without action from you. Each handler stream reopens, registers its names again and resumes, retrying with growing delays and logging each retry with console.warn. A subscription an event processor reads ends with an error, and the processor reopens it from its stored token. A subscription query ends, and the subscriber has to subscribe again.

A bad token fails with AuthenticationError at once and is not retried against another server. A server that announces it is shutting down keeps serving the streams already open and gets no new work.

Shutdown

Stop the application first, then close the handle.

await app.stop()
await kdb.close()

kdb.close() rejects new dispatches with ShutdownInProgressError, ends the subscriptions this process opened, and waits for running handlers to finish. It waits at most shutdownTimeoutMs. If the work has not drained by then, close() rejects with an UnavailableError, and in either case it closes the socket. Work still running after the timeout continues in this process, and its result is discarded. Call await control.close() before kdb.close() if you created a control plane.

Errors

Check errors with the guards from @kronos-ts/core, not with instanceof: an application can hold two copies of core, and the guards read the error's kind.

if (isConflict(error)) return "conflict"
if (isNoHandler(error)) return "nobody-handles-it"
if (isUnavailable(error)) return "try-again-later"
if (error instanceof AuthenticationError) return "bad-token"
if (error instanceof KronosDbRequestError) return `refused:${error.status}`
if (error instanceof KronosDbError) return `kronosdb:${error.errorCode}`
What happenedWhat the caller receivesWhat to do
An append's condition was violated; nothing was writtenConcurrencyError (isConflict)Load the state again and decide again.
Nothing handles the command or queryNoHandlerForCommandError or NoHandlerForQueryError (isNoHandler)Check that the handling process called kdb.start() on the same bus name.
The socket was lost, would not connect, or the handshake timed outConnectionFailedError (isUnavailable)Retry. The request may have run.
The server is not ready, is failing over, or a follower rejected a schedule writeKronosDbRequestError with status unavailable (isUnavailable)Retry.
The deadline passedUnavailableError, "Messaging deadline exceeded after Nms" (isUnavailable)Retry. The command may still have run.
A bus is at maxConcurrentHandlers or maxPendingRequestsMessagingOverloadedError (isUnavailable)Retry later, or raise the limits.
The connection is closingShutdownInProgressError (isUnavailable)Stop dispatching.
A handler on another instance threw anything elseCommandExecutionError or QueryExecutionError with the remote messageReport it.
The token is missing or wrongAuthenticationErrorFix the token.
A schedule token is already in useScheduleAlreadyExistsErrorThe earlier call armed it.
Any other rejectionKronosDbRequestError with the server's statusReport it.

kdb.start() rejects with UnavailableError ("Handler registration timed out after Nms") when the server does not acknowledge the handlers in time, and with a KronosDbError when the server rejects a registration. A subscription query fails its update iterator with UnavailableError when the initial result takes longer than timeoutMs or the bus is shutting down.

On this page