@kronos-ts/rabbitmq 0.1.0 → 0.2.0

package/src/query-bus.ts

@@ -0,0 +1,137 @@
+import type { QueryBus, QueryMessage, SubscriptionQueryResult } from "@kronos-ts/messaging"
+import { qualifiedNameToString } from "@kronos-ts/common"
+import { runInNewUoW } from "@kronos-ts/messaging"
+import type { RabbitMqResolvedConfig } from "./rabbitmq.js"
+
+export interface RabbitMqQueryEnvelope {
+  readonly kind: "query"
+  readonly requestId: string
+  readonly message: QueryMessage
+  readonly timeoutMs: number
+}
+
+export interface RabbitMqQueryReplyEnvelope {
+  readonly requestId: string
+  readonly ok: boolean
+  readonly result?: unknown
+  readonly error?: {
+    readonly name?: string
+    readonly message: string
+    readonly stack?: string
+  }
+}
+
+export interface RabbitMqQueryTransport {
+  dispatch(envelope: RabbitMqQueryEnvelope): Promise<RabbitMqQueryReplyEnvelope>
+  subscribe(
+    queryName: string,
+    handler: (envelope: RabbitMqQueryEnvelope) => Promise<RabbitMqQueryReplyEnvelope>,
+  ): void | Promise<void>
+}
+
+export interface RabbitMqQueryBusOptions {
+  readonly localSegment: QueryBus
+  readonly transport: RabbitMqQueryTransport
+  readonly config: RabbitMqResolvedConfig
+}
+
+/**
+ * Distributed query bus decorator.
+ *
+ * Direct request/reply queries (`query` + `subscribe`) route over RabbitMQ.
+ * Subscription queries (`subscriptionQuery`, `subscribeToUpdates`, `emitUpdate`,
+ * `completeSubscription*`) remain process-local and delegate to the local
+ * segment — distributing subscription-query update streams over RabbitMQ is
+ * intentionally out of scope for this version (see rabbitmq-extension-plan.md).
+ */
+export function createRabbitMqQueryBus(options: RabbitMqQueryBusOptions): QueryBus {
+  const localHandlers = new Set<string>()
+  const { localSegment, transport, config } = options
+
+  return {
+    async query(message: QueryMessage): Promise<unknown> {
+      const queryName = qualifiedNameToString(message.name)
+      const preferLocal = config.queries.preferLocalHandlers && !config.queries.alwaysUseDistributedBus
+      if (preferLocal && localHandlers.has(queryName)) {
+        return localSegment.query(message)
+      }
+
+      const envelope: RabbitMqQueryEnvelope = {
+        kind: "query",
+        requestId: message.identifier,
+        message,
+        timeoutMs: config.queries.defaultTimeoutMs,
+      }
+      const reply = await transport.dispatch(envelope)
+      if (!reply.ok) throw deserializeRemoteError(reply.error)
+      return reply.result
+    },
+
+    subscribe(queryName: string, handler: (message: QueryMessage) => Promise<unknown>): void {
+      localHandlers.add(queryName)
+      localSegment.subscribe(queryName, handler)
+      void transport.subscribe(queryName, async (envelope) => {
+        try {
+          // AF5 parity: an inbound distributed query is handled in its own
+          // fresh UnitOfWork. Correlation/causation lineage rides on the query
+          // message metadata, which crosses the wire intact.
+          const result = await runInNewUoW(envelope.message.metadata, () =>
+            handler(envelope.message),
+          )
+          return { requestId: envelope.requestId, ok: true, result }
+        } catch (error) {
+          return { requestId: envelope.requestId, ok: false, error: serializeError(error) }
+        }
+      })
+    },
+
+    // Subscription queries stay process-local — see the doc comment above.
+    subscriptionQuery(message: QueryMessage, bufferSize?: number): SubscriptionQueryResult {
+      return localSegment.subscriptionQuery(message, bufferSize)
+    },
+
+    subscribeToUpdates(
+      message: QueryMessage,
+      bufferSize?: number,
+    ): AsyncIterable<unknown> & { close(): void } {
+      return localSegment.subscribeToUpdates(message, bufferSize)
+    },
+
+    emitUpdate(
+      queryName: string,
+      filter: (queryPayload: unknown) => boolean,
+      update: unknown,
+    ): Promise<void> {
+      return localSegment.emitUpdate(queryName, filter, update)
+    },
+
+    completeSubscription(
+      queryName: string,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      return localSegment.completeSubscription(queryName, filter)
+    },
+
+    completeSubscriptionExceptionally(
+      queryName: string,
+      error: Error,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      return localSegment.completeSubscriptionExceptionally(queryName, error, filter)
+    },
+  }
+}
+
+function serializeError(error: unknown): RabbitMqQueryReplyEnvelope["error"] {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message, stack: error.stack }
+  }
+  return { message: String(error) }
+}
+
+function deserializeRemoteError(error: RabbitMqQueryReplyEnvelope["error"]): Error {
+  const result = new Error(error?.message ?? "Remote query handling failed")
+  result.name = error?.name ?? "RemoteQueryHandlingError"
+  if (error?.stack) result.stack = error.stack
+  return result
+}

