Issue Planner / Multi-region webhook delivery
built with carrot-ui Abstracted sample · fictional data. AI-generated · you review Steering · you control
Version 1 · generated 10:04 PM · on commit a1b2c3d
1Ingest issue→ 2Research repo→ 3Design choices→ 4Phased plan→ 5Handoff

Issue details

Title
Multi-region webhook delivery
Description
Today the delivery service runs a single worker bound to one region. Enterprise tenants need delivery to originate from several regions at once for data-residency and latency. We need to declare multiple region configs in one place, keep single-region setups working untouched, and route per tenant.
Repository
acme-platform / services
Assignee
@platform
Generated on
a1b2c3d

Summary AI

  • Introduce a dedicated REGIONS_CONFIG environment variable — a YAML array of region configurations, each with its own endpoint, credentials, and rate limits.
  • Maintain full backward compatibility by falling back to the existing single-region variables (REGION_HOST, REGION_KEY) when REGIONS_CONFIG is not set.
  • Refactor DeliveryManager to supervise multiple region workers with proper lifecycle coordination.
  • Decouple WebhookClient from the global TENANT_ID by passing tenant identity through constructor injection.

Design choices AI · reasoned

Configuration storage for multiple regions
A dedicated config block with a region-specific schema, rather than overloading tenant config.
▸Reasoning
The current bootstrap reads a flat set of region variables at startup, unlike the per-tenant config loaded from the control plane. A dedicated config with a region-scoped schema (endpoint, credentials, rate limits) gives cleaner validation and a clear separation of concerns, and avoids coupling region topology to tenant settings.
▸Options considered
  1. Extend the existing TENANT_CONFIG with region entries inline, alongside provider keys.
  2. Create a dedicated REGIONS_CONFIG env var — a new YAML block specific to multi-region configuration, with a tailored schema.
Worker lifecycle ownership
Who supervises per-region workers and how failures isolate.
▸Options considered
  1. One worker per process, scaled horizontally by deployment.
  2. A single DeliveryManager supervising N region workers, so failures isolate per region without extra deploys.

Coding plan AI · phased

▸Phase 1Multi-region configuration layerHigh
Define the region configuration schema
  • A YAML array where each entry has: id, host, region, key, webhook_url, and optional poll_interval_ms, max_retries_per_poll, request_timeout_ms.
  • The id field doubles as the label for logs and metrics attribution.
Create the region config parser
  • Add services/src/utils/regions-config.ts, following the pattern in tenant-config.ts.
  • Define a strongly-typed RegionConfig interface; parse lazily via a module-level singleton.
  • Validate required fields and throw descriptive errors for invalid entries.
Implement backward-compatible config resolution
  • getRegionConfigs() returns parsed REGIONS_CONFIG; else builds a single-entry array from legacy vars; else returns empty.
▸Agent prompt
Implement the multi-region configuration layer for the delivery service. Goal: introduce a REGIONS_CONFIG YAML env var and a backward-compatible resolution function.

Task 1 — Schema (interface + docs)
• YAML array; each entry: id, host, region, key, webhook_url, plus optional poll_interval_ms, max_retries_per_poll, request_timeout_ms.

Task 2 — Create services/src/utils/regions-config.ts
• Strongly-typed RegionConfig interface; getRegionConfigs() reads REGIONS_CONFIG (YAML) into RegionConfig[]; fall back to legacy vars; validate required fields.
▸Phase 2Multi-worker delivery infrastructureHigh
Extend DeliveryManager with region identity
  • Thread a regionId through construction so each worker is addressable.
Refactor for multiple workers + update bootstrap
  • Supervise one worker per region config; iterate getRegionConfigs() at startup.
▸Phase 3Client per-region contextMedium
Decouple WebhookClient from global TENANT_ID
  • Open assumption: confirm no other caller relies on the global read. Resolve to raise confidence.
  • Pass regionId into the client constructor in webhook-delivery-service.ts; include region id in logs.

Research AI · repo-aware

The webhook integration lives mainly in services/src/delivery/. Configuration is centralized in services/src/utils/env.ts with region-prefixed variables. Delivery is handled by DeliveryManager (lifecycle) and WebhookPoller (the interval loop). WebhookClient reads tenant identity directly from the environment. A multi-instance pattern exists in tenant-config.ts — but the per-region worker lifecycle warrants a dedicated configuration model.

3 phases selected