@btravstack/amqp-worker 0.9.0 → 0.11.0

package/README.md

@@ -13,7 +13,7 @@
 
 ```sh
 pnpm add @btravstack/amqp-worker @btravstack/core @btravstack/config @btravstack/di unthrown \
-  @amqp-contract/worker @opentelemetry/api
+  @amqp-contract/worker@^3.0.0-beta.7 @opentelemetry/api
 ```
 
 All six are peer dependencies — install them (`@opentelemetry/api` because
@@ -23,20 +23,79 @@ All six are peer dependencies — install them (`@opentelemetry/api` because
 
 <!-- doctest: prelude
 import { NonRetryableError, RetryableError } from "@amqp-contract/worker";
-import { orderContract } from "@btravstack/example-order-amqp-contract";
-import { PlaceOrder } from "@btravstack/example-order-application";
-import { TenantId } from "@btravstack/example-order-domain";
-import { Module } from "@btravstack/di";
-import { OrderApplicationModule, OrderRepository, Outbox } from "@btravstack/example-order-application";
-import { OrderPersistenceModule } from "@btravstack/example-order-infrastructure";
+import {
+  defineContract,
+  defineEventConsumer,
+  defineEventPublisher,
+  defineExchange,
+  defineMessage,
+  defineQueue,
+} from "@amqp-contract/contract";
+import { Module, Port, type AnyModule } from "@btravstack/di";
+import { TaggedError, type AsyncResult } from "unthrown";
 import { observability } from "@btravstack/observability";
 import { otel } from "@btravstack/observability/otel";
+import { z } from "zod";
+
+// The contract this README's worker serves: one event, broadcast to two
+// subscribers' queues. It is the application's own artifact — a client takes
+// it without this package.
+const orders = defineExchange("orders");
+const parked = defineExchange("orders-dlx", { type: "direct" });
+const orderChanged = defineMessage(
+  z.object({
+    tenantId: z.uuidv7(),
+    kind: z.literal("order"),
+    id: z.uuidv7(),
+    occurredAt: z.string(),
+    payload: z.object({ quantity: z.number() }).nullable(),
+  }),
+);
+const orderChangedEvent = defineEventPublisher(orders, orderChanged, {
+  routingKey: "order.changed",
+});
+const queueOptions = {
+  deadLetter: { exchange: parked, externalConsumers: true },
+  retry: { mode: "ttl-backoff", maxRetries: 3, initialDelayMs: 10 },
+} as const;
+const orderContract = defineContract({
+  publishers: { orderChanged: orderChangedEvent },
+  consumers: {
+    orderNotifications: defineEventConsumer(
+      orderChangedEvent,
+      defineQueue("order-notifications", queueOptions),
+    ),
+    orderAudit: defineEventConsumer(
+      orderChangedEvent,
+      defineQueue("order-audit", queueOptions),
+    ),
+  },
+});
+
+// The application's own layers, declared here for the same reason: the use
+// case, its errors and its tenant id are yours, not this package's.
+class DuplicateOrder extends TaggedError("DuplicateOrder")<{ readonly id: string }> {}
+class InvalidOrderId extends TaggedError("InvalidOrderId")<{ readonly id: string }> {}
+class InvalidQuantity extends TaggedError("InvalidQuantity")<{ readonly id: string }> {}
+declare const TenantId: (value: string) => string;
+class PlaceOrder extends Port("PlaceOrder")<{
+  readonly execute: (
+    tenantId: string,
+    id: string,
+    quantity: number,
+  ) => AsyncResult<
+    { readonly id: string },
+    DuplicateOrder | InvalidOrderId | InvalidQuantity
+  >;
+}> {}
+declare const OrderApplicationModule: Module<PlaceOrder, never, never>;
+declare const OrderPersistenceModule: AnyModule;
 
 // The application module the README's composition imports — the orders
 // vertical plus its persistence, as an application would compose it.
 const AppModule = Module("App")({
   imports: [OrderApplicationModule, OrderPersistenceModule, observability(), otel()],
-  exports: [PlaceOrder, OrderRepository, Outbox, Logger],
+  exports: [PlaceOrder, Logger],
 });
 -->
 
@@ -53,7 +112,7 @@ import { ErrAsync, OkAsync, P } from "unthrown";
 const orderHandlers = AmqpHandlers(orderContract)({
   inject: { placeOrder: PlaceOrder },
   sync: ({ placeOrder }) => ({
-    orderNotifications: (message) =>
+    orderNotifications: ({ input: message }) =>
       placeOrder
         .execute(
           TenantId(message.payload.tenantId),
@@ -102,9 +161,15 @@ rpc, typed by the key alone, and `AmqpHandlers(contract)([...])` composes an
 array of them into the same handlers provider `AmqpModule` takes — the array
 must cover every key the contract declares, and each piece's own port must
 still be discharged (`provides`), since the composed provider's deps are the
-pieces' ports, not what they close over. Two slices claiming one key are di's
-duplicate-provider defect at build, which is the point: a consumer belongs to
-exactly one slice.
+pieces' ports, not what they close over. A consumer belongs to exactly one slice, and the
+compiler holds only half of that: coverage is checked, injectivity is not, so
+two slices claiming one key type-check together. It is di's duplicate-provider
+defect at build once **both** pieces are discharged as providers in one graph
+— wire in only one and the other's handler is silently never registered.
+
+Its own test suite needs a **Docker daemon**: the specs run against the shared
+`rabbitmq` container `internal/test-infra` starts once per machine and every
+workspace reuses. Nothing else here does.
 
 ## Options
 

package/dist/index.cjs

@@ -34,7 +34,17 @@ const AmqpHandler = (contract, key) => {
 * handler that must stop when the kernel stops waiting reads
 * `currentUnit()?.signal`.
 */
-const messageUnits = (host) => (args, next) => host.run(metaFor(args.rawMessage), () => next());
+const messageUnits = (host, observers) => (args, next) => {
+	const settle = (0, _btravstack_core.observe)(observers, {
+		component: "amqp",
+		name: "delivery",
+		attributes: { handler: args.handlerName }
+	});
+	return host.run(metaFor(args.rawMessage), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+		outcome: "error",
+		cause: failure.tag === "Err" ? failure.error : failure.cause
+	}));
+};
 /**
 * `UnitMeta.id` must be unique per unit, and a **delivery tag is not one**: tags
 * are per-channel and restart at `1` after a reconnect, which
@@ -115,17 +125,25 @@ const amqp = (options) => {
 	}));
 	return (0, _btravstack_di.Module)("Amqp")({
 		needs: [_btravstack_config.Env, AmqpHandlersPort],
-		provides: [config, (0, _btravstack_di.Provider)(AmqpRuntime)({
-			inject: {
-				config: AmqpConfig,
-				handlers: AmqpHandlersPort
-			},
-			sync: ({ config: bound, handlers }) => ({
-				name: "amqp",
-				resolves: [],
-				start: (host) => createWorker(host, bound, options, handlers)
+		provides: [
+			config,
+			_btravstack_di.Provider.member(_btravstack_core.Observers)({
+				inject: {},
+				value: _btravstack_core.noObserver
+			}),
+			(0, _btravstack_di.Provider)(AmqpRuntime)({
+				inject: {
+					config: AmqpConfig,
+					handlers: AmqpHandlersPort,
+					observers: _btravstack_core.Observers
+				},
+				sync: ({ config: bound, handlers, observers }) => ({
+					name: "amqp",
+					resolves: [],
+					start: (host) => createWorker(host, bound, options, handlers, observers)
+				})
 			})
-		})],
+		],
 		exports: [AmqpRuntime, AmqpConfig]
 	});
 };
@@ -165,15 +183,15 @@ const queuesOf = (contract) => [...new Set(Object.values({
 	...contract.consumers,
 	...contract.rpcs
 }).map((entry) => entry.queue.name))].sort();
-const createWorker = (host, config, options, handlers) => _amqp_contract_worker.TypedAmqpWorker.create({
+const createWorker = (host, config, options, handlers, observers) => _amqp_contract_worker.TypedAmqpWorker.create({
 	contract: options.contract,
 	handlers,
-	middleware: messageUnits(host),
+	middleware: messageUnits(host, observers),
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
 	connectTimeoutMs: config.connectTimeoutMs
-}).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => (0, unthrown.ErrAsync)(startFailed(cause)));
+}).map((worker) => consume(worker, queuesOf(options.contract))).mapErrCases((matcher) => matcher.with(unthrown.P.tag("@amqp-contract/ConnectionError"), (error) => startFailed(error)));
 const consume = (worker, queues) => {
 	let closing;
 	const beginClose = () => closing ??= worker.close({ drainTimeoutMs: null });

package/dist/index.d.cts

@@ -110,6 +110,19 @@ type KeyOfPiece<P> = P extends {
 } ? K : never;
 /** The consumers and rpcs no piece in `T` covers. */
 type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exclude<HandlerKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -119,7 +132,7 @@ type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exc
  * The marker is a sentence rather than a bare label because it prints last,
  * after the caller's own several-hundred-character piece type.
  */
-type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>]) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
+type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>>) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
   readonly port: HandlersPortOf<C>;
 };
 /**

package/dist/index.d.mts

@@ -110,6 +110,19 @@ type KeyOfPiece<P> = P extends {
 } ? K : never;
 /** The consumers and rpcs no piece in `T` covers. */
 type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exclude<HandlerKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -119,7 +132,7 @@ type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exc
  * The marker is a sentence rather than a bare label because it prints last,
  * after the caller's own several-hundred-character piece type.
  */
-type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>]) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
+type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>>) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
   readonly port: HandlersPortOf<C>;
 };
 /**

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { Module, Port, Provider } from "@btravstack/di";
 import { TypedAmqpWorker } from "@amqp-contract/worker";
 import { Config, Env } from "@btravstack/config";
-import { RuntimePort, RuntimeStartFailed, releasedBy } from "@btravstack/core";
-import { ErrAsync } from "unthrown";
+import { Observers, RuntimePort, RuntimeStartFailed, noObserver, observe, releasedBy } from "@btravstack/core";
+import { P } from "unthrown";
 import { randomUUID } from "node:crypto";
 //#region src/handler.ts
 /** The prefix a piece's port id carries; the composing form strips it to recover the key. */
