Infrastructure

Axon Server

The @kronos-ts/axon-server package connects a Kronos application to Axon Server over gRPC for its event store, snapshots, command bus, query bus and processor administration.

@kronos-ts/axon-server is the client for Axon Server. It provides an event store over Axon Server's dynamic consistency boundary (DCB) API, a snapshot tier, a command bus and a query bus that route through the server, and a control plane through which the Axon Server dashboard administers your event processors. Each piece is a plain function over one shared connection.

The package is shaped like the KronosDB package except that it has no scheduling tier. For scheduling, wrap this store with a scheduling store from another package, such as postgresSchedulingEventStore.

Connecting

axonServerConnection creates the connection handle. All stores and buses built from it share one gRPC channel, and the context each call addresses is sent as a header, so several contexts can use one channel.

const axon = await axonServerConnection({
  componentName: "toolstore-counter",
  serializer: jsonSerializer(),
  host: "axonserver.internal",
  port: 8124,
  context: "toolstore",
  token,
})

componentName is the application name shown on the Axon Server dashboard, and serializer encodes every payload this client sends.

Composition

Build the stores and buses from the handle, assemble the application with kronos(), then start the handle. To let the dashboard administer your processors, create the control plane after that:

const eventStore = axonServerSnapshottingEventStore(
  axonServerEventStore(axon, "toolstore"),
  axon,
  "toolstore",
)
const commandBus = axonServerCommandBus(localCommandBus(unitOfWork), axon, { context: "toolstore" })
const queryBus = axonServerQueryBus(localQueryBus(unitOfWork), axon, { context: "toolstore" })
const inventoryView = eventProcessor("inventory-view", eventStore, inMemoryTokenStore(), unitOfWork)

const app = kronos({
  commandHandlers: [{ ...addTool, eventStore, commandBus, queryBus }],
  eventHandlers: [{ ...recordAddedTool, eventStore, commandBus, queryBus, processor: inventoryView }],
})

await axon.start()
const control = await axonServerControlPlane(axon, app.processors.values() as Iterable<ManagedEventProcessor>)

axon.start() has to run after kronos(), because kronos() subscribes the handlers and each subscription registers the handler with the server. It then waits busSubscriptionAckDelayMs for the server to register them. The wait is a fixed delay, because the client cannot detect when Axon Server has registered a subscription. app.processors is typed as a map of unknown values, so passing .values() needs the cast shown. Processors added to the app after the control plane is created are not addressable from the dashboard.

FunctionProvides
axonServerEventStoreThe event store of State and consistency over one context.
axonServerSnapshottingEventStoreSnapshot storage for states that declare a snapshot policy. Wraps a store.
axonServerCommandBus, axonServerQueryBusBuses that route through the server. Wrap a local bus.
axonServerControlPlaneLets the dashboard administer your event processors. Optional.

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

A context is Axon Server's tenancy boundary. axonServerEventStore(axon, "toolstore") and axonServerEventStore(axon, "billing") share one channel and address different contexts. A store's context argument is required. A bus takes its context from its context option, which defaults to the connection's context.

Event store behaviour

Events read back have empty tags, because Axon Server indexes tags when it stores an event but does not return them. Reading past the head of the log returns no events and is not an error.

If a gRPC read does not complete within readTimeoutMs, the client cancels and retries it once, and a second timeout fails with ConnectionFailedError. This guards against a Bun HTTP/2 client defect that intermittently loses the end of a response. Reads are idempotent, so repeating one is safe. Raise readTimeoutMs if a single read legitimately takes longer than 15 seconds.

A snapshot is a cache. When the snapshot service has no snapshot, or cannot be reached, the load falls back to a full read from the start of the log and stays correct. A snapshot is written after the transaction it summarizes commits, and writing one removes the earlier ones.

Command and query buses

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, a higher priority is processed first, and the server cancels a command that is not handled within timeoutMs. loadFactor is the relative share of routed commands this instance receives.

subscriptionQuery returns the initial result, then the updates handlers emit with ctx.emitUpdate. 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, and fails the excess with UnavailableError. A subscription is not a durable feed: it ends when the channel does, and the subscriber has to query and subscribe again. Use an event processor for changes that must not be missed.

Control plane

Axon Server can pause and start the event processors of a connected client, split, merge and release their segments, and show their status on the dashboard. pause-processor starts the processor's stop() and does not wait for it, so a processor can take a moment to stop after the dashboard reports the instruction as sent. 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 third argument:

Prop

Type

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 sends a heartbeat to the server and treats a stretch without a response as a lost connection. It then closes the gRPC channel and opens one to the next address in servers, waiting after each failed attempt. After maxReconnectAttempts it throws UnavailableError; with the default of 0 it keeps trying. Calls in flight on the old channel fail, and the client does not send them 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.

Each bus reopens its stream after a reconnect, announces its handler names again and resumes, retrying with growing delays and logging each retry with console.warn. An event processor reopens its subscription from its stored token. A subscription query ends, and the subscriber has to subscribe again.

Shutdown

Stop the application first, close the control plane if you created one, then close the handle.

await app.stop()
await control.close()
await axon.close()

axon.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 channel. Work still running after the timeout continues in this process, and its result is discarded.

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 AxonServerError) return `axon:${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 axon.start() on the same context.
The server could not respond: gRPC UNAVAILABLE or DEADLINE_EXCEEDEDConnectionFailedError (isUnavailable)Retry. The request may have run.
The server reports a dispatch failure or no event store leaderCommandDispatchError, QueryDispatchError or AxonServerError (isUnavailable)Retry.
The deadline passedUnavailableError, "Messaging deadline exceeded after Nms" (isUnavailable)Retry. The command may still have run.
A read timed out twiceConnectionFailedError (isUnavailable)Retry, or raise readTimeoutMs.
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 message exceeds the server's size limitAxonServerError with transient: falseSend a smaller payload, or raise the server's limit.

A subscription query fails its update iterator with UnavailableError when the initial result takes longer than timeoutMs, when 1024 subscriptions are already open, or when the bus is shutting down.

On this page