Runtime Controller API Reference

Overview

The Runtime Controller is the central HTTP entry point for all API traffic processed by the platform. It acts as a sophisticated gateway, receiving requests from API consumers, applying security and transformation logic, dispatching them to the appropriate backend services, and returning responses.

The controller is responsible for several key functions:

• Request Routing: It parses incoming request URLs to determine the intended direction (e.g., publish, consume, gateway), environment, and serviceKey. It uses this information to look up the correct route configuration via the RuntimeRouteCacheService.
• Protocol and Data Transformation: It orchestrates the conversion between different protocols and data formats. This includes:
  • Publish Flow: Transforming inbound REST/JSON requests into outbound SOAP/XML requests.
  • Consume Flow: Transforming inbound SOAP/XML requests into outbound REST/JSON requests.
  • Gateway Flow: Passing inbound SOAP/XML requests through to a backend SOAP service with byte-level fidelity.
• Security Enforcement: It integrates a multi-layered security model, including:
  • Network ingress controls (GatewayIngressGuard) to ensure requests originate from trusted network paths.
  • IP-based access control (ConsumerIpGrantGuard) to restrict service access to authorized client IPs.
  • Schema and field-level validation to enforce data contracts.
  • Authentication for asynchronous callbacks.
• Asynchronous Processing: It manages long-running operations using a callback pattern, allowing API consumers to initiate a request, receive an immediate acknowledgment, and poll for the result later.
• Backend Management: It handles backend selection based on configured routing strategies (e.g., active_passive, round_robin), performs health checks to filter out unhealthy backends, and manages authentication to those backends.
• Observability: It provides health check endpoints (/health/live, /health/ready) and performs detailed, structured logging for every transaction via the RuntimeLogAsyncWriter.

All API requests are assigned a unique correlationId (either from the X-Correlation-Id header or generated by the controller) to facilitate end-to-end tracing.

Request Processing Flows

The controller handles three primary data flow directions: publish, gateway, and consume.

Publish Flow (REST-to-SOAP)

The publish flow exposes a SOAP backend as a modern RESTful API. The controller receives a JSON request, converts it to a SOAP envelope, calls the backend SOAP service, and transforms the SOAP response back into a JSON response for the client.

How it Works

