@onlineapps/conn-orch-cookbook

Complete cookbook toolkit for ALL services - unified wrapper including core, executor, transformer, and router functionality

🚀 Version 2.0 - Major Update

The conn-orch-cookbook package (v2.0) is now a complete toolkit that combines all cookbook functionality in one unified package. This ensures architectural consistency across ALL services including infrastructure components like workflow_launcher.

What's New in v2.0

• Modular architecture - Four specialized modules combined
• Backward compatibility - All v1.x APIs still work
• Unified approach - Same package for ALL services (infrastructure and business)
• Complete toolkit - Parsing, execution, transformation, and routing

Why Unified Approach?

Per architectural decision, ALL services including workflow_launcher use this single package to ensure:

• Consistency - Same API everywhere
• Predictability - No special cases
• Maintainability - Single source of truth
• Simplicity - One package to learn

📦 Installation

npm install @onlineapps/conn-orch-cookbook
# or
yarn add @onlineapps/conn-orch-cookbook

🔧 Quick Start

Backward Compatible (v1.x style)

const {
  parseCookbookFromFile,
  validateCookbook
} = require('@onlineapps/conn-orch-cookbook');

// Works exactly as before
const cookbook = await parseCookbookFromFile('./workflow.json');
validateCookbook(cookbook);

New Modular Approach (v2.0)

const cookbook = require('@onlineapps/conn-orch-cookbook');

// Use specific modules
const { CookbookExecutor } = cookbook.executor;
const { CookbookRouter } = cookbook.router;
const { CookbookGenerator } = cookbook.transformer;

// Or use factory functions
const processor = cookbook.createProcessor({
  cookbook: myCookbook,
  maxRetries: 3
});

📚 Included Modules

1. Core Module (@onlineapps/cookbook-core)

• JSON Schema validation
• Recursive step validation
• Parsing from file/object
• Lightweight (~50KB)

2. Executor Module (@onlineapps/cookbook-executor)

• Workflow execution engine
• Context management
• Variable resolution ($api_input, $steps)
• Step processing for all types

3. Transformer Module (@onlineapps/cookbook-transformer)

• OpenAPI to cookbook generation
• API spec analysis
• Response mapping
• JSONPath transformations

4. Router Module (@onlineapps/cookbook-router)

• Service discovery
• Queue management
• Retry with exponential backoff
• Dead letter queue handling

🎯 Usage Examples

Complete Service Implementation

const cookbook = require('@onlineapps/conn-orch-cookbook');
const MQClient = require('@onlineapps/conn-infra-mq');
const RegistryClient = require('@onlineapps/conn-orch-registry');

class MyService {
  constructor() {
    // Initialize clients
    this.mqClient = new MQClient(mqConfig);
    this.registryClient = new RegistryClient(registryConfig);

    // Create router for message handling
    this.router = cookbook.createRouter(
      this.mqClient,
      this.registryClient
    );
  }

  async processWorkflow(message) {
    // Parse and validate
    const workflowDef = cookbook.parseCookbookFromObject(message.cookbook);

    // Create executor
    const executor = new cookbook.CookbookExecutor(workflowDef);

    // Execute workflow
    const result = await executor.execute(message.context);

    // Route to next service
    await this.router.routeToNextService(
      workflowDef,
      result,
      message.current_step
    );
  }
}

Infrastructure Service (workflow_launcher)

// workflow_launcher uses the SAME package
const cookbook = require('@onlineapps/conn-orch-cookbook');

class WorkflowLauncher {
  async handleWorkflowInit(message) {
    // Validate cookbook
    cookbook.validateCookbook(message.cookbook);

    // Route to first service
    await this.router.routeWorkflow(
      message.cookbook,
      message.context
    );
  }
}

OpenAPI Integration

const { CookbookGenerator } = require('@onlineapps/conn-orch-cookbook');

const generator = new CookbookGenerator({
  defaultTimeout: 10000,
  defaultRetry: { maxAttempts: 3, delayMs: 2000 }
});

