From 354314dfe093fcd20aec493eaa546a71d9ce97a3 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 19 May 2026 11:45:41 -0400 Subject: [PATCH] docs(requirements): cached calls return TrackedOperationId in ESG --- .../Component-ExternalSystemGateway.md | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/requirements/Component-ExternalSystemGateway.md b/docs/requirements/Component-ExternalSystemGateway.md index f64af27..9678f55 100644 --- a/docs/requirements/Component-ExternalSystemGateway.md +++ b/docs/requirements/Component-ExternalSystemGateway.md @@ -59,10 +59,10 @@ Each database connection definition includes: - Failures are immediate — no buffering. ### Cached Write (Store-and-Forward) -- Script calls `Database.CachedWrite("name", "sql", parameters)`. -- The write is submitted to the Store-and-Forward Engine. +- Script calls `Database.CachedWrite("name", "sql", parameters)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the write result. - Payload includes: connection name, SQL statement, serialized parameter values. -- If the database is unavailable, the write is buffered and retried per the connection's retry settings. +- The write is attempted immediately. On immediate success it is recorded as a terminal `Delivered` tracking record. On **transient failure** (database unavailable) it is buffered (`Pending`/`Retrying`) and retried per the connection's retry settings by the Store-and-Forward Engine. +- Cached-write status is observable to scripts via `Tracking.Status(id)` (answered site-locally) and centrally via the Site Call Audit component. ## Invocation Protocol @@ -84,10 +84,11 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da - Use for request/response interactions where the script needs the result (e.g., fetching a recipe, querying inventory). ### Cached (Store-and-Forward) -- Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`. -- The call is attempted immediately. If it succeeds, the response is discarded (fire-and-forget). -- On **transient failure** (connection refused, timeout, HTTP 5xx), the call is routed to the Store-and-Forward Engine for retry per the system's retry settings. The script does **not** block — the call is buffered and the script continues. -- On **permanent failure** (HTTP 4xx), the error is returned **synchronously** to the calling script. No retry — the request itself is wrong. +- Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the response body. +- The call is attempted immediately. If it succeeds, the response is discarded and the call is recorded as a terminal `Delivered` tracking record. +- On **transient failure** (connection refused, timeout, HTTP 5xx), the call is routed to the Store-and-Forward Engine for retry per the system's retry settings. The script does **not** block — the call is buffered (`Pending`/`Retrying`) and the script continues. +- On **permanent failure** (HTTP 4xx), the error is returned **synchronously** to the calling script. No retry — the request itself is wrong. The call is also recorded as a terminal `Failed` tracking record capturing the error. +- Cached-call status is observable to scripts via `Tracking.Status(id)` (answered site-locally and authoritatively) and centrally via the Site Call Audit component. - Use for outbound data pushes where deferred delivery is acceptable (e.g., posting production data, sending quality reports). ## Call Timeout & Error Handling @@ -95,7 +96,7 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da - Each external system definition specifies a **timeout** that applies to all method calls on that system. - Error classification by HTTP response: - **Transient failures** (connection refused, timeout, HTTP 408, 429, 5xx): Behavior depends on call mode — `CachedCall` buffers for retry; `Call` returns error to script. - - **Permanent failures** (HTTP 4xx except 408/429): Always returned to the calling script regardless of call mode. Logged to Site Event Logging. + - **Permanent failures** (HTTP 4xx except 408/429): Always returned to the calling script regardless of call mode. Logged to Site Event Logging. For `CachedCall`, the failure is additionally recorded as a terminal `Failed` tracking record — so even a never-buffered cached call has an authoritative status record. - This classification ensures the S&F buffer is not polluted with requests that will never succeed. - **Idempotency note**: `CachedCall` retries may result in duplicate delivery if the external system received the original request but the response was lost. Callers should use `CachedCall` only for operations that are idempotent or where duplicate delivery is acceptable. @@ -114,7 +115,8 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da - **Configuration Database (MS SQL)**: Stores external system and database connection definitions (central only). - **Local SQLite**: At sites, external system and database connection definitions are read from local SQLite (populated by artifact deployment). Sites do not access the central config DB. -- **Store-and-Forward Engine**: Handles buffering for failed external system calls and cached database writes. +- **Store-and-Forward Engine**: Handles buffering for failed external system calls and cached database writes, and owns the site-local operation tracking table read by `Tracking.Status(id)`. +- **Site Call Audit**: Central audit mirror for cached calls — receives cached-call lifecycle telemetry so `CachedCall`/`CachedWrite` status is observable centrally. - **Communication Layer**: Routes inbound external system requests from central to sites. - **Security & Auth**: Design role manages definitions. - **Configuration Database (via IAuditService)**: Definition changes are audit logged. @@ -122,5 +124,6 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da ## Interactions - **Site Runtime (Script/Alarm Execution Actors)**: Scripts invoke external system methods and database operations through this component. -- **Store-and-Forward Engine**: Failed calls and cached writes are routed here for reliable delivery. +- **Store-and-Forward Engine**: Failed calls and cached writes are routed here for reliable delivery; it also assigns each cached call a `TrackedOperationId` tracking row. +- **Site Call Audit**: The central observability sibling for cached calls — cached-call status reported here is queried via the Central UI Site Calls page. - **Deployment Manager**: Receives updated definitions as part of system-wide artifact deployment (triggered explicitly by Deployment role).