RecoveryOrchestrator

Pipeline-level error recovery orchestrator that coordinates recovery across providers with exponential backoff.

Defined in: src/core/RecoveryOrchestrator.ts:144

Pipeline-level error recovery orchestrator that coordinates recovery across providers with exponential backoff.

Remarks

The RecoveryOrchestrator is a standalone utility that does not know about provider internals. Instead, callers pass a recovery function that encapsulates the provider-specific reconnection or retry logic. The orchestrator handles:

Attempt tracking: Counts recovery attempts per provider and gives up after maxAttempts.
Exponential backoff: Delays between attempts grow exponentially, capped at maxDelay.
Concurrency guard: Prevents multiple simultaneous recovery attempts for the same provider.
Non-recoverable filtering: Errors with recoverable: false are rejected immediately without attempting recovery.
Event notification: Emits RecoveryEvent objects at each stage of the recovery process.

Example

const recovery = new RecoveryOrchestrator();

// In a catch block for STT connection errors:
const recovered = await recovery.attemptRecovery(
  'DeepgramSTT',
  error,
  async () => { await sttProvider.connect(); },
);

if (recovered) {
  console.log('STT reconnected successfully');
} else {
  console.error('STT recovery failed');
}

// After successful operation, reset the counter:
recovery.resetProvider('DeepgramSTT');

Constructors

Constructor

new RecoveryOrchestrator(
   strategy?, 
   logger?, 
   onRecoveryEvent?): RecoveryOrchestrator;

Defined in: src/core/RecoveryOrchestrator.ts:156

Creates a new RecoveryOrchestrator.

Parameters

Parameter	Type	Default value	Description
`strategy`	`RecoveryStrategy`	`DEFAULT_RECOVERY_STRATEGY`	Recovery strategy configuration. Defaults to DEFAULT_RECOVERY_STRATEGY if not provided.
`logger?`	`Logger`	`undefined`	Optional logger for diagnostic output.
`onRecoveryEvent?`	(`event`) => `void`	`undefined`	Optional callback invoked at each stage of recovery.

Returns

RecoveryOrchestrator

Methods

attemptRecovery()

attemptRecovery(
   providerName, 
   error, 
recoverFn): Promise<boolean>;

Defined in: src/core/RecoveryOrchestrator.ts:186

Attempt to recover a failed provider.

Parameters

Parameter	Type	Description
`providerName`	`string`	Identifier for the provider being recovered.
`error`	`CompositeVoiceError`	The error that triggered recovery. Must be a CompositeVoiceError with a `recoverable` flag.
`recoverFn`	() => `Promise`<`void`>	Async function that performs the actual recovery (e.g., reconnecting a WebSocket, retrying an API call).

Returns

Promise<boolean>

true if recovery succeeded, false if it failed or was skipped.

Remarks

The recovery process follows these steps:

Check if the error is recoverable. If not, emit a non-recovering event and return false.
Check if recovery is already in progress for this provider. If so, return false to prevent concurrent recovery.
Increment the attempt counter. If it exceeds maxAttempts, emit a failure event and return false.
Wait for the calculated backoff delay.
Execute the provided recovery function.
On success, reset the attempt counter and return true.
On failure, log the error and return false.

isRecovering()

isRecovering(providerName): boolean;

Defined in: src/core/RecoveryOrchestrator.ts:293

Check if a provider is currently in recovery.

Parameters

Parameter	Type	Description
`providerName`	`string`	The provider to check.

Returns

boolean

true if recovery is currently in progress for this provider.

reset()

reset(): void;

Defined in: src/core/RecoveryOrchestrator.ts:282

Reset all recovery state for all providers.

Returns

void

Remarks

Useful when tearing down or reinitializing the pipeline.

resetProvider()

resetProvider(providerName): void;

Defined in: src/core/RecoveryOrchestrator.ts:271

Reset recovery state for a provider.

Parameters

Parameter	Type	Description
`providerName`	`string`	The provider whose recovery state should be reset.

Returns

void

Remarks

Call this after a successful operation to clear the attempt counter and allow fresh recovery attempts if a future error occurs.