// Generate cookbook from OpenAPI spec
const openApiSpec = require('./api-spec.json');
const cookbook = generator.generate(openApiSpec);

📖 Cookbook Structure

Basic Example (v2.0 Schema)

{
  "version": "2.1.0",
  "api_input": {
    "customer": "ACME Corp",
    "amount": 1000
  },
  "steps": [
    {
      "step_id": "invoice_step",
      "type": "task",
      "service": "invoice-service",
      "operation": "createInvoice",
      "input": {
        "customer": "${api_input.customer}",
        "amount": "${api_input.amount}"
      },
      "output": {
        "invoice_id": "${response.invoice_id}"
      },
      "retry": {
        "max_attempts": 3,
        "delay_ms": 2000
      }
    }
  ]
}

📚 Step Types

All 7 step types are fully supported:

• task - Service operation execution
• foreach - Iteration over arrays
• fork_join - Parallel execution
• switch - Conditional branching
• steps - Nested workflows (replaces sub_workflow)
• wait - Time delays
• dispatch - Webhook dispatching

📤 Delivery Block (v2.1)

Cookbook nově může definovat top-level sekci delivery, která popisuje způsob doručení výsledku klientovi:

"delivery": {
  "handler": "dispatcher",
  "allow_skip": false,
  "destinations": [
    {
      "type": "webhook",
      "url": "https://client.example.com/api/callback",
      "method": "POST",
      "retry": {
        "max_attempts": 5,
        "delay_ms": 3000
      }
    },
    {
      "type": "public_url",
      "path": "result/${context.workflow_id}/invoice.pdf",
      "ttl_seconds": 86400,
      "access": "signed"
    }
  ],
  "output": {
    "workflow_id": "${context.workflow_id}",
    "invoice_id": "${steps.invoice_step.output.invoice_id}"
  }
}

• handler: dispatcher (výchozí), service_step, nebo none.
• destinations: konkrétní výstupy (webhook, websocket, public_url).
• output: mapování hodnot, které se mají doručit.

Detailní specifikace viz Schema Final Specification nebo API Delivery Dispatcher.

🔄 Migration from v1.x

Version 2.0 maintains full backward compatibility. Existing code continues to work without changes:

// This still works exactly as before
const { parseCookbookFromFile } = require('@onlineapps/conn-orch-cookbook');
const cookbook = await parseCookbookFromFile('./workflow.json');

To access new features, use the modular exports:

// New modular approach
const { executor, router, transformer } = require('@onlineapps/conn-orch-cookbook');

📋 API Reference

Legacy Exports (v1.x compatible)

• parseCookbookFromFile(path) - Parse from file
• parseCookbookFromObject(obj) - Parse from object
• validateCookbook(cookbook) - Validate structure
• CookbookValidationError - Error class

New Modular Exports (v2.0)

• core - Core parsing and validation
• executor - Workflow execution
• transformer - OpenAPI transformation
• router - Message routing
• createProcessor(options) - Factory for complete processor
• createRouter(mqClient, registryClient, options) - Factory for router

🧪 Testing

npm test              # Run all tests
npm run test:unit     # Unit tests only
npm run test:integration  # Integration tests

⚠️ Important Notes

Schema v2.0 Update

The cookbook schema has been updated to version 2.0 with improved semantics and consistency:

Major Changes:

• All naming conventions now use snake_case (not camelCase)
• Field id renamed to step_id for clarity
• Field operation is now required only for task steps (maps to OpenAPI operationId)
• Removed explicit queue field (now implicit from service name)
• Added comprehensive error handling and compensation support

Example v2.0 step:

{
  step_id: 'process_items',
  type: 'foreach',
  iterator: '${api_input.items}',
  steps: [
    // nested steps
  ],
  output: {
    processed_items: '${foreach.results}'
  }
}

See Schema v2.0 Specification for full details.

📄 License

PROPRIETARY - All rights reserved

🤝 Contributing

Internal package - contributions via internal GitLab only.

For detailed documentation on individual modules, see their respective README files in the shared/ directory.