@bernierllc/validators-retry-topology

Retry topology validation - loops, backoff, dead-letter policy, and circuit breaker validation for reliable systems.

Installation

npm install @bernierllc/validators-retry-topology

Overview

This package provides validators for retry configurations to ensure reliable and fault-tolerant systems. It validates:

• Infinite retry loop detection - Ensures retry configurations have finite limits
• Backoff strategy validation - Validates exponential backoff and delay configurations
• Max retry limits - Ensures reasonable retry counts
• Dead letter queue requirements - Enforces DLQ for high retry scenarios
• Circuit breaker validation - Validates fault tolerance configurations
• Timeout validation - Ensures reasonable timeout configurations

Part of the BernierLLC validators ecosystem following MECE architecture principles.

Quick Start

import { validateRetryTopology } from '@bernierllc/validators-retry-topology';

const config = {
  maxRetries: 3,
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffFactor: 2,
  jitter: true
};

const problems = await validateRetryTopology(config);

if (problems.length > 0) {
  console.error('Validation errors:', problems);
}

API Reference

validateRetryTopology(config, options?)

Validates a retry topology configuration and returns an array of problems found.

Parameters:

• config: RetryTopologyConfig - The retry configuration to validate
• options?: RetryTopologyValidationOptions - Optional validation options

Returns: Promise<Problem[]> - Array of validation problems

Configuration Types

RetryTopologyConfig

interface RetryTopologyConfig {
  maxRetries?: number;
  initialDelayMs?: number;
  maxDelayMs?: number;
  backoffFactor?: number;
  jitter?: boolean;
  backoff?: BackoffConfig;
  deadLetterQueue?: DeadLetterQueueConfig;
  circuitBreaker?: CircuitBreakerConfig;
  timeoutMs?: number;
  totalTimeoutMs?: number;
}

DeadLetterQueueConfig

interface DeadLetterQueueConfig {
  enabled: boolean;
  maxSize?: number;
  handler?: string;
  ttl?: number;
}

CircuitBreakerConfig

interface CircuitBreakerConfig {
  enabled: boolean;
  failureThreshold: number;
  failureWindowMs: number;
  recoveryTimeoutMs: number;
  successThreshold?: number;
}

RetryTopologyValidationOptions

interface RetryTopologyValidationOptions {
  maxAllowedRetries?: number; // Default: 10
  minInitialDelayMs?: number; // Default: 100
  maxTotalTimeoutMs?: number; // Default: 300000 (5 minutes)
  requireDeadLetterQueue?: boolean; // Default: true
  deadLetterQueueThreshold?: number; // Default: 5
  requireCircuitBreaker?: boolean; // Default: true
}

Validation Rules

no-infinite-retries

Ensures retry configurations have a finite maximum retry count.

// Invalid - no maxRetries
const config = { initialDelayMs: 1000 };

// Invalid - infinite retries
const config = { maxRetries: Infinity };

// Valid
const config = { maxRetries: 3 };

valid-backoff

Validates backoff strategy configuration with reasonable delays.

// Invalid - maxDelayMs < initialDelayMs
const config = {
  initialDelayMs: 1000,
  maxDelayMs: 500
};

// Valid
const config = {
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffFactor: 2
};

reasonable-max-retries

Ensures maxRetries is set to a reasonable value.

// Warning - too many retries
const config = { maxRetries: 15 };

// Valid
const config = { maxRetries: 5 };

require-dead-letter-queue

Enforces dead letter queue configuration for high retry counts.

// Warning - high retries without DLQ
const config = { maxRetries: 8 };

// Valid - high retries with DLQ
const config = {
  maxRetries: 8,
  deadLetterQueue: {
    enabled: true,
    handler: 'handleDeadLetter'
  }
};

valid-circuit-breaker

Validates circuit breaker configuration.

// Invalid - zero threshold
const config = {
  circuitBreaker: {
    enabled: true,
    failureThreshold: 0,
    failureWindowMs: 60000,
    recoveryTimeoutMs: 30000
  }
};

// Valid
const config = {
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    failureWindowMs: 60000,
    recoveryTimeoutMs: 30000
  }
};

reasonable-total-timeout

Ensures total timeout across all retries is reasonable.

// Warning - timeout too high
const config = {
  totalTimeoutMs: 400000 // > 5 minutes
};

// Valid
const config = {
  timeoutMs: 5000,
  totalTimeoutMs: 60000
};

Usage Examples

API Request Retry Configuration

import { validateRetryTopology } from '@bernierllc/validators-retry-topology';

const apiRetryConfig = {
  maxRetries: 3,
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffFactor: 2,
  jitter: true,
  timeoutMs: 5000,
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    failureWindowMs: 60000,
    recoveryTimeoutMs: 30000,
    successThreshold: 2
  }
};

const problems = await validateRetryTopology(apiRetryConfig);
console.log('Validation results:', problems);