package/src/rabbitmq.ts

@@ -1,7 +1,10 @@
 import type { App, KronosIdentity } from "@kronos-ts/app"
 import { createRabbitMqTopologyNames, type RabbitMqTopologyConfig } from "./topology.js"
 import { createRabbitMqCommandBus } from "./command-bus.js"
+import { createRabbitMqQueryBus } from "./query-bus.js"
 import { AmqpRabbitMqCommandTransport } from "./amqp-command-transport.js"
+import { AmqpRabbitMqQueryTransport } from "./amqp-query-transport.js"
+import { createAmqpConnection } from "./connection.js"
 
 export interface RabbitMqCommandDispatchConfig {
   /** Prefer local handlers when registered; otherwise route through RabbitMQ. Default: true. */
@@ -12,6 +15,15 @@ export interface RabbitMqCommandDispatchConfig {
   readonly defaultTimeoutMs?: number
 }
 
+export interface RabbitMqQueryDispatchConfig {
+  /** Prefer local handlers when registered; otherwise route through RabbitMQ. Default: true. */
+  readonly preferLocalHandlers?: boolean
+  /** Force all query dispatch through RabbitMQ, even when a local handler exists. */
+  readonly alwaysUseDistributedBus?: boolean
+  /** Default request/reply timeout for query dispatch. Default: 30000. */
+  readonly defaultTimeoutMs?: number
+}
+
 export interface RabbitMqRetryConfig {
   /** Dead-letter failed command messages instead of silently dropping them. Default: true. */
   readonly deadLetter?: boolean
@@ -23,6 +35,7 @@ export interface RabbitMqExtensionConfig {
   readonly url: string
   readonly topology?: RabbitMqTopologyConfig
   readonly commands?: RabbitMqCommandDispatchConfig
+  readonly queries?: RabbitMqQueryDispatchConfig
   readonly retry?: RabbitMqRetryConfig
 }
 
@@ -31,6 +44,7 @@ export interface RabbitMqResolvedConfig {
   readonly url: string
   readonly topology: ReturnType<typeof createRabbitMqTopologyNames>
   readonly commands: Required<RabbitMqCommandDispatchConfig>
+  readonly queries: Required<RabbitMqQueryDispatchConfig>
   readonly retry: Required<RabbitMqRetryConfig>
 }
 
@@ -44,6 +58,11 @@ export function resolveRabbitMqConfig(app: App, config: RabbitMqExtensionConfig)
       alwaysUseDistributedBus: config.commands?.alwaysUseDistributedBus ?? false,
       defaultTimeoutMs: config.commands?.defaultTimeoutMs ?? 30_000,
     },
+    queries: {
+      preferLocalHandlers: config.queries?.preferLocalHandlers ?? true,
+      alwaysUseDistributedBus: config.queries?.alwaysUseDistributedBus ?? false,
+      defaultTimeoutMs: config.queries?.defaultTimeoutMs ?? 30_000,
+    },
     retry: {
       deadLetter: config.retry?.deadLetter ?? true,
       deadLetterExchange: config.retry?.deadLetterExchange ?? `${config.topology?.prefix ?? "kronos"}.dlx`,
@@ -54,14 +73,17 @@ export function resolveRabbitMqConfig(app: App, config: RabbitMqExtensionConfig)
 /**
  * RabbitMQ distributed messaging extension.
  *
- * Command transport implementation is intentionally staged. The first committed
- * surface resolves app-level identity/topology and reserves the extension entry
- * point; the next step wires the command bus decorator around this config.
+ * Wraps the command and query buses with RabbitMQ-backed request/reply
+ * transports. Both transports share a single broker connection, each taking
+ * its own channel. Subscription queries remain process-local — distributing
+ * their update streams is out of scope for this version.
  */
 export function rabbitMq(config: RabbitMqExtensionConfig): (app: App) => void {
   return (app) => {
     const resolved = resolveRabbitMqConfig(app, config)
-    const commandTransport = new AmqpRabbitMqCommandTransport(resolved)
+    const connection = createAmqpConnection(resolved.url)
+    const commandTransport = new AmqpRabbitMqCommandTransport(resolved, connection)
+    const queryTransport = new AmqpRabbitMqQueryTransport(resolved, connection)
 
     app.decorate("commandBus", (localSegment) =>
       createRabbitMqCommandBus({
@@ -71,7 +93,18 @@ export function rabbitMq(config: RabbitMqExtensionConfig): (app: App) => void {
       }),
     )
 
+    app.decorate("queryBus", (localSegment) =>
+      createRabbitMqQueryBus({
+        localSegment,
+        transport: queryTransport,
+        config: resolved,
+      }),
+    )
+
     app.onStart("connect", () => commandTransport.connect())
+    app.onStart("connect", () => queryTransport.connect())
     app.onStop("connect", () => commandTransport.close())
+    app.onStop("connect", () => queryTransport.close())
+    app.onStop("connect", () => connection.close())
   }
 }

package/src/topology.ts

@@ -4,14 +4,19 @@ import type { KronosIdentity } from "@kronos-ts/app"
 export interface RabbitMqTopologyConfig {
   readonly prefix?: string
   readonly commandsExchange?: string
+  readonly queriesExchange?: string
   readonly durableQueues?: boolean
 }
 
 export interface RabbitMqTopologyNames {
   readonly commandsExchange: string
+  readonly queriesExchange: string
   commandRoutingKey(commandName: QualifiedName | string): string
   commandQueue(commandName: QualifiedName | string): string
-  replyQueue(): string
+  queryRoutingKey(queryName: QualifiedName | string): string
+  queryQueue(queryName: QualifiedName | string): string
+  commandReplyQueue(): string
+  queryReplyQueue(): string
 }
 
 export function createRabbitMqTopologyNames(
@@ -22,18 +27,29 @@ export function createRabbitMqTopologyNames(
   const service = sanitizeSegment(identity.serviceName)
   const instance = sanitizeSegment(identity.instanceId)
   const commandsExchange = config.commandsExchange ?? `${prefix}.commands`
+  const queriesExchange = config.queriesExchange ?? `${prefix}.queries`
 
   return {
     commandsExchange,
+    queriesExchange,
     commandRoutingKey(commandName) {
       return messageName(commandName)
     },
     commandQueue(commandName) {
       return `${prefix}.commands.${service}.${sanitizeMessageName(messageName(commandName))}`
     },
-    replyQueue() {
+    queryRoutingKey(queryName) {
+      return messageName(queryName)
+    },
+    queryQueue(queryName) {
+      return `${prefix}.queries.${service}.${sanitizeMessageName(messageName(queryName))}`
+    },
+    commandReplyQueue() {
       return `${prefix}.replies.${service}.${instance}`
     },
+    queryReplyQueue() {
+      return `${prefix}.query-replies.${service}.${instance}`
+    },
   }
 }