Refine External System Gateway: protocol, auth, timeouts, error classification

Specify HTTP/REST with JSON as the invocation protocol. Add API key and Basic Auth
as outbound authentication modes. Add per-system call timeouts. Classify errors by
HTTP status for store-and-forward decisions (5xx/transient → retry, 4xx → permanent
error to script). Document ADO.NET connection pooling for database connections.
Update Store-and-Forward to clarify transient-only buffering.

Component-ExternalSystemGateway.md

@@ -31,10 +31,16 @@ Site clusters (executes calls directly to external systems). Central cluster (st
 
 Each external system definition includes:
 - **Name**: Unique identifier (e.g., "MES", "RecipeManager").
-- **Connection Details**: Endpoint URL, authentication, protocol.
-- **Retry Settings**: Max retry count, fixed time between retries (used by Store-and-Forward Engine).
+- **Base URL**: The root endpoint URL for the external system (e.g., `https://mes.example.com/api`).
+- **Authentication**: One of:
+  - **API Key**: Header name (e.g., `X-API-Key`) and key value.
+  - **Basic Auth**: Username and password.
+- **Timeout**: Per-system timeout for all method calls (e.g., 30 seconds). Applies to the HTTP request round-trip.
+- **Retry Settings**: Max retry count, fixed time between retries (used by Store-and-Forward Engine for transient failures only).
 - **Method Definitions**: List of available API methods, each with:
   - Method name.
+  - **HTTP method**: GET, POST, PUT, or DELETE.
+  - **Path**: Relative path appended to the base URL (e.g., `/recipes/{id}`).
   - Parameter definitions (name, type).
   - Return type definition.
 
@@ -58,6 +64,29 @@ Each database connection definition includes:
 - 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.
 
+## Invocation Protocol
+
+All external system calls are **HTTP/REST** with **JSON** serialization:
+
+- The ESG acts as an HTTP client. The external system definition provides the base URL; each method definition specifies the HTTP method and relative path.
+- Request parameters are serialized as JSON in the request body (POST/PUT) or as query parameters (GET/DELETE).
+- Response bodies are deserialized from JSON into the method's defined return type.
+- Credentials (API key header or Basic Auth header) are attached to every request per the system's authentication configuration.
+
+## Call Timeout & Error Handling
+
+- Each external system definition specifies a **timeout** that applies to all method calls on that system.
+- Error classification determines whether the Store-and-Forward Engine retries the call:
+  - **Transient failures** (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 waiting for eventual delivery — the call is buffered and the script continues.
+  - **Permanent failures** (HTTP 4xx): No retry. The error is returned **synchronously** to the calling script for handling (log, notify, try different parameters, etc.). The failure is logged to Site Event Logging.
+- This classification ensures the S&F buffer is not polluted with requests that will never succeed.
+
+## Database Connection Management
+
+- Database connections use **standard ADO.NET connection pooling** per named connection. No custom pool management.
+- Pool behavior (max pool size, connection lifetime, etc.) can be tuned via connection string parameters in the database connection definition if needed.
+- Synchronous failures on `Database.Connection()` (e.g., unreachable server) return an error to the calling script, consistent with external system permanent failure handling.
+
 ## Dependencies
 
 - **Configuration Database (MS SQL)**: Stores external system and database connection definitions.