dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add dual call modes for external systems: synchronous Call() and cached CachedCall()

Browse Source 
Scripts now choose per invocation whether an external system call is synchronous
(all failures return to script) or cached (transient failures go to store-and-forward).
Mirrors the existing Database.Connection/CachedWrite pattern. Updated ESG, Site
Runtime script API, high-level requirements, and design doc.
This commit is contained in:
Joseph Doherty
2026-03-16 08:00:20 -04:00
parent 5fff1712a8
commit 1ef316f32c
4 changed files with 35 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/plans/2026-03-16-external-system-gateway-refinement-design.md
View File

@@ -24,13 +24,15 @@ The External System Gateway doc lacked specification for the invocation protocol
- **Per-system timeout** — one timeout value applies to all methods on a given external system.
- Defined in the external system definition.
### Error Classification
- **Transient failures** (connection errors, timeouts, HTTP 5xx): Routed to Store-and-Forward for retry. Script does not block.
- **Permanent failures** (HTTP 4xx): No retry. Error returned synchronously to the calling script. Logged to Site Event Logging.
- S&F buffer only accepts transient failures to avoid accumulating unrecoverable requests.
### Dual Call Modes
- **`ExternalSystem.Call()`**: Synchronous request/response. All failures (transient and permanent) return to the script. No S&F buffering. Use when the script needs the result.
- **`ExternalSystem.CachedCall()`**: Fire-and-forget with S&F on transient failure. Use for outbound data pushes where deferred delivery is acceptable.
- Mirrors the existing `Database.Connection()` / `Database.CachedWrite()` pattern.
### Permanent Failure Behavior
- Synchronous error back to script, consistent with DCL write failure handling.
### Error Classification
- **Transient failures** (connection errors, timeouts, HTTP 5xx): `CachedCall` buffers for retry; `Call` returns error to script.
- **Permanent failures** (HTTP 4xx): Always returned to the calling script regardless of call mode. Logged to Site Event Logging.
- S&F buffer only accepts transient failures to avoid accumulating unrecoverable requests.
### Database Connection Pooling
- Standard ADO.NET connection pooling per named connection. No custom pool logic.
@@ -43,8 +45,10 @@ The External System Gateway doc lacked specification for the invocation protocol
| Document | Change |
|----------|--------|
| `Component-ExternalSystemGateway.md` | Updated External System Definition fields (base URL, auth modes, timeout, HTTP method/path per method). Added 3 new sections: Invocation Protocol, Call Timeout & Error Handling, Database Connection Management. |
| `Component-ExternalSystemGateway.md` | Updated External System Definition fields. Added sections: External System Call Modes (dual-mode API), Invocation Protocol, Call Timeout & Error Handling, Database Connection Management. |
| `Component-StoreAndForward.md` | Clarified that only transient failures are buffered; 4xx errors are not queued. |
| `Component-SiteRuntime.md` | Updated Script Runtime API with `ExternalSystem.Call()` and `ExternalSystem.CachedCall()`. |
| `HighLevelReqs.md` | Updated script capabilities (Section 4.4) to reflect dual call modes. |
## Alternatives Considered
@@ -54,3 +58,4 @@ The External System Gateway doc lacked specification for the invocation protocol
- **All failures retryable**: Rejected — retrying 4xx errors pollutes the S&F buffer with requests that will never succeed.
- **Custom connection pooling**: Rejected — ADO.NET pooling is battle-tested and handles this scenario natively.
- **XML serialization option**: Rejected — JSON-only is consistent with REST-only; XML systems can use a wrapper.
- **Per-method sync/cached flag**: Rejected — the same method may need synchronous calls in one script and cached in another. Script author chooses per invocation.