@kronos-ts/axon-server 0.4.0 → 0.6.0

package/dist/axon-server.d.ts

@@ -1,60 +1,36 @@
-/**
- * The Axon Server command and query buses.
- *
- * Axon Server is a SMART HUB: outbound dispatch always goes to the server, and
- * the server decides which node handles it — there is no client-side
- * prefer-local fork here, which is the whole difference from the dumb-pipe
- * broker in `@kronos-ts/rabbitmq`.
- *
- * Both buses are plain functions over the shared connection and YOUR local bus:
- *
- * ```ts
- * const commandBus = interceptingCommandBus(
- *   axonServerCommandBus(axon, simpleCommandBus(unitOfWork)), lineage)
- * const queryBus = interceptingQueryBus(
- *   axonServerQueryBus(axon, simpleQueryBus(unitOfWork)), lineage)
- * ```
- *
- * Axon-specific protocol invariants are preserved byte-for-byte:
- *
- *   - CLIENT_SUPPORTS_STREAMING capability advertised on every dispatched
- *     query via `defaultQueryInstructions(...)`;
- *   - AxonIQ-Context + AxonIQ-Access-Token gRPC metadata headers built by
- *     `contextView(...)` and attached to every outbound stream/RPC;
- *   - permits-AFTER-subscriptions stream ordering preserved on the initial
- *     handshake AND on reconnect (see `ensureStreamStarted` /
- *     `reestablishStreamBody`).
- */
-import { type ResilienceConfig } from "@kronos-ts/core";
-import type { CommandBus, QueryBus } from "@kronos-ts/core";
+import { type MessagingLimits } from "@kronos-ts/core";
+import { type ResilienceConfig } from "./resilience.js";
+import type { CommandBus, QueryBus, SubscriptionCapableQueryBus, UnitOfWork } from "@kronos-ts/core";
 import type { AxonServerBusSource } from "./connection.js";
 /**
  * Flow control configuration for a bus channel.
  */
-export interface FlowControlConfig {
+export type FlowControlConfig = {
     /** Initial permits granted to Axon Server. Default: 5000 (aligned with Java). */
     permits?: number;
     /** Threshold at which to request more permits. Default: 2500 (aligned with Java). */
     refillThreshold?: number;
-}
+};
 /**
  * Processing instructions attached to outbound messages.
  * Controls routing, priority, and timeout behavior on Axon Server.
  */
-export interface ProcessingInstructions {
+export type ProcessingInstructions = {
     /** Routing key for consistent hashing (e.g., aggregate ID). */
     routingKey?: string;
     /** Priority (higher = processed first). Default: 0 */
     priority?: number;
     /** Timeout in ms. Axon Server cancels the command/query if not handled in time. */
     timeoutMs?: number;
-}
+};
 /**
  * Tuning for {@link axonServerCommandBus}. Every field has a working default;
- * the two arguments that carry meaning — the connection and your local bus —
+ * the two arguments that carry meaning — the connection and your next bus —
  * are positional, and this record is the trailing remainder.
  */