Message Queue Retry Configuration

const queueRetryConfig = {
  maxRetries: 5,
  initialDelayMs: 500,
  maxDelayMs: 60000,
  backoffFactor: 2,
  deadLetterQueue: {
    enabled: true,
    handler: 'processDeadLetterMessage',
    maxSize: 10000,
    ttl: 604800 // 7 days
  }
};

const problems = await validateRetryTopology(queueRetryConfig);

Database Connection Retry Configuration

const dbRetryConfig = {
  maxRetries: 10,
  initialDelayMs: 2000,
  maxDelayMs: 120000,
  backoffFactor: 1.5,
  jitter: true,
  timeoutMs: 10000,
  totalTimeoutMs: 300000,
  circuitBreaker: {
    enabled: true,
    failureThreshold: 3,
    failureWindowMs: 30000,
    recoveryTimeoutMs: 60000
  },
  deadLetterQueue: {
    enabled: true,
    handler: 'notifyDatabaseFailure'
  }
};

const problems = await validateRetryTopology(dbRetryConfig);

Custom Validation Options

const config = {
  maxRetries: 4,
  initialDelayMs: 1000
};

const problems = await validateRetryTopology(config, {
  maxAllowedRetries: 3,
  deadLetterQueueThreshold: 3,
  requireDeadLetterQueue: true
});

Using Individual Rules

import {
  noInfiniteRetries,
  validBackoffStrategy,
  requireDeadLetterQueue
} from '@bernierllc/validators-retry-topology';
import { createRuleContext } from '@bernierllc/validators-core';

const config = { maxRetries: 3 };
const context = createRuleContext('test', {}, defaultUtils);

const validator = noInfiniteRetries.create(context);
validator(config);

Using the Primitive Validator

import { retryTopologyValidator } from '@bernierllc/validators-retry-topology';
import { createRuleContext } from '@bernierllc/validators-core';

const config = {
  maxRetries: 3,
  initialDelayMs: 1000
};

const context = createRuleContext('retry-topology', {}, defaultUtils);
const problems = await retryTopologyValidator.validate(config, context);

Integration with Other Packages

With @bernierllc/retry-policy

import { validateRetryTopology } from '@bernierllc/validators-retry-topology';
import { RetryPolicy } from '@bernierllc/retry-policy';

const config = {
  maxRetries: 3,
  initialDelayMs: 1000,
  backoffFactor: 2
};

// Validate before creating policy
const problems = await validateRetryTopology(config);
if (problems.length === 0) {
  const policy = new RetryPolicy(config);
  // Use policy...
}

In CI/CD Pipelines

import { validateRetryTopology } from '@bernierllc/validators-retry-topology';
import * as fs from 'fs';

const config = JSON.parse(fs.readFileSync('retry-config.json', 'utf-8'));
const problems = await validateRetryTopology(config);

if (problems.some(p => p.severity === 'error')) {
  console.error('Retry configuration validation failed');
  process.exit(1);
}

Best Practices

1. Always set maxRetries - Prevent infinite retry loops
2. Use exponential backoff - Set backoffFactor >= 2 for effective backoff
3. Add jitter - Reduce thundering herd problems
4. Configure DLQ for high retries - maxRetries >= 5 should have DLQ
5. Use circuit breakers - Protect downstream services
6. Set reasonable timeouts - Prevent resource exhaustion
7. Validate in CI - Catch configuration issues early

Integration Status

Logger Integration

Status: Not applicable

This package provides pure validation functions with no side effects. @bernierllc/logger integration is not applicable as validators don't perform logging - they return structured Problem objects that consumers can log as needed.

Docs-Suite Integration

Status: Ready

Complete TypeDoc documentation available. All types and functions are fully documented with examples.

NeverHub Integration

Status: Not applicable

As a primitive validator following MECE principles, this package has no runtime dependencies or service discovery needs. @bernierllc/neverhub-adapter integration is not applicable - validators are pure functions that operate on configuration objects.

Dependencies

• @bernierllc/validators-core - Core validation framework
• @bernierllc/retry-policy - Retry configuration types

Quality Standards

• 90%+ test coverage with real retry configurations
• Zero linting errors
• Strict TypeScript mode enabled
• Comprehensive edge case handling

Security

This package performs validation only and does not execute any retry logic. It has no external network dependencies and processes only configuration objects. No sensitive data is stored or transmitted.

Security Considerations:

• Pure validation functions with no side effects
• No external API calls or network requests
• No file system access
• No execution of user-provided code
• Type-safe TypeScript implementation
• Regular dependency audits with npm audit

For security issues, please contact: [email protected]

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

See Also

• @bernierllc/validators-core - Core validation framework
• @bernierllc/retry-policy - Retry policy implementation
• @bernierllc/validators-workflow-sla - Workflow SLA validation