@btravstack/amqp-worker 0.45.1 → 0.46.0

package/README.md

@@ -13,7 +13,7 @@
 
 ```sh
 pnpm add @btravstack/amqp-worker @btravstack/core @btravstack/config @btravstack/di unthrown \
-  @amqp-contract/worker@^3.0.0-beta.7 @opentelemetry/api
+  @amqp-contract/worker@^3.0.0-beta.11 @opentelemetry/api
 ```
 
 All six are peer dependencies — install them (`@opentelemetry/api` because
@@ -221,3 +221,13 @@ It keeps private infrastructure hidden and business exports explicit.
 ## License
 
 [MIT](./LICENSE) © Benoit TRAVERS
+
+## Broadcast subscriptions
+
+`amqpSubscription(name, { contract, settings, inject?, sync })` consumes
+best-effort facts beside an HTTP runtime, with one exclusive ephemeral queue
+per replica. It reports failures and broker health and closes with the scope.
+`InvalidAmqpSubscription` names a refused configuration;
+`SubscriptionHandlers<C, E>` types the contract's handler record.
+See [the subscription reference](https://btravstack.github.io/btravstack/reference/amqp-worker#broadcast-subscriptions-beside-another-runtime)
+for the typed contract, settings port and delivery guarantees.

package/dist/index.cjs

@@ -327,9 +327,77 @@ const AmqpModule = (name) => (options) => {
 	});
 };
 //#endregion
+//#region src/subscription.ts
+/** A subscription requires explicitly ephemeral queues with no retry or dead-letter routing. */
+var InvalidAmqpSubscription = class extends (0, unthrown.TaggedError)("InvalidAmqpSubscription") {
+	message = "subscriptions require consumers on exclusive auto-delete non-durable classic queues with no retry or dead letter, and no RPCs";
+};
+/**
+* Consume broadcast facts for the application scope's lifetime, beside its one
+* runtime. Every validated delivery is acknowledged, including handler failures;
+* failures are reported to Observers. Each replica must name its own queues.
+*/
+const amqpSubscription = (name, options) => {
+	const resource = (0, _btravstack_di.Port)(`AmqpSubscription:${name}`);
+	return (0, _btravstack_di.Module)(`AmqpSubscription:${name}`)({
+		provides: [
+			_btravstack_core.noObserverMember,
+			(0, _btravstack_di.Provider)(resource)({
+				inject: {
+					settings: options.settings,
+					observers: _btravstack_core.Observers,
+					...Object.fromEntries(Object.entries(options.inject ?? {}).map(([key, port]) => [`dependency:${key}`, port]))
+				},
+				acquire: (services) => {
+					const consumers = Object.values(options.contract.consumers ?? {});
+					if (consumers.length === 0 || Object.keys(options.contract.rpcs ?? {}).length > 0 || consumers.some(({ queue }) => queue.type !== "classic" || queue.durable || queue.exclusive !== true || queue.autoDelete !== true || queue.retry.mode !== "none" || queue.deadLetter !== void 0 || queue.arguments?.["x-dead-letter-exchange"] !== void 0)) return (0, unthrown.ErrAsync)(new InvalidAmqpSubscription({ subscription: name }));
+					const dependencies = Object.fromEntries(Object.keys(options.inject ?? {}).map((key) => [key, services[`dependency:${key}`]]));
+					const handlers = options.sync(dependencies);
+					const observers = services.observers;
+					const wrapped = Object.fromEntries(Object.entries(handlers).map(([key, handler]) => [key, (...args) => {
+						const settle = (0, _btravstack_core.observe)(observers, {
+							component: "amqp",
+							name: "subscription",
+							attributes: {
+								subscription: name,
+								consumer: key
+							}
+						});
+						return (0, unthrown.fromSafePromise)((async () => {
+							const result = await (0, unthrown.OkAsync)().flatMap(() => handler(...args) ?? (0, unthrown.Ok)());
+							settle(result.isOk() ? { outcome: "ok" } : {
+								outcome: "error",
+								cause: result.isErr() ? result.error : result.cause
+							});
+						})());
+					}]));
+					return _amqp_contract_worker.TypedAmqpWorker.create({
+						contract: options.contract,
+						handlers: wrapped,
+						urls: [services.settings.url],
+						connectTimeoutMs: services.settings.connectTimeoutMs ?? 5e3,
+						logger: brokerLog(observers)
+					});
+				},
+				release: (worker) => worker.close().get()
+			}),
+			_btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
+				inject: { worker: resource },
+				sync: ({ worker }) => ({
+					name: `amqp-subscription:${name}`,
+					check: () => worker.isConnected() ? (0, unthrown.OkAsync)() : (0, unthrown.ErrAsync)(new _btravstack_core.HealthCheckFailed({ reason: "broker disconnected" }))
+				})
+			})
+		],
+		exports: [_btravstack_core.HealthChecks]
+	});
+};
+//#endregion
 exports.AmqpConfig = AmqpConfig;
 exports.AmqpHandler = AmqpHandler;
 exports.AmqpHandlers = AmqpHandlers;
 exports.AmqpMessage = AmqpMessage;
 exports.AmqpModule = AmqpModule;
 exports.AmqpRuntime = AmqpRuntime;