@@ -33,7 +33,17 @@ const AmqpHandler = (contract, key) => {
 * handler that must stop when the kernel stops waiting reads
 * `currentUnit()?.signal`.
 */
-const messageUnits = (host) => (args, next) => host.run(metaFor(args.rawMessage), () => next());
+const messageUnits = (host, observers) => (args, next) => {
+	const settle = observe(observers, {
+		component: "amqp",
+		name: "delivery",
+		attributes: { handler: args.handlerName }
+	});
+	return host.run(metaFor(args.rawMessage), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+		outcome: "error",
+		cause: failure.tag === "Err" ? failure.error : failure.cause
+	}));
+};
 /**
 * `UnitMeta.id` must be unique per unit, and a **delivery tag is not one**: tags
 * are per-channel and restart at `1` after a reconnect, which
@@ -114,17 +124,25 @@ const amqp = (options) => {
 	}));
 	return Module("Amqp")({
 		needs: [Env, AmqpHandlersPort],
-		provides: [config, Provider(AmqpRuntime)({
-			inject: {
-				config: AmqpConfig,
-				handlers: AmqpHandlersPort
-			},
-			sync: ({ config: bound, handlers }) => ({
-				name: "amqp",
-				resolves: [],
-				start: (host) => createWorker(host, bound, options, handlers)
+		provides: [
+			config,
+			Provider.member(Observers)({
+				inject: {},
+				value: noObserver
+			}),
+			Provider(AmqpRuntime)({
+				inject: {
+					config: AmqpConfig,
+					handlers: AmqpHandlersPort,
+					observers: Observers
+				},
+				sync: ({ config: bound, handlers, observers }) => ({
+					name: "amqp",
+					resolves: [],
+					start: (host) => createWorker(host, bound, options, handlers, observers)
+				})
 			})
-		})],
+		],
 		exports: [AmqpRuntime, AmqpConfig]
 	});
 };
@@ -164,15 +182,15 @@ const queuesOf = (contract) => [...new Set(Object.values({
 	...contract.consumers,
 	...contract.rpcs
 }).map((entry) => entry.queue.name))].sort();
-const createWorker = (host, config, options, handlers) => TypedAmqpWorker.create({
+const createWorker = (host, config, options, handlers, observers) => TypedAmqpWorker.create({
 	contract: options.contract,
 	handlers,
-	middleware: messageUnits(host),
+	middleware: messageUnits(host, observers),
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
 	connectTimeoutMs: config.connectTimeoutMs
-}).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => ErrAsync(startFailed(cause)));
+}).map((worker) => consume(worker, queuesOf(options.contract))).mapErrCases((matcher) => matcher.with(P.tag("@amqp-contract/ConnectionError"), (error) => startFailed(error)));
 const consume = (worker, queues) => {
 	let closing;
 	const beginClose = () => closing ??= worker.close({ drainTimeoutMs: null });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/amqp-worker",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "The AMQP starter for @btravstack/core: the handlers as a port, one unit per delivery, and a drain the kernel's deadline releases",
   "keywords": [
     "amqp",
@@ -44,9 +44,9 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@amqp-contract/contract": "3.0.0-beta.6",
-    "@amqp-contract/testing": "3.0.0-beta.6",
-    "@amqp-contract/worker": "3.0.0-beta.6",
+    "@amqp-contract/contract": "3.0.0-beta.7",
+    "@amqp-contract/testing": "3.0.0-beta.7",
+    "@amqp-contract/worker": "3.0.0-beta.7",
     "@btravstack/tsconfig": "0.2.0",
     "@opentelemetry/api": "1.9.1",
     "@types/node": "26.4.0",
@@ -56,20 +56,20 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "zod": "4.5.1",
-    "@btravstack/config": "0.9.0",
-    "@btravstack/core": "0.9.0",
-    "@btravstack/di": "0.9.0",
+    "zod": "4.5.3",
+    "@btravstack/config": "0.11.0",
+    "@btravstack/core": "0.11.0",
+    "@btravstack/di": "0.11.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.9.0"
+    "@btravstack/testing": "0.11.0"
   },
   "peerDependencies": {
-    "@amqp-contract/worker": "^3.0.0-beta.6",
+    "@amqp-contract/worker": "^3.0.0-beta.7",
     "@opentelemetry/api": "^1",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.9.0",
-    "@btravstack/core": "^0.9.0",
-    "@btravstack/di": "^0.9.0"
+    "@btravstack/config": "^0.11.0",
+    "@btravstack/core": "^0.11.0",
+    "@btravstack/di": "^0.11.0"
   },
   "engines": {
     "node": ">=22"