flowchart TD
    subgraph API Consumer
        A[Client sends REST Request]
    end

    subgraph Runtime Controller
        B[POST /{direction}/{env}/**]
        C{Route Resolution}
        D{Schema & Regex Validation}
        E[JSON to SOAP Conversion]
        F{Async or Sync?}
        G[Send SOAP to Backend]
        H[Receive SOAP Response]
        I[SOAP to JSON Conversion]
        J{Response Validation}
        K[Shape Response (Envelope/Error)]
    end

    subgraph Backend
        L[SOAP Backend Service]
    end

    subgraph Logging
        M[Async Log Writer]
    end

    A --> B
    B --> C
    C -- Found --> D
    C -- Not Found --> K
    D -- Valid --> E
    D -- Invalid --> K
    E --> F
    F -- Sync --> G
    F -- Async --> G
    G --> L
    L --> H
    H --> I
    I --> J
    J -- Valid --> K
    J -- Invalid --> K
    K --> A
    B -- All Paths --> M
    K -- All Paths --> M

1. An API consumer sends a REST request (e.g., POST) to /publish/{environment}/{serviceKey}/{operationKey}.
2. The controller resolves the route using the path, method, and environment. If no route is found, it returns a 404 Not Found error. It includes a defensive check to correct for misconfigured upstream gateways that may send a duplicated /{environment}/{serviceKey} prefix.
3. If the route is found but has no active backend targets, it returns a 503 Service Unavailable error.
4. Validation: The request is validated against several criteria:
   • If configured, an OpenAPI schema is enforced by OpenApiSchemaValidationInterceptor. Invalid requests are rejected with a 400 Bad Request (S2R-VAL-0410).
   • If configured, per-field regex patterns (request_field_validation_regexes) are enforced by FieldRegexValidator. Mismatches are rejected with a 400 Bad Request (S2R-VAL-0411).
5. Request Transformation: The JSON request body is merged with any path and query parameters. It may be transformed based on requestTransformRules.
6. SOAP Conversion: The resulting JSON payload is converted into a SOAP envelope by SoapMessageMapper, honoring the operation's configured soapOperationName, soapNamespace, and soapVersion.
7. Execution Mode:
   • Synchronous: The controller selects a healthy backend target, resolves authentication, and sends the SOAP request.
   • Asynchronous (async_callback): The controller injects WS-Addressing headers into the SOAP request, creates a pending record in the async_execution table, and sends the request. It immediately returns a 202 Accepted response to the consumer with a correlationId and a path for polling the result.
8. Response Handling: Upon receiving the SOAP response, the controller parses it.
   • If the response is a SOAP Fault, the controller maps it to an appropriate HTTP status code (e.g., 400 or 502) and returns a structured error. The level of detail in the error is controlled by the faultDetailExposureMode.
   • If the response is successful, the payload is extracted and converted back to JSON.
9. Response Validation: The final JSON response can be validated against an OpenAPI schema and per-field regex patterns. A validation failure results in a 502 Bad Gateway (S2R-VAL-0430 or S2R-VAL-0431), as the backend has returned a non-compliant response.
10. Final Response: The JSON payload is shaped according to the route's envelopeWrapOverride and errorShapeOverride settings and returned to the API consumer.
11. Logging: Details of the entire transaction are sent to the RuntimeLogAsyncWriter to be persisted.

Gateway Flow (SOAP Passthrough)

The gateway flow acts as a high-fidelity SOAP passthrough broker. It is designed to be a drop-in replacement for a direct backend connection, preserving the SOAP envelope bytes and applying critical security checks.

How it Works

flowchart TD
    subgraph API Consumer
        A[Client sends SOAP Request]
    end

    subgraph Runtime Controller
        B[POST /gateway/{env}/**]
        C[Ingress Guard]
        D{Route Resolution}
        E[Consumer IP Grant Guard]
        F[Read Raw Body Bytes]
        G[Select Backend]
        H[Forward Raw Body]
    end

    subgraph Backend
        I[SOAP Backend Service]
    end

    A --> B
    B --> C
    C -- Deny --> A
    C -- Allow --> D
    D -- Found --> E
    D -- Not Found --> A
    E -- Deny --> A
    E -- Allow --> F
    F --> G
    G --> H
    H --> I
    I --> H
    H --> A

1. An API consumer sends a POST request with a SOAP payload to /gateway/{environment}/{serviceKey}.
2. Ingress Guard: The GatewayIngressGuard immediately evaluates the request's origin. It checks the X-Forwarded-For header against a configured list of trusted proxies. If the request does not come from a trusted path, it is rejected with a 403 Forbidden before its body is read or processed.
3. Route Resolution: The route is resolved based on the address (/gateway/{environment}/{serviceKey}) only. The SOAP payload or SOAPAction header is not used for routing.
4. IP Grant Guard: If a route is found, the ConsumerIpGrantGuard checks if the attributed client IP address is explicitly granted access to this service. If not, the request is rejected with a 403 Forbidden, also before the body is read.
5. Body Read: Only after passing all guards is the raw request body read from the input stream as a byte array. This is capped at 30MB by a platform filter.
6. Backend Dispatch:
   • A healthy backend target is selected.
   • Backend authentication headers are resolved.
   • The GatewaySoapHandler forwards the original request body bytes to the backend. It rebuilds security-sensitive headers like X-Forwarded-For based on the trusted, derived client address, rather than relaying the inbound values.
7. Response: The raw SOAP response from the backend is streamed back to the API consumer, preserving its content and headers.
8. A log entry is created, recording metadata about the transaction. For security, sensitive headers like Authorization are redacted, and payloads are not logged unless debug mode is enabled.

Consume Flow (SOAP-to-REST)

The consume flow exposes a modern REST/JSON backend as a standard SOAP web service. This allows legacy SOAP clients to integrate with services that only speak REST.

1. A SOAP client sends a POST request to /consume/{environment}/{serviceKey}.
2. The controller validates that the method is POST and that the Content-Type is appropriate for a SOAP request.
3. The route is resolved using the path, environment, and SOAPAction header to disambiguate operations that share an endpoint address.
4. If no route is found or the route has no active backend, a SOAP Fault is returned.
5. The inbound SOAP payload is parsed and mapped to a JSON structure based on the operation's requestMapping. This process handles xop:Include for MTOM attachments, inlining them into the SOAP envelope before parsing.
6. Authentication for the downstream REST backend is resolved. Supported methods include basic, bearer, and api_key_header.
7. The ConsumeSoapHandler dispatches the corresponding REST request (e.g., GET, POST) to the backend, including the generated JSON payload and authentication headers.
8. The REST response from the backend is received.
9. The handler maps the JSON response back into a SOAP envelope, which is then returned to the original SOAP client. If the REST call fails, a SOAP Fault is generated instead.
10. A log entry for the transaction is persisted.

Asynchronous Processing

For long-running publish operations, the controller supports an asynchronous callback pattern.

1. Initiation: An API consumer makes a publish request to an operation configured with executionMode set to async_callback.

   • The controller validates the request and dispatches it to the backend.
   • It immediately returns a 202 Accepted response. The response body contains a correlationId, a pollPath for checking status, and a single-use pollToken. The token is also returned in the X-S2R-Poll-Token header.
   • An AsyncExecutionRecord is created in the database with a status of waiting_callback.

2. Polling: The consumer can poll the status by making a GET request to the pollPath (/{direction}/{...}/async/{correlationId}).

   • The request MUST include the X-S2R-Poll-Token header received during initiation.
   • The controller verifies that the poll request comes from the same authenticated principal (tenant and API key) that initiated the execution.
   • The response contains the current status (waiting_callback, completed, failed, expired). If completed, the final result payload is included.

3. Callback: The backend SOAP service completes its processing and sends the result in a SOAP response to a special callback endpoint: POST /_s2r/callback/{environment}/{serviceKey}/{operationKey}.

   • The callback request's SOAP body must contain a WS-Addressing header (RelatesTo or MessageID) that matches the original correlationId.
   • Authentication: The controller authenticates the callback. If callback_auth_mode is shared_secret, the callback must provide the correct secret in the X-S2R-Callback-Secret or Authorization: Bearer header. Unauthenticated callbacks are rejected with a 401 Unauthorized.
   • The controller updates the AsyncExecutionRecord with the result and sets the status to completed or failed.
   • The operation is idempotent; if a callback arrives for an already-completed execution, it is rejected with a 409 Conflict.

WSDL Serving

The controller can serve a WSDL contract for consume and gateway services, which is essential for SOAP client tooling. A WSDL is requested by appending ?wsdl to the service's base URL or by appending a /wsdl path segment.

• Endpoint: GET /consume/{env}/{serviceKey}?wsdl or GET /gateway/{env}/{serviceKey}?wsdl
• Mechanism:
  1. The controller detects the WSDL request.
  2. For gateway services, it first applies the GatewayIngressGuard and ConsumerIpGrantGuard to ensure only authorized clients can discover the service's topology.
  3. It retrieves the WSDL XML associated with the active service version from the runtimeWsdlRepository.
  4. It dynamically rewrites the <soap:address location="..."> attribute in the WSDL to point to the public-facing URL of the platform itself. This ensures that client stubs generated from the WSDL will send requests back to the platform, not to the original backend address.
  5. The rewritten WSDL is returned with a Content-Type of application/wsdl+xml.

Security and Validation

The controller enforces security and data integrity at multiple stages of the request lifecycle.

Backend Selection and Health

When a route has multiple backend targets, the controller uses a defined strategy to select one.

• Routing Mode (backendRoutingMode):

  • single: Only the preferred backend (by defaultBackendProfileId or lowest routingPriority) is used.
  • active_passive: Tries backends in order of routingPriority. The first successful one is used.
  • round_robin: Distributes requests across all healthy backends according to their routingWeight.

• Health Checks (backendHealthCheckMode):

  • Before sending a request in a multi-backend scenario, the controller can check backend health. Unhealthy backends are temporarily removed from the pool.
  • Checks are cached for a duration defined by backendHealthCheckIntervalSec.
  • Modes:
    • none: No health checks are performed.
    • ping: An ICMP ping to the backend host.
    • tcp: A TCP connection test to the backend's host and port.
    • wsdl_fetch: An HTTP GET to the backend's WSDL or health check URL. This can include semantic validation to ensure the WSDL still contains the required operation and namespace.

Error Handling

The controller generates structured JSON error responses. The exact shape is configurable via the errorShapeOverride setting.

Fault Detail Exposure

When a backend returns a SOAP Fault, the level of detail included in the client-facing error response is controlled by the faultDetailExposureMode:

• safe (default): Only the faultCode is exposed. All other fields, which may contain sensitive backend information like stack traces or hostnames, are scrubbed.
• full: The entire parsed fault structure is passed through to the client.

The full, unscrubbed fault is always available to operators in the transaction logs.

Endpoint Reference

Key Headers

See Also

• Payload Conversion Options: The platform provides a rich set of options for controlling how data is converted between JSON and SOAP, including handling for datetimes, booleans, nulls, and arrays. These are configured at the system, operation, and field levels.
• License Enforcement: The readiness of the runtime is tied to the platform's license state, which is managed by the EnforcementProbe.
• Runtime Logging: All transactions are logged in detail to the s2r_runtime_log table for auditing and troubleshooting.

All SOAP-to-REST docs