REST API adapter dispatch router in Edge Function
epic-external-system-integration-configuration-backend-infrastructure-task-003 — Implement the core dispatch routing logic inside the Edge Function that receives export job requests, identifies the target integration type (Xledger, Dynamics, Cornerstone, Consio, Bufdir), loads the corresponding adapter from the REST API Adapter Registry, and executes the export. The router must validate the request payload, resolve field mappings via the Field Mapping Resolver, and return a structured result object.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
Structure the router as a single handler function: serve(async (req) => { ... }) using Supabase's serve helper. Use a plain object as the AdapterRegistry (a Map
Each adapter (XledgerAdapter, DynamicsAdapter, etc.) implements this interface and is responsible for its own HTTP calls to the external system. The FieldMappingResolver should query the field_mappings table in Supabase using the service role client and apply transformations — memoize the mapping lookup per integrationId within the invocation using a local Map. Wrap the entire handler body in a try/catch to guarantee that unhandled errors always return a valid JSON response rather than a Deno runtime error page. Use AbortSignal.timeout(30_000) for all external adapter HTTP calls to enforce the per-adapter timeout.
Testing Requirements
Write Deno unit tests covering: (1) valid request routes to the correct adapter and returns 200 with result; (2) missing required field returns 400; (3) unknown integrationTypeId returns 422; (4) CredentialNotFoundError from adapter returns 503; (5) generic adapter error returns 502 with sanitised message; (6) field mapping resolver is called with the correct integrationId and payload before the adapter; (7) adapter receives the resolved (transformed) payload, not the raw one. Mock AdapterRegistry, FieldMappingResolver, and CredentialProvider — do not make real external API calls in unit tests. Additionally write one integration test (integration_test/) that deploys the function to a local Supabase instance and sends a real POST request with a stub adapter registered for 'test-type'.
Supabase Edge Functions have cold start latency that can cause the first sync invocation after idle periods to fail or timeout when the external API has a short connection window, leading to missed scheduled syncs that go undetected.
Mitigation & Contingency
Mitigation: Configure Edge Function memory and implement a warm-up ping mechanism before heavy sync invocations. Set generous timeout values on the external API calls. Log all cold-start incidents for monitoring.
Contingency: If cold starts cause consistent sync failures, migrate the sync scheduler to a persistent Supabase cron job that pre-warms the function 30 seconds before the scheduled sync time.
The sync scheduler must execute jobs at predictable times for financial reporting accuracy. Drift in cron execution timing (due to Supabase infrastructure delays) could cause syncs to run at wrong times, leading to missing data in accounting exports or duplicate exports across reporting periods.
Mitigation & Contingency
Mitigation: Implement idempotency keys based on integration ID + scheduled period, so re-runs of a delayed sync cannot create duplicate exports. Log actual execution timestamps vs scheduled timestamps and alert on drift exceeding 5 minutes.
Contingency: If scheduler reliability is insufficient, integrate with a dedicated cron service (e.g., pg_cron on Supabase) for millisecond-precise scheduling, replacing the application-level scheduler.
Aggressive health monitoring ping frequency could trigger rate limiting on external APIs (especially Xledger and Dynamics), causing legitimate export calls to fail after the monitor exhausts the API's request quota.
Mitigation & Contingency
Mitigation: Use lightweight health check endpoints (HEAD requests or vendor-specific ping/status endpoints) rather than data requests. Set health check frequency to once per 15 minutes minimum. Implement exponential backoff after consecutive failures.
Contingency: If rate limiting occurs, disable active health monitoring for the affected integration type and switch to passive health detection (mark unhealthy only when a scheduled sync fails).