+exports.InvalidAmqpSubscription = InvalidAmqpSubscription;
+exports.amqpSubscription = amqpSubscription;

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import { ConfigInvalid, EnvReading } from "@btravstack/config";
-import { AnyUnitModule, Refuse, Runtime, RuntimePort, UnitGate, UnitNeedsOf, UnitRecordOf } from "@btravstack/core";
-import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, ServiceOf } from "@btravstack/di";
-import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
+import { AnyUnitModule, HealthChecks, Refuse, Runtime, RuntimePort, UnitGate, UnitNeedsOf, UnitRecordOf } from "@btravstack/core";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope, ServiceOf } from "@btravstack/di";
+import { ConnectionError, ConsumerOptions, TypedAmqpWorker, WorkerInferConsumerHandler, WorkerInferHandlers } from "@amqp-contract/worker";
+import { AsyncResult, Result } from "unthrown";
 //#region src/handler.d.ts
 /** The consumer and rpc names `C` declares — the keys of its handlers record. */
 type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & string;
@@ -276,4 +277,31 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
  */
 export declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared = never, Unit extends AnyUnitModule | undefined = undefined, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] | undefined = undefined>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, Declared, Unit, I, P, X, N>) => Module<(Extract<(readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> extends (infer T_2) ? T_2 extends Extract<(readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> ? T_2 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number] extends (infer E_1) ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never), ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[1] | ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_4 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]> | Exclude<((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]>>;
 //#endregion
-export type { AmqpConnectionOptions, AmqpInfo, AmqpMessageOf, AmqpMessagePortOf, AmqpModuleOptions, AmqpOptions, HandlerPortOf, HandlersInstanceOf, HandlersPortOf };
+//#region src/subscription.d.ts
+declare const InvalidAmqpSubscription_base: import("unthrown").TaggedErrorConstructor<"InvalidAmqpSubscription">;
+/** A subscription requires explicitly ephemeral queues with no retry or dead-letter routing. */
+export declare class InvalidAmqpSubscription extends InvalidAmqpSubscription_base<{
+  readonly subscription: string;
+}> {
+  message: string;
+}
+/** Best-effort handlers retain their contract's typed input and may run synchronously. */
+type SubscriptionHandlers<C extends AnyAmqpContract, E> = { readonly [K in C["consumers"] extends Record<string, unknown> ? keyof C["consumers"] : never]: (...args: Parameters<WorkerInferConsumerHandler<C, K>>) => void | Result<void, E> | AsyncResult<void, E>; };
+/**
+ * Consume broadcast facts for the application scope's lifetime, beside its one
+ * runtime. Every validated delivery is acknowledged, including handler failures;
+ * failures are reported to Observers. Each replica must name its own queues.
+ */
+export declare const amqpSubscription: <C extends AnyAmqpContract, Settings extends {
+  readonly url: string;
+  readonly connectTimeoutMs?: number;
+}, const SettingsId extends string, E, const D extends Readonly<Record<string, AnyPort>> = Record<never, never>>(name: string, options: {
+  readonly contract: C;
+  readonly settings: PortClassOf<SettingsId, Settings>;
+  readonly inject?: D;
+  readonly sync: (services: { readonly [K in keyof D]: ServiceOf<InstanceType<D[K]>>; }) => SubscriptionHandlers<C, E>;
+} & ([keyof D] extends [never] ? unknown : {
+  readonly inject: D;
+})) => Module<HealthChecks, ConnectionError | InvalidAmqpSubscription, InstanceType<PortClassOf<SettingsId, Settings>> | InstanceType<D[keyof D]> | Scope>;
+//#endregion
+export type { AmqpConnectionOptions, AmqpInfo, AmqpMessageOf, AmqpMessagePortOf, AmqpModuleOptions, AmqpOptions, HandlerPortOf, HandlersInstanceOf, HandlersPortOf, SubscriptionHandlers };

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { AnyUnitModule, Refuse, Runtime, RuntimePort, UnitGate, UnitNeedsOf, UnitRecordOf } from "@btravstack/core";
-import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, ServiceOf } from "@btravstack/di";
-import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
+import { AnyUnitModule, HealthChecks, Refuse, Runtime, RuntimePort, UnitGate, UnitNeedsOf, UnitRecordOf } from "@btravstack/core";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope, ServiceOf } from "@btravstack/di";
+import { ConnectionError, ConsumerOptions, TypedAmqpWorker, WorkerInferConsumerHandler, WorkerInferHandlers } from "@amqp-contract/worker";
 import { ConfigInvalid, EnvReading } from "@btravstack/config";
