diff --git a/en/api/@connectum/events-amqp/functions/AmqpAdapter.md b/en/api/@connectum/events-amqp/functions/AmqpAdapter.md index 96ca05a..96fd248 100644 --- a/en/api/@connectum/events-amqp/functions/AmqpAdapter.md +++ b/en/api/@connectum/events-amqp/functions/AmqpAdapter.md @@ -4,7 +4,7 @@ > **AmqpAdapter**(`options`): `EventAdapter` -Defined in: [packages/events-amqp/src/AmqpAdapter.ts:401](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L401) +Defined in: [packages/events-amqp/src/AmqpAdapter.ts:442](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L442) Create an AMQP/RabbitMQ adapter for @connectum/events. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md index 6c88313..74cf3d1 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md @@ -103,7 +103,7 @@ false > `readonly` `optional` **lifecycle?**: [`AmqpLifecycleCallbacks`](AmqpLifecycleCallbacks.md) -Defined in: [packages/events-amqp/src/types.ts:196](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L196) +Defined in: [packages/events-amqp/src/types.ts:197](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L197) Connection lifecycle callbacks. Connection errors are surfaced here — not just logged. @@ -124,7 +124,7 @@ Publisher options. > `readonly` `optional` **publishTimeoutMs?**: `number` -Defined in: [packages/events-amqp/src/types.ts:206](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L206) +Defined in: [packages/events-amqp/src/types.ts:207](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L207) Per-publish broker-outcome deadline in milliseconds. A publish whose ack/nack/return/connection-loss outcome does not arrive in time @@ -263,7 +263,7 @@ How topology is established: > `readonly` `optional` **treatTopologyErrorAsFatal?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:190](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L190) +Defined in: [packages/events-amqp/src/types.ts:191](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L191) Treat DETERMINISTIC topology drift during steady-state recovery as fatal: stop the reconnect cycle instead of retrying forever against a @@ -293,10 +293,11 @@ re-subscribe explicitly. Scope: steady-state recovery only. Boot-time drift is the startup probe's job — see [failFastOnInitialSetupError](#failfastoninitialsetuperror). Setting both -covers boot and steady state; the remaining gap — broker unreachable at -`connect()` time with drift surfacing before the first successful -connect — is covered by neither flag until the bounded initial phase -lands ([https://github.com/Connectum-Framework/connectum/issues/198](https://github.com/Connectum-Framework/connectum/issues/198)). +covers boot and steady state; the remaining window — broker unreachable +at `connect()` time with drift surfacing before the first successful +connect — is closed by +[AmqpRecoveryOptions.initialConnectMaxRetries](AmqpRecoveryOptions.md#initialconnectmaxretries) (since 1.3.0), +whose bounded phase surfaces those failures and rejects on exhaustion. #### Default diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md index be9c125..53dd002 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md @@ -2,7 +2,7 @@ # Interface: AmqpBindingDeclaration -Defined in: [packages/events-amqp/src/types.ts:266](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L266) +Defined in: [packages/events-amqp/src/types.ts:267](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L267) ## Properties @@ -10,7 +10,7 @@ Defined in: [packages/events-amqp/src/types.ts:266](https://github.com/Connectum > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\> -Defined in: [packages/events-amqp/src/types.ts:274](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L274) +Defined in: [packages/events-amqp/src/types.ts:275](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L275) *** @@ -18,7 +18,7 @@ Defined in: [packages/events-amqp/src/types.ts:274](https://github.com/Connectum > `readonly` `optional` **exchange?**: `string` -Defined in: [packages/events-amqp/src/types.ts:270](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L270) +Defined in: [packages/events-amqp/src/types.ts:271](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L271) Destination exchange name (exchange-to-exchange binding). @@ -28,7 +28,7 @@ Destination exchange name (exchange-to-exchange binding). > `readonly` `optional` **queue?**: `string` -Defined in: [packages/events-amqp/src/types.ts:268](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L268) +Defined in: [packages/events-amqp/src/types.ts:269](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L269) Destination queue name (queue binding) — mutually exclusive with `exchange`. @@ -38,7 +38,7 @@ Destination queue name (queue binding) — mutually exclusive with `exchange`. > `readonly` **routingKey**: `string` -Defined in: [packages/events-amqp/src/types.ts:273](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L273) +Defined in: [packages/events-amqp/src/types.ts:274](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L274) *** @@ -46,6 +46,6 @@ Defined in: [packages/events-amqp/src/types.ts:273](https://github.com/Connectum > `readonly` **source**: `string` -Defined in: [packages/events-amqp/src/types.ts:272](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L272) +Defined in: [packages/events-amqp/src/types.ts:273](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L273) Source exchange. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md index cd54c23..f4c7b55 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpConsumerOptions -Defined in: [packages/events-amqp/src/types.ts:478](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L478) +Defined in: [packages/events-amqp/src/types.ts:518](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L518) Consumer options. @@ -12,7 +12,7 @@ Consumer options. > `readonly` `optional` **exclusive?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:492](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L492) +Defined in: [packages/events-amqp/src/types.ts:532](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L532) Whether the consumer is exclusive to this connection. @@ -28,7 +28,7 @@ false > `readonly` `optional` **prefetch?**: `number` -Defined in: [packages/events-amqp/src/types.ts:485](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L485) +Defined in: [packages/events-amqp/src/types.ts:525](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L525) Prefetch count (QoS) — how many unacknowledged messages a consumer can have at a time. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md index 3e42c26..acdedab 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md @@ -2,7 +2,7 @@ # Interface: AmqpExchangeDeclaration -Defined in: [packages/events-amqp/src/types.ts:248](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L248) +Defined in: [packages/events-amqp/src/types.ts:249](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L249) ## Properties @@ -10,7 +10,7 @@ Defined in: [packages/events-amqp/src/types.ts:248](https://github.com/Connectum > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\> -Defined in: [packages/events-amqp/src/types.ts:254](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L254) +Defined in: [packages/events-amqp/src/types.ts:255](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L255) Raw AMQP arguments passthrough. @@ -20,7 +20,7 @@ Raw AMQP arguments passthrough. > `readonly` `optional` **autoDelete?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:252](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L252) +Defined in: [packages/events-amqp/src/types.ts:253](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L253) *** @@ -28,7 +28,7 @@ Defined in: [packages/events-amqp/src/types.ts:252](https://github.com/Connectum > `readonly` `optional` **durable?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:251](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L251) +Defined in: [packages/events-amqp/src/types.ts:252](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L252) *** @@ -36,7 +36,7 @@ Defined in: [packages/events-amqp/src/types.ts:251](https://github.com/Connectum > `readonly` **name**: `string` -Defined in: [packages/events-amqp/src/types.ts:249](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L249) +Defined in: [packages/events-amqp/src/types.ts:250](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L250) *** @@ -44,4 +44,4 @@ Defined in: [packages/events-amqp/src/types.ts:249](https://github.com/Connectum > `readonly` **type**: `"headers"` \| `"topic"` \| `"direct"` \| `"fanout"` -Defined in: [packages/events-amqp/src/types.ts:250](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L250) +Defined in: [packages/events-amqp/src/types.ts:251](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L251) diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeOptions.md index 833422f..188cbb9 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpExchangeOptions -Defined in: [packages/events-amqp/src/types.ts:427](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L427) +Defined in: [packages/events-amqp/src/types.ts:467](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L467) Exchange assertion options. @@ -12,7 +12,7 @@ Exchange assertion options. > `readonly` `optional` **autoDelete?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:440](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L440) +Defined in: [packages/events-amqp/src/types.ts:480](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L480) Whether the exchange is deleted when the last queue unbinds. @@ -28,7 +28,7 @@ false > `readonly` `optional` **durable?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:433](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L433) +Defined in: [packages/events-amqp/src/types.ts:473](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L473) Whether the exchange should survive broker restarts. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpLifecycleCallbacks.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpLifecycleCallbacks.md index 89f0302..0348edd 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpLifecycleCallbacks.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpLifecycleCallbacks.md @@ -2,7 +2,7 @@ # Interface: AmqpLifecycleCallbacks -Defined in: [packages/events-amqp/src/types.ts:371](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L371) +Defined in: [packages/events-amqp/src/types.ts:410](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L410) Connection lifecycle callbacks. @@ -16,7 +16,7 @@ deprecated since 1.3.0 (removal not before 2.0). > `readonly` `optional` **onConnected?**: () => `void` -Defined in: [packages/events-amqp/src/types.ts:391](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L391) +Defined in: [packages/events-amqp/src/types.ts:430](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L430) #### Returns @@ -32,7 +32,7 @@ Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "connected"`). Kept unti > `readonly` `optional` **onDisconnected?**: (`cause`) => `void` -Defined in: [packages/events-amqp/src/types.ts:393](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L393) +Defined in: [packages/events-amqp/src/types.ts:432](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L432) #### Parameters @@ -54,7 +54,7 @@ Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "disconnected"`). Kept u > `readonly` `optional` **onLifecycle?**: (`event`) => `void` -Defined in: [packages/events-amqp/src/types.ts:389](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L389) +Defined in: [packages/events-amqp/src/types.ts:428](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L428) Single discriminated-union lifecycle callback — the preferred surface. Receives every [AmqpLifecycleEvent](../type-aliases/AmqpLifecycleEvent.md), including `blocked`/`unblocked`, @@ -88,7 +88,7 @@ deterministic misconfiguration at boot. > `readonly` `optional` **onReconnectFailed?**: (`cause`) => `void` -Defined in: [packages/events-amqp/src/types.ts:406](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L406) +Defined in: [packages/events-amqp/src/types.ts:445](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L445) #### Parameters @@ -110,7 +110,7 @@ Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "reconnect-failed"`). Ke > `readonly` `optional` **onReconnecting?**: (`info`) => `void` -Defined in: [packages/events-amqp/src/types.ts:404](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L404) +Defined in: [packages/events-amqp/src/types.ts:443](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L443) A reconnect attempt has been scheduled. Fires exactly ONCE per scheduled retry (amqplib's `reconnect-scheduled`). A failed attempt that also emits @@ -149,11 +149,12 @@ Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "reconnecting"`). Kept u > `readonly` `optional` **onSetupFailed?**: (`error`, `ctx`) => `void` -Defined in: [packages/events-amqp/src/types.ts:421](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L421) +Defined in: [packages/events-amqp/src/types.ts:461](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L461) A setup/topology failure occurred while (re)applying the declarative -topology — on the initial connect's validation probe (`ctx.initial: true`, -`ctx.attempt: 0`) and/or on a reconnect whose topology re-assert fails +topology — during the startup window (`ctx.initial: true`; `ctx.attempt` +is 0 on the probe, or the 0-based attempt index in the bounded initial +phase) and/or on a reconnect whose topology re-assert fails (`ctx.initial: false`, `ctx.attempt` ≥ 1). This surfaces deterministic configuration drift (e.g. a missing queue in diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpPublisherOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpPublisherOptions.md index 35e465d..f799b18 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpPublisherOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpPublisherOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpPublisherOptions -Defined in: [packages/events-amqp/src/types.ts:498](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L498) +Defined in: [packages/events-amqp/src/types.ts:538](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L538) Publisher options. @@ -12,7 +12,7 @@ Publisher options. > `readonly` `optional` **correlationHeader?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:527](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L527) +Defined in: [packages/events-amqp/src/types.ts:567](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L567) How `basic.return` frames are correlated to publishes when `mandatory: true`. The return frame carries no deliveryTag, so: @@ -36,7 +36,7 @@ true > `readonly` `optional` **externalContract?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:556](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L556) +Defined in: [packages/events-amqp/src/types.ts:596](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L596) Publish against an EXTERNAL (non-EventBus) message contract: suppress the EventBus envelope so the wire frame carries ONLY contract-specified @@ -74,7 +74,7 @@ false > `readonly` `optional` **mandatory?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:512](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L512) +Defined in: [packages/events-amqp/src/types.ts:552](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L552) Whether the message should be returned if it cannot be routed. Unroutable messages reject the publish with `AmqpUnroutableError`. @@ -91,7 +91,7 @@ false > `readonly` `optional` **persistent?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:504](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L504) +Defined in: [packages/events-amqp/src/types.ts:544](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L544) Whether messages should be persisted to disk (deliveryMode=2). diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueDeclaration.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueDeclaration.md index 038b389..71cb19b 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueDeclaration.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueDeclaration.md @@ -2,7 +2,7 @@ # Interface: AmqpQueueDeclaration -Defined in: [packages/events-amqp/src/types.ts:257](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L257) +Defined in: [packages/events-amqp/src/types.ts:258](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L258) ## Properties @@ -10,7 +10,7 @@ Defined in: [packages/events-amqp/src/types.ts:257](https://github.com/Connectum > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\> -Defined in: [packages/events-amqp/src/types.ts:263](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L263) +Defined in: [packages/events-amqp/src/types.ts:264](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L264) Raw AMQP arguments passthrough (e.g. x-dead-letter-exchange). @@ -20,7 +20,7 @@ Raw AMQP arguments passthrough (e.g. x-dead-letter-exchange). > `readonly` `optional` **autoDelete?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:260](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L260) +Defined in: [packages/events-amqp/src/types.ts:261](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L261) *** @@ -28,7 +28,7 @@ Defined in: [packages/events-amqp/src/types.ts:260](https://github.com/Connectum > `readonly` `optional` **durable?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:259](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L259) +Defined in: [packages/events-amqp/src/types.ts:260](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L260) *** @@ -36,7 +36,7 @@ Defined in: [packages/events-amqp/src/types.ts:259](https://github.com/Connectum > `readonly` `optional` **exclusive?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:261](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L261) +Defined in: [packages/events-amqp/src/types.ts:262](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L262) *** @@ -44,4 +44,4 @@ Defined in: [packages/events-amqp/src/types.ts:261](https://github.com/Connectum > `readonly` **name**: `string` -Defined in: [packages/events-amqp/src/types.ts:258](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L258) +Defined in: [packages/events-amqp/src/types.ts:259](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L259) diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOptions.md index 181fd2a..9dd398a 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpQueueOptions -Defined in: [packages/events-amqp/src/types.ts:446](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L446) +Defined in: [packages/events-amqp/src/types.ts:486](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L486) Queue assertion options. @@ -12,7 +12,7 @@ Queue assertion options. > `readonly` `optional` **deadLetterExchange?**: `string` -Defined in: [packages/events-amqp/src/types.ts:467](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L467) +Defined in: [packages/events-amqp/src/types.ts:507](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L507) Dead letter exchange name for rejected messages. @@ -22,7 +22,7 @@ Dead letter exchange name for rejected messages. > `readonly` `optional` **deadLetterRoutingKey?**: `string` -Defined in: [packages/events-amqp/src/types.ts:472](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L472) +Defined in: [packages/events-amqp/src/types.ts:512](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L512) Dead letter routing key for rejected messages. @@ -32,7 +32,7 @@ Dead letter routing key for rejected messages. > `readonly` `optional` **durable?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:452](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L452) +Defined in: [packages/events-amqp/src/types.ts:492](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L492) Whether the queue should survive broker restarts. @@ -48,7 +48,7 @@ true > `readonly` `optional` **maxLength?**: `number` -Defined in: [packages/events-amqp/src/types.ts:462](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L462) +Defined in: [packages/events-amqp/src/types.ts:502](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L502) Maximum number of messages in the queue. @@ -58,6 +58,6 @@ Maximum number of messages in the queue. > `readonly` `optional` **messageTtl?**: `number` -Defined in: [packages/events-amqp/src/types.ts:457](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L457) +Defined in: [packages/events-amqp/src/types.ts:497](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L497) Per-message TTL in milliseconds. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOverride.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOverride.md index 3e1b143..c162989 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOverride.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpQueueOverride.md @@ -2,7 +2,7 @@ # Interface: AmqpQueueOverride -Defined in: [packages/events-amqp/src/types.ts:278](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L278) +Defined in: [packages/events-amqp/src/types.ts:279](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L279) External queue override for a consumer group. @@ -12,7 +12,7 @@ External queue override for a consumer group. > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\> -Defined in: [packages/events-amqp/src/types.ts:282](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L282) +Defined in: [packages/events-amqp/src/types.ts:283](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L283) Raw AMQP arguments used when asserting the queue (assert mode only). @@ -22,7 +22,7 @@ Raw AMQP arguments used when asserting the queue (assert mode only). > `readonly` `optional` **durable?**: `boolean` -Defined in: [packages/events-amqp/src/types.ts:284](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L284) +Defined in: [packages/events-amqp/src/types.ts:285](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L285) #### Default @@ -36,6 +36,6 @@ true > `readonly` **queue**: `string` -Defined in: [packages/events-amqp/src/types.ts:280](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L280) +Defined in: [packages/events-amqp/src/types.ts:281](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L281) Externally-defined queue name to consume from. diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpRecoveryOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpRecoveryOptions.md index 1f2a94e..1498347 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpRecoveryOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpRecoveryOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpRecoveryOptions -Defined in: [packages/events-amqp/src/types.ts:311](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L311) +Defined in: [packages/events-amqp/src/types.ts:312](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L312) Recovery knobs (passed through to amqplib's opt-in recovery). @@ -20,12 +20,12 @@ Full jitter with a hard cap is expressible today: set `jitter: 1` and halve `initialDelay`/`maxDelay` — the delay becomes uniform in `[0, intended cap]` (verified against amqplib 2.0.1's internal formula; re-verify on upgrades). -Bounding the initial connect independently from steady-state recovery, and a -pluggable backoff hook, are tracked as future options — see -[https://github.com/Connectum-Framework/connectum/issues/198](https://github.com/Connectum-Framework/connectum/issues/198) and +The initial connect CAN be bounded independently since 1.3.0 — see +[AmqpRecoveryOptions.initialConnectMaxRetries](#initialconnectmaxretries) (#198; upstream native +support tracked in [https://github.com/amqp-node/amqplib/issues/856](https://github.com/amqp-node/amqplib/issues/856)). +A pluggable backoff hook remains tracked in [https://github.com/Connectum-Framework/connectum/issues/199](https://github.com/Connectum-Framework/connectum/issues/199) -(upstream: [https://github.com/amqp-node/amqplib/issues/856](https://github.com/amqp-node/amqplib/issues/856) and -[https://github.com/amqp-node/amqplib/issues/855](https://github.com/amqp-node/amqplib/issues/855)). +(upstream: [https://github.com/amqp-node/amqplib/issues/855](https://github.com/amqp-node/amqplib/issues/855)). ## Properties @@ -33,7 +33,7 @@ pluggable backoff hook, are tracked as future options — see > `readonly` `optional` **factor?**: `number` -Defined in: [packages/events-amqp/src/types.ts:317](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L317) +Defined in: [packages/events-amqp/src/types.ts:318](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L318) #### Default @@ -43,11 +43,48 @@ Defined in: [packages/events-amqp/src/types.ts:317](https://github.com/Connectum *** +### initialConnectMaxRetries? + +> `readonly` `optional` **initialConnectMaxRetries?**: `number` + +Defined in: [packages/events-amqp/src/types.ts:354](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L354) + +Bound the retry budget of the INITIAL connect independently of +steady-state recovery: N retries = N+1 attempts, mirroring `maxRetries` +semantics. A single `maxRetries` cannot express "bounded startup, +unbounded steady-state" — its counter resets on every success. + +When set to an explicit finite value (a negative value clamps to `0` — +single attempt — mirroring amqplib's `maxRetries` normalization), the +adapter owns the initial window with a bounded validate-connect loop +(the startup probe folds into it — validation IS each attempt, no extra +connects): every +attempt surfaces per-attempt lifecycle events (`reconnecting` with the +next delay, `setup-failed { initial: true, attempt }` for topology +failures), and budget exhaustion rejects `connect()` with a typed +`AmqpConnectionError` after a terminal `reconnect-failed` — never a +silent block. Backoff matches amqplib's steady-state formula exactly +(same knobs above, same cap-before-jitter semantics). + +`failFastOnInitialSetupError` still short-circuits a deterministic +topology error on the first sight, budget notwithstanding. + +Handoff caveat: after a successful validation the real recovering +connect runs — a broker dying inside that small window blocks per +amqplib's own initial loop. + +Unset (default): behavior unchanged — amqplib's initial loop with the +shared `maxRetries` governs startup, and initial-window per-retry events +are not surfaced. Since 1.3.0; upstream native support tracked in +[https://github.com/amqp-node/amqplib/issues/856](https://github.com/amqp-node/amqplib/issues/856). + +*** + ### initialDelay? > `readonly` `optional` **initialDelay?**: `number` -Defined in: [packages/events-amqp/src/types.ts:313](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L313) +Defined in: [packages/events-amqp/src/types.ts:314](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L314) #### Default @@ -61,7 +98,7 @@ Defined in: [packages/events-amqp/src/types.ts:313](https://github.com/Connectum > `readonly` `optional` **jitter?**: `number` -Defined in: [packages/events-amqp/src/types.ts:319](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L319) +Defined in: [packages/events-amqp/src/types.ts:320](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L320) Symmetric jitter factor (0..1): the delay is uniform in `[base × (1 − jitter), base × (1 + jitter)]`. @@ -77,7 +114,7 @@ Symmetric jitter factor (0..1): the delay is uniform in `[base × (1 − jitter) > `readonly` `optional` **maxDelay?**: `number` -Defined in: [packages/events-amqp/src/types.ts:315](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L315) +Defined in: [packages/events-amqp/src/types.ts:316](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L316) Base delay cap in ms; jitter is applied on top of the capped base, so the effective wait can exceed it. @@ -93,9 +130,9 @@ Base delay cap in ms; jitter is applied on top of the capped base, so the effect > `readonly` `optional` **maxRetries?**: `number` -Defined in: [packages/events-amqp/src/types.ts:321](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L321) +Defined in: [packages/events-amqp/src/types.ts:322](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L322) -Attempts per series (initial connect and each recovery series); resets on success. +Attempts per series (initial connect and each recovery series); resets on success. To bound ONLY startup, use [initialConnectMaxRetries](#initialconnectmaxretries). #### Default diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpSerializationOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpSerializationOptions.md index 0e06619..18c47a6 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpSerializationOptions.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpSerializationOptions.md @@ -2,7 +2,7 @@ # Interface: AmqpSerializationOptions -Defined in: [packages/events-amqp/src/types.ts:219](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L219) +Defined in: [packages/events-amqp/src/types.ts:220](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L220) Serialization metadata and optional wire transcoding. @@ -12,7 +12,7 @@ Serialization metadata and optional wire transcoding. > `readonly` `optional` **contentType?**: `string` -Defined in: [packages/events-amqp/src/types.ts:225](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L225) +Defined in: [packages/events-amqp/src/types.ts:226](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L226) AMQP `contentType` message property. @@ -28,7 +28,7 @@ AMQP `contentType` message property. > `readonly` `optional` **decode?**: (`content`) => `Uint8Array` -Defined in: [packages/events-amqp/src/types.ts:238](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L238) +Defined in: [packages/events-amqp/src/types.ts:239](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L239) Transform the incoming wire body before it reaches the event handler. Failures nack the message (requeue per consumer policy). @@ -49,7 +49,7 @@ Failures nack the message (requeue per consumer policy). > `readonly` `optional` **encode?**: (`payload`) => `Uint8Array` -Defined in: [packages/events-amqp/src/types.ts:232](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L232) +Defined in: [packages/events-amqp/src/types.ts:233](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L233) Transform the outgoing wire body. Receives the payload bytes the EventBus (or the application) produced. Failures reject the publish diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpTopology.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpTopology.md index e9f4705..6b79a1c 100644 --- a/en/api/@connectum/events-amqp/types/interfaces/AmqpTopology.md +++ b/en/api/@connectum/events-amqp/types/interfaces/AmqpTopology.md @@ -2,7 +2,7 @@ # Interface: AmqpTopology -Defined in: [packages/events-amqp/src/types.ts:242](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L242) +Defined in: [packages/events-amqp/src/types.ts:243](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L243) Declarative topology. @@ -12,7 +12,7 @@ Declarative topology. > `readonly` `optional` **bindings?**: readonly [`AmqpBindingDeclaration`](AmqpBindingDeclaration.md)[] -Defined in: [packages/events-amqp/src/types.ts:245](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L245) +Defined in: [packages/events-amqp/src/types.ts:246](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L246) *** @@ -20,7 +20,7 @@ Defined in: [packages/events-amqp/src/types.ts:245](https://github.com/Connectum > `readonly` `optional` **exchanges?**: readonly [`AmqpExchangeDeclaration`](AmqpExchangeDeclaration.md)[] -Defined in: [packages/events-amqp/src/types.ts:243](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L243) +Defined in: [packages/events-amqp/src/types.ts:244](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L244) *** @@ -28,4 +28,4 @@ Defined in: [packages/events-amqp/src/types.ts:243](https://github.com/Connectum > `readonly` `optional` **queues?**: readonly [`AmqpQueueDeclaration`](AmqpQueueDeclaration.md)[] -Defined in: [packages/events-amqp/src/types.ts:244](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L244) +Defined in: [packages/events-amqp/src/types.ts:245](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L245) diff --git a/en/api/@connectum/events-amqp/types/type-aliases/AmqpLifecycleEvent.md b/en/api/@connectum/events-amqp/types/type-aliases/AmqpLifecycleEvent.md index 6ff13a6..786c56b 100644 --- a/en/api/@connectum/events-amqp/types/type-aliases/AmqpLifecycleEvent.md +++ b/en/api/@connectum/events-amqp/types/type-aliases/AmqpLifecycleEvent.md @@ -4,7 +4,7 @@ > **AmqpLifecycleEvent** = \{ `reconnected`: `boolean`; `type`: `"connected"`; \} \| \{ `error`: `Error`; `type`: `"disconnected"`; \} \| \{ `attempt`: `number`; `delay`: `number`; `error`: `Error`; `type`: `"reconnecting"`; \} \| \{ `error`: `Error`; `type`: `"reconnect-failed"`; \} \| \{ `attempt`: `number`; `error`: `Error`; `initial`: `boolean`; `type`: `"setup-failed"`; \} \| \{ `reason`: `string`; `type`: `"blocked"`; \} \| \{ `type`: `"unblocked"`; \} -Defined in: [packages/events-amqp/src/types.ts:355](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L355) +Defined in: [packages/events-amqp/src/types.ts:394](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L394) Discriminated connection lifecycle event, delivered to [AmqpLifecycleCallbacks.onLifecycle](../interfaces/AmqpLifecycleCallbacks.md#onlifecycle). @@ -14,24 +14,30 @@ Exactly-once guarantees (pinned by integration tests): for the initial connect and `true` after a recovery. - `disconnected` fires once per connection loss (a socket-level cut no longer double-fires via the raw `error` event — fixed in 1.3.0). -- `reconnecting` fires once per scheduled retry AFTER the connection has been - established once. `reconnect-failed` is terminal and fires for either of - its two triggers: the retry budget is exhausted (`maxRetries`), or the - fatal topology policy stopped the cycle (`treatTopologyErrorAsFatal`). -- `setup-failed` reports a topology/setup failure on the initial validation - probe (`initial: true`, `attempt: 0`) or a reconnect re-assert - (`initial: false`, `attempt` >= 1). +- `reconnecting` fires once per scheduled retry — after the connection has + been established once, and also per attempt of the bounded initial phase + when [AmqpRecoveryOptions.initialConnectMaxRetries](../interfaces/AmqpRecoveryOptions.md#initialconnectmaxretries) is set. + `reconnect-failed` is terminal and fires for any of its three triggers: + the retry budget is exhausted (`maxRetries`), the fatal topology policy + stopped the cycle (`treatTopologyErrorAsFatal`), or the initial connect + budget ran out (`initialConnectMaxRetries`). +- `setup-failed` reports a topology/setup failure with `initial: true` for + the startup window (`attempt: 0` on the probe; the 0-based attempt index + in the bounded initial phase) or `initial: false` for a reconnect + re-assert (`attempt` >= 1). - `blocked`/`unblocked` surface broker flow control (RabbitMQ `connection.blocked`, e.g. under a memory/disk alarm); they have no flat callback equivalent. -Scope: the retry loop of the INITIAL connect (broker unreachable when -`connect()` is called) happens before the lifecycle wiring can attach, so -its per-retry events are not surfaced; the startup probe covers the -deterministic-misconfiguration case (`setup-failed { initial: true }`). -Full initial-window observability lands with the adapter-owned bounded -initial phase — see -[https://github.com/Connectum-Framework/connectum/issues/198](https://github.com/Connectum-Framework/connectum/issues/198). +Scope: with amqplib's own initial loop (default), the retry loop of the +INITIAL connect (broker unreachable when `connect()` is called) happens +before the lifecycle wiring can attach, so its per-retry events are not +surfaced; the startup probe covers the deterministic-misconfiguration case +(`setup-failed { initial: true }`). Set +[AmqpRecoveryOptions.initialConnectMaxRetries](../interfaces/AmqpRecoveryOptions.md#initialconnectmaxretries) (since 1.3.0) to make +the adapter own that window — its bounded phase surfaces per-attempt +`reconnecting`/`setup-failed` events and a terminal `reconnect-failed` on +budget exhaustion. The `type` values are deliberately broker-agnostic so a future cross-adapter generalization stays non-breaking. diff --git a/en/api/@connectum/events-amqp/types/type-aliases/AmqpTopologyMode.md b/en/api/@connectum/events-amqp/types/type-aliases/AmqpTopologyMode.md index 53a6aff..695384f 100644 --- a/en/api/@connectum/events-amqp/types/type-aliases/AmqpTopologyMode.md +++ b/en/api/@connectum/events-amqp/types/type-aliases/AmqpTopologyMode.md @@ -4,6 +4,6 @@ > **AmqpTopologyMode** = *typeof* [`AmqpTopologyMode`](../variables/AmqpTopologyMode.md)\[keyof *typeof* [`AmqpTopologyMode`](../variables/AmqpTopologyMode.md)\] -Defined in: [packages/events-amqp/src/types.ts:210](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L210) +Defined in: [packages/events-amqp/src/types.ts:211](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L211) Topology establishment mode. diff --git a/en/api/@connectum/events-amqp/types/variables/AmqpTopologyMode.md b/en/api/@connectum/events-amqp/types/variables/AmqpTopologyMode.md index 7b6c8f8..2188bc9 100644 --- a/en/api/@connectum/events-amqp/types/variables/AmqpTopologyMode.md +++ b/en/api/@connectum/events-amqp/types/variables/AmqpTopologyMode.md @@ -4,7 +4,7 @@ > `const` **AmqpTopologyMode**: `object` -Defined in: [packages/events-amqp/src/types.ts:210](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L210) +Defined in: [packages/events-amqp/src/types.ts:211](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L211) Topology establishment mode. diff --git a/en/packages/events-amqp.md b/en/packages/events-amqp.md index 449cb1c..7a6fa45 100644 --- a/en/packages/events-amqp.md +++ b/en/packages/events-amqp.md @@ -187,7 +187,8 @@ const adapter = AmqpAdapter({ | `maxDelay` | `number` | `30000` | Base delay cap in ms. Jitter is applied on top of the capped base, so the effective wait can exceed this (~20% at the default jitter, up to ~2x at `jitter: 1`) | | `factor` | `number` | `2` | Exponential backoff factor | | `jitter` | `number` | `0.2` | Symmetric jitter factor (0..1): the delay is drawn uniformly from `[base × (1 − jitter), base × (1 + jitter)]` | -| `maxRetries` | `number` | `Infinity` | Attempts per series before giving up. Governs **both** the initial connect and each later recovery series; the counter resets on every success | +| `maxRetries` | `number` | `Infinity` | Attempts per series before giving up. Governs **both** the initial connect and each later recovery series; the counter resets on every success. To bound only startup, use `initialConnectMaxRetries` | +| `initialConnectMaxRetries` | `number` | unset | Bound the **initial** connect independently (N retries = N+1 attempts): the adapter runs a bounded validate-connect loop with per-attempt lifecycle events (`reconnecting`, `setup-failed {initial: true}`) and rejects `connect()` with a typed `AmqpConnectionError` on exhaustion (after a terminal `reconnect-failed`) — instead of blocking forever. Backoff matches amqplib's formula exactly. Available since 1.3.0 | ### `AmqpLifecycleCallbacks` @@ -217,7 +218,7 @@ lifecycle: { Deprecated flat callbacks (compatibility shim): `onConnected()`, `onDisconnected(cause)`, `onReconnecting({ attempt, delay, error })`, `onReconnectFailed(cause)`, `onSetupFailed(error, { initial, attempt })` (since 1.2.0). -**Scope**: the retry loop of the **initial** connect (broker unreachable when `connect()` is called) runs before the lifecycle wiring can attach, so its per-retry events are not surfaced; the startup probe covers the deterministic-misconfiguration case. Full initial-window observability is tracked in [connectum#198](https://github.com/Connectum-Framework/connectum/issues/198). +**Scope**: with amqplib's own initial loop (default), the retry loop of the **initial** connect (broker unreachable when `connect()` is called) runs before the lifecycle wiring can attach, so its per-retry events are not surfaced; the startup probe covers the deterministic-misconfiguration case. Set `recovery.initialConnectMaxRetries` (since 1.3.0) to make the adapter own that window — its bounded phase surfaces per-attempt `reconnecting`/`setup-failed` events and a terminal `reconnect-failed` on budget exhaustion. ::: tip Fixed in 1.3.0 A socket-level connection cut used to fire `onDisconnected` twice; it now fires exactly once per drop on both surfaces (disconnect-counter metrics roughly halve). In `recovery: false` mode a server-forced graceful close now surfaces a single `disconnected` (previously no event). @@ -432,7 +433,7 @@ Connection behavior: - **With recovery enabled**, `connect()` retries with backoff until the broker becomes reachable -- convenient for `docker-compose` startup ordering where the broker may not be up yet. Under the default `maxRetries: Infinity`, `connect()` blocks rather than failing fast; set `failFastOnInitialSetupError: true` to reject `connect()` with a typed `AmqpTopologyError` on a **permanent** setup/topology error at startup while still recovering from transient broker outages. - **`maxRetries` scope.** The retry budget governs **both** the initial connect and every later recovery series, with the counter reset on each success. A finite value chosen only to bound startup therefore also caps steady-state recovery: a transient blip of that many consecutive failures in any single series permanently stops recovery. - **Reconnect delay.** The effective delay is symmetric jitter around the exponential base -- uniform in `[base × (1 − jitter), base × (1 + jitter)]` with `base = min(maxDelay, initialDelay × factor^(attempt − 1))`. The cap applies to the base **before** jitter, so the wait can overshoot `maxDelay` (~20% at the default `jitter: 0.2`, up to ~2x at `jitter: 1`). -- **Topology drift during recovery.** Under the default policy, a queue/exchange deleted or incompatibly redeclared while the adapter reconnects makes every recovery attempt fail deterministically -- the cycle retries forever, reporting `setup-failed` per attempt (and heals if the topology is restored). Set `treatTopologyErrorAsFatal: true` to stop the cycle on the first such failure instead: the adapter reports `setup-failed` then the terminal `reconnect-failed`, tears down fully (consumers are dead; a later `connect()` starts from a clean slate), and subsequent publishes fail fast with `AmqpConnectionError`. The gate is the AMQP reply code of the cause (`404`/`406` = deterministic; transient causes -- including the cluster classic-queue "home node ... down or inaccessible" 404 -- stay in recovery). Boot-time drift is `failFastOnInitialSetupError`'s job; the broker-unreachable-at-boot window is covered by neither flag until [connectum#198](https://github.com/Connectum-Framework/connectum/issues/198). +- **Topology drift during recovery.** Under the default policy, a queue/exchange deleted or incompatibly redeclared while the adapter reconnects makes every recovery attempt fail deterministically -- the cycle retries forever, reporting `setup-failed` per attempt (and heals if the topology is restored). Set `treatTopologyErrorAsFatal: true` to stop the cycle on the first such failure instead: the adapter reports `setup-failed` then the terminal `reconnect-failed`, tears down fully (consumers are dead; a later `connect()` starts from a clean slate), and subsequent publishes fail fast with `AmqpConnectionError`. The gate is the AMQP reply code of the cause (`404`/`406` = deterministic; transient causes -- including the cluster classic-queue "home node ... down or inaccessible" 404 -- stay in recovery). Boot-time drift is `failFastOnInitialSetupError`'s job; the broker-unreachable-at-boot window is closed by `recovery.initialConnectMaxRetries` (since 1.3.0). - **With `recovery: false`**, `connect()` rejects immediately if the broker is unreachable, and a lost connection is not restored. Observe connection state through `lifecycle.onLifecycle` (discriminated union; preferred since 1.3.0) or the deprecated flat callbacks (`onConnected`, `onDisconnected`, `onReconnecting`, `onReconnectFailed`, `onSetupFailed`).