@onlineapps/cookbook-router

Message routing for cookbook workflows - handles service discovery and queue routing.

Overview

This package provides routing capabilities for cookbook workflows in a distributed microservices environment. It handles service discovery, queue management, and retry logic for reliable message delivery.

Installation

npm install @onlineapps/cookbook-router

Features

• Service discovery - Integration with service registry
• Queue management - RabbitMQ operations and DLQ handling
• Workflow routing - Route between services based on cookbook steps
• Retry logic - Exponential backoff with jitter
• Health checking - Service availability monitoring

Usage

Basic routing setup

const { CookbookRouter } = require('@onlineapps/cookbook-router');
const MQClient = require('@onlineapps/connector-mq-client');
const RegistryClient = require('@onlineapps/connector-registry-client');

const mqClient = new MQClient(mqConfig);
const registryClient = new RegistryClient(registryConfig);

const router = new CookbookRouter(mqClient, registryClient, {
  defaultQueue: 'workflow.init',
  completedQueue: 'workflow.completed',
  maxRetries: 3
});

Route workflow to first service

const cookbook = {
  id: 'my-workflow',
  steps: [
    { id: 'step1', type: 'task', service: 'user-service', operation: 'getUser' },
    { id: 'step2', type: 'task', service: 'email-service', operation: 'sendEmail' }
  ]
};

const context = {
  workflow_id: 'wf_123',
  api_input: { userId: '456' }
};

await router.routeWorkflow(cookbook, context);

Route to next service

// After completing step1, route to next service
await router.routeToNextService(cookbook, updatedContext, 'step1');

Handle failures

try {
  await router.routeWorkflow(cookbook, context);
} catch (error) {
  // Route to dead letter queue
  await router.routeToDLQ(cookbook, context, error, 'user-service');
}

Service Discovery

const { ServiceDiscovery } = require('@onlineapps/cookbook-router');

const discovery = new ServiceDiscovery(registryClient);

// Check service availability
const exists = await discovery.serviceExists('user-service');

// Get service details
const service = await discovery.getService('user-service');

// Find services by capability
const services = await discovery.findServicesByCapability('email');

Queue Management

const { QueueManager } = require('@onlineapps/cookbook-router');

const queueManager = new QueueManager(mqClient);

// Publish message
await queueManager.publish('user.queue', { action: 'process' });

// Subscribe to queue
await queueManager.subscribe('user.queue', async (message) => {
  console.log('Received:', message);
});

// Setup dead letter queue
await queueManager.setupDLQ('user.queue', 'user.dlq');

Retry Handling

const { RetryHandler } = require('@onlineapps/cookbook-router');

const retryHandler = new RetryHandler({
  maxAttempts: 3,
  initialDelay: 1000,
  backoffFactor: 2
});

// Execute with retry
const result = await retryHandler.execute(async () => {
  return await unreliableOperation();
});

// Wrap function with retry
const reliableOperation = retryHandler.wrap(unreliableOperation);
await reliableOperation();

Configuration Options

CookbookRouter Options

{
  defaultQueue: 'workflow.init',    // Default entry queue
  completedQueue: 'workflow.completed', // Completion queue
  dlqSuffix: '.dlq',               // Dead letter queue suffix
  maxRetries: 3,                   // Max retry attempts
  retryDelay: 2000,                // Base retry delay (ms)
  logger: console                  // Logger instance
}

ServiceDiscovery Options

{
  cacheTTL: 60000,                 // Cache TTL in ms
  logger: console                  // Logger instance
}

QueueManager Options

{
  defaultTTL: 30000,               // Message TTL
  persistent: true,                // Persistent messages
  logger: console                  // Logger instance
}

RetryHandler Options

{
  maxAttempts: 3,                  // Max retry attempts
  initialDelay: 1000,              // Initial delay (ms)
  maxDelay: 30000,                 // Max delay cap (ms)
  backoffFactor: 2,                // Exponential factor
  jitter: true,                    // Add random jitter
  logger: console                  // Logger instance
}

Queue Naming Conventions

• {service}.workflow - Workflow messages
• {service}.queue - Direct messages
• {service}.dlq - Dead letter queue
• workflow.init - Entry point
• workflow.completed - Completed workflows

Error Handling

The router distinguishes between retryable and non-retryable errors:

Retryable:

• Network timeouts
• Connection refused
• Service temporarily unavailable

Non-retryable:

• Validation errors
• Authentication failures
• Not found errors
• Bad requests

Related Packages

• @onlineapps/cookbook-core - Core parsing and validation
• @onlineapps/cookbook-executor - Workflow execution engine
• @onlineapps/cookbook-transformer - OpenAPI mapping
• @onlineapps/connector-cookbook - Full-featured wrapper

License

PROPRIETARY - All rights reserved