-export interface AxonServerCommandBusOptions {
+export type AxonServerCommandBusOptions = {
+    /** Client-side request deadline. Default: 30000ms. */
+    timeoutMs?: number;
     /** Axon Server context for this bus's stream. Default: the connection's. */
     context?: string;
     /** Flow control for the command stream. */
@@ -67,11 +43,13 @@ export interface AxonServerCommandBusOptions {
     loadFactor?: number;
     /** Retry policy for stream re-establishment. Default: the connection's. */
     resilience?: Partial<ResilienceConfig>;
-}
+    /** Bounded admission; excess nested work receives an overload error. */
+    limits?: MessagingLimits;
+};
 /**
  * Tuning for {@link axonServerQueryBus}. See {@link AxonServerCommandBusOptions}.
  */
-export interface AxonServerQueryBusOptions {
+export type AxonServerQueryBusOptions = {
     /** Axon Server context for this bus's stream. Default: the connection's. */
     context?: string;
     /** Flow control for the query stream. */
@@ -87,41 +65,43 @@ export interface AxonServerQueryBusOptions {
      */
     shortcutQueriesToLocalHandlers?: boolean;
     /**
-     * Default timeout for query dispatch in ms. Default: 3600000 (1 hour).
+     * Default timeout for query dispatch in ms. Default: 30000ms.
      * Aligned with Java's processing instruction timeout.
      */
     timeoutMs?: number;
     /** Retry policy for stream re-establishment. Default: the connection's. */
     resilience?: Partial<ResilienceConfig>;
-}
+    /** Bounded admission; excess nested work receives an overload error. */
+    limits?: MessagingLimits;
+};
 /**
- * A command bus backed by Axon Server, over YOUR local bus.
+ * A command bus backed by Axon Server, over YOUR next bus.
  *
  * - **Outbound dispatch**: ALWAYS through Axon Server, via the unary Dispatch
  *   RPC. Axon Server routes the command to the appropriate node (which may be
- *   this one). There is deliberately no client-side prefer-local fork: the hub
+ *   this one). There is deliberately no client-side prefer-next fork: the hub
  *   is the router, and short-circuiting it would silently defeat load factors,
  *   priorities and routing keys.
- * - **Inbound**: a command the server routes here is dispatched into `local` —
+ * - **Inbound**: a command the server routes here is dispatched into `next` —
  *   not into a privately-held handler map. That is what makes the unit-of-work
- *   policy you chose for `local` (say `postgresUnitOfWork(pg, unitOfWork)`)
+ *   policy you chose for `next` (say `postgresUnitOfWork(unitOfWork, pg)`)
  *   apply to server-routed work exactly as it applies to work this process
  *   originated. It is also why this function takes no `unitOfWork` argument:
- *   `local` carries that policy now.
- * - **subscribe**: registers the handler on `local` AND announces the name to
+ *   `next` carries that policy now.
+ * - **subscribe**: registers the handler on `next` AND announces the name to
  *   Axon Server, so other nodes can route to us.
  *
- * ## Correlation lineage and the interceptor layer
+ * ## correlation and the interceptor layer
  *
- * The returned bus stamps no lineage of its own. A host that wants it wraps the
+ * The returned bus stamps no correlation of its own. A host that wants it wraps the
  * OUTERMOST bus:
  *
  * ```ts
- * interceptingCommandBus(axonServerCommandBus(conn, local), lineage)
+ * interceptingCommandBus(axonServerCommandBus(next, conn), correlation)
  * ```
  *
  * so whatever a host adds runs BEFORE the message is serialized onto the wire.
- * Lineage itself is usually already on `message.metadata` by then — `ctx.send`
+ * Correlation itself is usually already on `message.metadata` by then — `ctx.send`
  * stamps the unit of work's correlation data before any bus sees the message.
  *
  * This is precisely how the Java client does it. AF4's `AxonServerCommandBus`
@@ -129,37 +109,38 @@ export interface AxonServerQueryBusOptions {
  * `doDispatch(dispatchInterceptors.intercept(commandMessage), cb)` — one call
  * site, at the top, ahead of any routing. AF5 keeps the property via decorator
  * order: `DISTRIBUTED_COMMAND_BUS_ORDER = InterceptingCommandBus.DECORATION_ORDER - 50`
- * stacks `InterceptingCommandBus → DistributedCommandBus → SimpleCommandBus`.
+ * stacks `InterceptingCommandBus → DistributedCommandBus → LocalCommandBus`.
  *
- * If `local` is itself an intercepting bus, a server-routed command sees
- * `lineage` twice. That is harmless: both of its fields are `??` seeds, so the
+ * If `next` is itself an intercepting bus, a server-routed command sees
+ * `correlation` twice. That is harmless: both of its fields are `??` seeds, so the
  * second application finds them set and changes nothing.
  */
-export declare function axonServerCommandBus(conn: AxonServerBusSource, local: CommandBus, options?: AxonServerCommandBusOptions): CommandBus;
+export declare function axonServerCommandBus<U extends UnitOfWork = UnitOfWork>(next: CommandBus<U>, conn: AxonServerBusSource, options?: AxonServerCommandBusOptions): CommandBus<U>;
 /**
- * A query bus backed by Axon Server, over YOUR local bus.
+ * A query bus backed by Axon Server, over YOUR next bus.
  *
  * Same architecture as {@link axonServerCommandBus}: outbound dispatch goes
- * through Axon Server, and a query the server routes here runs through `local`,
+ * through Axon Server, and a query the server routes here runs through `next`,
  * so your unit-of-work policy applies to server-routed reads too. `subscribe`
- * registers on `local` and announces the name to the server.
+ * registers on `next` and announces the name to the server.
  *
  * The one asymmetry with commands is `shortcutQueriesToLocalHandlers` — Java
  * has it for queries and not for commands, and so do we. When it is on and this
- * node subscribed the name, `query()` goes straight to `local` and the caller's
- * unit of work is passed through, so the local branch nests exactly as the
+ * node subscribed the name, `query()` goes straight to `next` and the caller's
+ * unit of work is passed through, so the next branch nests exactly as the
  * in-process bus does.
  *
- * Lineage, if wanted, is `interceptingQueryBus(bus, lineage)` at the host,
+ * Correlation, if wanted, is `interceptingQueryBus(bus, correlation)` at the host,
  * matching AF4's `AxonServerQueryBus`, which calls
  * `dispatchInterceptors.intercept(...)` at the top of `query`, `streamingQuery`,
  * `scatterGather` and `subscriptionQuery`. Because the wrap is outside, the
- * shortcut branch gets identical lineage to the remote branch.
+ * shortcut branch gets identical correlation to the remote branch.
  *
- * KNOWN GAP: `subscriptionQuery` / `subscribeToUpdates` build their proto
- * straight from `message.metadata`, and `interceptingQueryBus` (in
- * `@kronos-ts/core`) forwards those two calls to the delegate without
- * running the dispatch chain. Closing that needs a core change.
+ * Subscription queries run the dispatch chain: `interceptingQueryBus` wraps
+ * `subscriptionQuery` / `subscribeToUpdates` with the same intercept the
+ * primary `query` gets, so the proto built from `message.metadata` already
+ * carries whatever the host's intercept stamped (pinned in core by
+ * `interception/__tests__/subscription-interception.test.ts`).
  */
-export declare function axonServerQueryBus(conn: AxonServerBusSource, local: QueryBus, options?: AxonServerQueryBusOptions): QueryBus;
+export declare function axonServerQueryBus<U extends UnitOfWork = UnitOfWork>(next: QueryBus<U>, conn: AxonServerBusSource, options?: AxonServerQueryBusOptions): SubscriptionCapableQueryBus<U>;
 //# sourceMappingURL=axon-server.d.ts.map

package/dist/axon-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"axon-server.d.ts","sourceRoot":"","sources":["../src/axon-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EACV,UAAU,EAEV,QAAQ,EAOT,MAAM,iBAAiB,CAAA;AAOxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAgB1D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B;;;;;;;;OAQG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACvC;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,2BAAgC,GACxC,UAAU,CAuOZ;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,QAAQ,EACf,OAAO,GAAE,yBAA8B,GACtC,QAAQ,CAojBV"}
+{"version":3,"file":"axon-server.d.ts","sourceRoot":"","sources":["../src/axon-server.ts"],"names":[],"mappings":"AACA,OAAO,EAA0D,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAkC9G,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EACV,UAAU,EAEV,QAAQ,EACR,2BAA2B,EAI3B,UAAU,EAEX,MAAM,iBAAiB,CAAA;AAMxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAiB1D;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACtC,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAA;CAEzB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B;;;;;;;;OAQG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACtC,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAA;CAEzB,CAAA;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACpE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EACnB,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE,2BAAgC,GACxC,UAAU,CAAC,CAAC,CAAC,CAuPf;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAClE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE,yBAA8B,GACtC,2BAA2B,CAAC,CAAC,CAAC,CA4nBhC"}