Asynchronous Execution Repository

Overview

The Asynchronous Execution Repository is a data access component responsible for managing the lifecycle and persistent state of asynchronous API operations. When an API consumer initiates an operation that is processed asynchronously (returning a 202 Accepted response), this repository creates and manages a record of that execution.

This component solves the problem of tracking long-running, out-of-band operations. It provides the persistence layer for the following capabilities:

• Creation: Storing the initial request details, security context of the initiator, and a unique correlation ID.
• Status Tracking: Maintaining the execution's state, from waiting_callback to completed, failed, or expired.
• Secure Polling: Enabling the original API consumer to securely poll for the status and result of their specific execution using a unique token.
• Finalization: Atomically updating the execution record with the final result (or failure details) received from a backend callback.
• Data Retention: Managing the expiration and eventual cleanup of execution records.

All database operations performed by this repository are strictly scoped to the tenant of the authenticated caller, preventing any possibility of one tenant accessing or modifying another tenant's execution records.

How it Works

The repository manages an s2r_async_execution database table where each row represents a single asynchronous operation. The lifecycle of an execution is managed through a series of state transitions orchestrated by this component's methods.

sequenceDiagram
    participant C as API Consumer
    participant P as API Platform
    participant R as Async Execution<br>Repository
    participant D as Database

    C->>P: 1. Initiate async API call
    P->>R: 2. createPending(...)
    R->>D: 3. INSERT into s2r_async_execution<br>(status: 'waiting_callback')
    R-->>P: Returns new AsyncExecutionRecord
    P-->>C: 4. Respond 202 Accepted<br>with correlation ID & poll token

    loop Poll for result
        C->>P: 5. GET /status?correlationId=...<br>(with poll token)
        P->>R: 6. findByCorrelationForCaller(...)
        R->>D: 7. SELECT with security checks<br>(tenant, key hash, token hash)
        D-->>R: Returns matching record
        R-->>P: Returns AsyncExecutionRecord
        P-->>C: 8. Respond with current status
    end

    Note over P, D: Later...

    participant B as Backend System
    B->>P: 9. Send callback with final result
    P->>R: 10. complete(...) or fail(...)
    R->>D: 11. UPDATE s2r_async_execution<br>where status = 'waiting_callback'
    D-->>R: Returns 1 if row updated
    R-->>P: Returns updated record or null

    Note over C, P: Later, on next poll...
    C->>P: 12. Polls again
    P->>P: (Steps 6-8 repeat)
    P-->>C: 13. Respond with final status<br>(e.g., 'completed') and payload

1. Execution Creation

When an asynchronous operation is initiated, the platform calls the createPending method. This method:

1. Generates a new, unique internal ID (id) for the execution record.
2. Constructs an INSERT statement for the s2r_async_execution table.
3. Persists the request details, including the service and operation identifiers, request payloads, and the client-provided correlationId.
4. Sets the initial status to waiting_callback.
5. Records the security context of the initiator: the initiator_tenant_id and a SHA-256 hash of their API key (initiator_key_hash).
6. Stores a SHA-256 hash of the single-use poll_token that was generated for this execution. The raw token is never stored.
7. Calculates and sets an expires_at timestamp based on the configured retentionDays.

2. Secure Status Polling

An API consumer polls for the result using the correlationId returned in the initial 202 response. The platform uses the findByCorrelationForCaller method to retrieve the status. This lookup is designed for security:

• It requires the correlationId, the route identifiers (environment, service_key, operation_key), and the callerTenantId.
• It requires the caller to present the original poll_token. The repository performs a constant-time comparison between the SHA-256 hash of the presented token and the stored poll_token_hash.
• As a defense-in-depth measure, the query also validates that the callerTenantId and callerKeyHash match the initiator_tenant_id and initiator_key_hash stored when the record was created.

A record is returned only if all these conditions are met. A mismatch in any condition, an unknown ID, or a missing token are indistinguishable and all result in null being returned, preventing information leakage.

3. Execution Finalization

When the backend system completes the work, it sends a callback to the platform, which then calls either complete or fail on the repository.

• complete: Updates the record's status to completed and stores the final response payloads from the callback.
• fail: Updates the status to failed and stores a failure_message.

Both update operations are atomic and idempotent. They include where status = 'waiting_callback' in the UPDATE statement. This ensures that a given execution can only be finalized once. Any subsequent or racing callbacks for the same execution will find the status is no longer waiting_callback and the update will affect zero rows.

4. Expiration

A background process can call expireIfOverdue to manage records that never receive a callback. This method will update an execution's status from waiting_callback to expired if its expires_at timestamp is in the past.

Data Model

The following fields are stored for each asynchronous execution in the s2r_async_execution table.

API Reference

The component exposes Java methods for internal platform use. The primary methods and their parameters are detailed below.

createPending

Creates a new record for an asynchronous execution in the waiting_callback state.

Parameters

Returns

The newly created AsyncExecutionRecord, or null if the record could not be found immediately after creation.

findByCorrelationForCaller

Finds an execution record for a polling API consumer, performing strict security checks.

Parameters

Returns

The AsyncExecutionRecord if all identifiers and security credentials match; otherwise, null.

complete

Marks an execution as completed. This is an atomic, idempotent operation.

Parameters

Returns

The updated AsyncExecutionRecord if the update was successful, or null if the record was not found or was not in the waiting_callback state.

fail

Marks an execution as failed. This is an atomic, idempotent operation.

Parameters

Troubleshooting

Polling returns no record

A call to findByCorrelationForCaller returns null under several conditions, which are deliberately made indistinguishable to the polling client for security reasons:

• The correlationId does not exist.
• The presentedPollToken is missing, malformed, or does not match the stored token hash for the execution.
• The polling client's callerTenantId does not match the initiator_tenant_id stored for the execution.
• The polling client's callerKeyHash does not match the initiator_key_hash stored for the execution.
• The record predates the implementation of these security checks (i.e., poll_token_hash or initiator_tenant_id is null).

Callback fails to update execution status

A call to complete or fail returns null, indicating that zero rows were updated in the database. This occurs if the targeted execution record was not in the waiting_callback state at the time of the update. This is expected behavior for:

• Duplicate callbacks: A second callback arrives for an execution that has already been completed or failed by a previous callback.
• Racing callbacks: Two callbacks for the same execution arrive concurrently. Only the first one to acquire the row lock will succeed.
• Expired executions: A callback arrives after the execution has already been transitioned to the expired state by a cleanup process.

This mechanism ensures that the final state of an execution is written exactly once.

All SOAP-to-REST docs