+import { AsyncResult, Result } from "unthrown";
 //#region src/handler.d.ts
 /** The consumer and rpc names `C` declares — the keys of its handlers record. */
 type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & string;
@@ -276,4 +277,31 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
  */
 export declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared = never, Unit extends AnyUnitModule | undefined = undefined, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] | undefined = undefined>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, Declared, Unit, I, P, X, N>) => Module<(Extract<(readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> extends (infer T_2) ? T_2 extends Extract<(readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> ? T_2 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [typeof AmqpRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T) ? T extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : never : never) | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number] extends (infer E_1) ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never), ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[1] | ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_4 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]> | Exclude<((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, AmqpStarter<TContract, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]>>;
 //#endregion
-export type { AmqpConnectionOptions, AmqpInfo, AmqpMessageOf, AmqpMessagePortOf, AmqpModuleOptions, AmqpOptions, HandlerPortOf, HandlersInstanceOf, HandlersPortOf };
+//#region src/subscription.d.ts
+declare const InvalidAmqpSubscription_base: import("unthrown").TaggedErrorConstructor<"InvalidAmqpSubscription">;
+/** A subscription requires explicitly ephemeral queues with no retry or dead-letter routing. */
+export declare class InvalidAmqpSubscription extends InvalidAmqpSubscription_base<{
+  readonly subscription: string;
+}> {
+  message: string;
+}
+/** Best-effort handlers retain their contract's typed input and may run synchronously. */
+type SubscriptionHandlers<C extends AnyAmqpContract, E> = { readonly [K in C["consumers"] extends Record<string, unknown> ? keyof C["consumers"] : never]: (...args: Parameters<WorkerInferConsumerHandler<C, K>>) => void | Result<void, E> | AsyncResult<void, E>; };
+/**
+ * Consume broadcast facts for the application scope's lifetime, beside its one
+ * runtime. Every validated delivery is acknowledged, including handler failures;
+ * failures are reported to Observers. Each replica must name its own queues.
+ */
+export declare const amqpSubscription: <C extends AnyAmqpContract, Settings extends {
+  readonly url: string;
+  readonly connectTimeoutMs?: number;
+}, const SettingsId extends string, E, const D extends Readonly<Record<string, AnyPort>> = Record<never, never>>(name: string, options: {
+  readonly contract: C;
+  readonly settings: PortClassOf<SettingsId, Settings>;
+  readonly inject?: D;
+  readonly sync: (services: { readonly [K in keyof D]: ServiceOf<InstanceType<D[K]>>; }) => SubscriptionHandlers<C, E>;
+} & ([keyof D] extends [never] ? unknown : {
+  readonly inject: D;
+})) => Module<HealthChecks, ConnectionError | InvalidAmqpSubscription, InstanceType<PortClassOf<SettingsId, Settings>> | InstanceType<D[keyof D]> | Scope>;
+//#endregion
+export type { AmqpConnectionOptions, AmqpInfo, AmqpMessageOf, AmqpMessagePortOf, AmqpModuleOptions, AmqpOptions, HandlerPortOf, HandlersInstanceOf, HandlersPortOf, SubscriptionHandlers };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { Observers, RuntimePort, RuntimeStartFailed, composeByPrefix, dispatchUnit, infrastructureExports, mintPiece, noObserverMember, observe, releasedBy, traceIdOfTraceparent, withUnitRecord } from "@btravstack/core";
+import { HealthCheckFailed, HealthChecks, Observers, RuntimePort, RuntimeStartFailed, composeByPrefix, dispatchUnit, infrastructureExports, mintPiece, noObserverMember, observe, releasedBy, traceIdOfTraceparent, withUnitRecord } from "@btravstack/core";
 import { Module, Port, Provider } from "@btravstack/di";
 import { TypedAmqpWorker } from "@amqp-contract/worker";
 import { Config, Env } from "@btravstack/config";
-import { P } from "unthrown";
+import { ErrAsync, Ok, OkAsync, P, TaggedError, fromSafePromise } from "unthrown";
 import { randomUUID } from "node:crypto";
 //#region src/broker-log.ts
 /**
@@ -326,4 +326,70 @@ const AmqpModule = (name) => (options) => {
 	});
 };
 //#endregion
-export { AmqpConfig, AmqpHandler, AmqpHandlers, AmqpMessage, AmqpModule, AmqpRuntime };
+//#region src/subscription.ts
+/** A subscription requires explicitly ephemeral queues with no retry or dead-letter routing. */
+var InvalidAmqpSubscription = class extends TaggedError("InvalidAmqpSubscription") {
+	message = "subscriptions require consumers on exclusive auto-delete non-durable classic queues with no retry or dead letter, and no RPCs";
+};
+/**
+* Consume broadcast facts for the application scope's lifetime, beside its one
+* runtime. Every validated delivery is acknowledged, including handler failures;
+* failures are reported to Observers. Each replica must name its own queues.
+*/
+const amqpSubscription = (name, options) => {
+	const resource = Port(`AmqpSubscription:${name}`);
+	return Module(`AmqpSubscription:${name}`)({
+		provides: [
+			noObserverMember,
+			Provider(resource)({
+				inject: {
+					settings: options.settings,
+					observers: Observers,
+					...Object.fromEntries(Object.entries(options.inject ?? {}).map(([key, port]) => [`dependency:${key}`, port]))
+				},
+				acquire: (services) => {
+					const consumers = Object.values(options.contract.consumers ?? {});
+					if (consumers.length === 0 || Object.keys(options.contract.rpcs ?? {}).length > 0 || consumers.some(({ queue }) => queue.type !== "classic" || queue.durable || queue.exclusive !== true || queue.autoDelete !== true || queue.retry.mode !== "none" || queue.deadLetter !== void 0 || queue.arguments?.["x-dead-letter-exchange"] !== void 0)) return ErrAsync(new InvalidAmqpSubscription({ subscription: name }));
+					const dependencies = Object.fromEntries(Object.keys(options.inject ?? {}).map((key) => [key, services[`dependency:${key}`]]));
+					const handlers = options.sync(dependencies);
+					const observers = services.observers;
+					const wrapped = Object.fromEntries(Object.entries(handlers).map(([key, handler]) => [key, (...args) => {
+						const settle = observe(observers, {
+							component: "amqp",
+							name: "subscription",
+							attributes: {
+								subscription: name,
+								consumer: key
+							}
+						});
+						return fromSafePromise((async () => {
+							const result = await OkAsync().flatMap(() => handler(...args) ?? Ok());
+							settle(result.isOk() ? { outcome: "ok" } : {
+								outcome: "error",
+								cause: result.isErr() ? result.error : result.cause
+							});
+						})());
+					}]));
+					return TypedAmqpWorker.create({
+						contract: options.contract,
+						handlers: wrapped,
+						urls: [services.settings.url],
+						connectTimeoutMs: services.settings.connectTimeoutMs ?? 5e3,
+						logger: brokerLog(observers)
+					});
+				},
+				release: (worker) => worker.close().get()
+			}),
+			Provider.member(HealthChecks)({
+				inject: { worker: resource },
+				sync: ({ worker }) => ({
+					name: `amqp-subscription:${name}`,
+					check: () => worker.isConnected() ? OkAsync() : ErrAsync(new HealthCheckFailed({ reason: "broker disconnected" }))
+				})
+			})
+		],
+		exports: [HealthChecks]
+	});
+};
+//#endregion
+export { AmqpConfig, AmqpHandler, AmqpHandlers, AmqpMessage, AmqpModule, AmqpRuntime, InvalidAmqpSubscription, amqpSubscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/amqp-worker",
-  "version": "0.45.1",
+  "version": "0.46.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",
@@ -47,11 +47,11 @@
     "@amqp-contract/contract": "3.0.0-beta.11",
     "@amqp-contract/testing": "3.0.0-beta.11",
     "@amqp-contract/worker": "3.0.0-beta.11",
-    "@btravstack/config": "0.45.1",
-    "@btravstack/core": "0.45.1",
-    "@btravstack/di": "0.45.1",
+    "@btravstack/config": "0.46.0",
+    "@btravstack/core": "0.46.0",
+    "@btravstack/di": "0.46.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.45.1",
+    "@btravstack/testing": "0.46.0",
     "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
     "@types/node": "26.6.5",
@@ -65,12 +65,12 @@
     "zod": "4.6.7"
   },
   "peerDependencies": {
-    "@amqp-contract/worker": "^3.0.0-beta.7",
-    "@btravstack/config": "^0.45.1",
-    "@btravstack/core": "^0.45.1",
-    "@btravstack/di": "^0.45.1",
+    "@amqp-contract/worker": "^3.0.0-beta.11",
+    "@btravstack/config": "^0.46.0",
+    "@btravstack/core": "^0.46.0",
+    "@btravstack/di": "^0.46.0",
     "@opentelemetry/api": "^1",
-    "unthrown": "^5.7.0"
+    "unthrown": "^5.11.0"
   },
   "engines": {
     "node": ">=22.22"