Sqalin

Sqalin Documentation

Technical documentation for Sqalin execution layer

Core Concepts

Execution

An Execution represents one attempt to perform an HTTP request or event emission. Each Execution has:

  • A unique Execution ID
  • A type (sync, async, or queued)
  • A lifecycle with distinct states
  • Timestamps for each state transition
  • Status information
  • Request payload
  • Response payload (or error)

Execution Lifecycle

created→started→completed
failed|timed out

Execution Types

sync

Synchronous Execution

The caller waits for the execution result. Sqalin executes immediately and the HTTP response contains the execution result.

Typical use cases:

  • User-facing requests
  • Read operations
  • APIs that require immediate confirmation
async

Asynchronous Execution

The caller receives an immediate acknowledgement. Execution continues in background. Result is stored and optionally sent via callback.

Typical use cases:

  • Non-critical notifications
  • Fire-and-forget integrations
  • Background processing
queued

Queued Execution

The execution is placed in a queue and executed later by workers. Used to control concurrency and ordering.

Typical use cases:

  • Rate-limited APIs
  • Sequential processing requirements
  • Controlled concurrency

Queues

Queues in Sqalin are execution constraints, not infrastructure. They control how executions are processed.

Serial Queues

One execution at a time, guaranteed ordering

Parallel Queues

Limited concurrency, controlled throughput

Queues are typically defined by integration, connection, external system, or any logical grouping (e.g., moduleSetupId).

Why Queues Exist

  • To protect external systems from overload
  • To avoid internal resource exhaustion
  • To guarantee execution order when required

Callback

A callback is a new execution triggered after the main execution completes. Callbacks are optional and independent.

A callback contains:

  • executionId - Reference to the original execution
  • status - Final execution status
  • timestamps - Timing information
  • response or error - Execution result

Important: Callback failure does NOT affect the original execution result. Callbacks can fail and be retried independently.

Execution ID & Correlation ID

Execution ID

Uniquely identifies a single execution

Correlation ID

Groups multiple related executions

Correlation IDs are used to:

  • Trace business flows across multiple executions
  • Group retries and related operations
  • Audit integrations at a business level

Execution Flows

Synchronous Flow

Caller → Sqalin → Target System
        ↓
Sqalin → Caller (with response)

The caller waits for the complete execution before receiving a response.

Asynchronous Flow

Caller → Sqalin (immediate ack)
        ↓
Sqalin → Target System
        ↓
Sqalin → (optional callback)

The caller receives immediate acknowledgement and optionally gets notified via callback.

Queued Flow

Caller → Sqalin (queued)
        ↓
Sqalin → Queue
        ↓
Worker → Target System
        ↓
Worker → (optional callback)

Execution is queued and processed by workers according to queue constraints.

API Reference

Create Execution

POST/executions

Creates a new execution request. The request body specifies how and where the execution should be performed.

{
  "type": "sync | async | queued",
  "queue": "optional-queue-name",
  "request": {
    "method": "POST",
    "url": "https://external.api.com/resource",
    "headers": {
      "Authorization": "Bearer token"
    },
    "body": {
      "example": "data"
    },
    "timeout_ms": 30000
  },
  "callback": {
    "url": "https://client.app/callback",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer callback-token"
    }
  },
  "correlation_id": "order-12345"
}

Field Descriptions

type

Execution type: sync,async, orqueued

queue

Optional queue name. Required for queued executions. Defines execution constraints.

request

The HTTP request to execute. Contains method, URL, headers, body, and timeout.

callback

Optional callback configuration. Sqalin will POST execution results to this endpoint.

correlation_id

Optional correlation ID for grouping related executions.

Response

For synchronous executions:

{
  "execution_id": "exec_abc123",
  "status": "completed",
  "response": {
    "status_code": 200,
    "headers": { ... },
    "body": { ... }
  },
  "timestamps": {
    "created_at": "2026-01-13T10:00:00Z",
    "started_at": "2026-01-13T10:00:00Z",
    "completed_at": "2026-01-13T10:00:02Z"
  }
}

For asynchronous or queued executions:

{
  "execution_id": "exec_abc123",
  "status": "queued",
  "timestamps": {
    "created_at": "2026-01-13T10:00:00Z"
  }
}

Get Execution

GET/executions/:execution_id

Retrieves the full execution record by execution ID.

{
  "execution_id": "exec_abc123",
  "type": "async",
  "queue": "user-notifications",
  "status": "completed",
  "correlation_id": "order-12345",
  "request": {
    "method": "POST",
    "url": "https://external.api.com/notify",
    "headers": { ... },
    "body": { ... }
  },
  "response": {
    "status_code": 200,
    "headers": { ... },
    "body": { ... }
  },
  "timestamps": {
    "created_at": "2026-01-13T10:00:00Z",
    "started_at": "2026-01-13T10:00:01Z",
    "completed_at": "2026-01-13T10:00:03Z"
  }
}

Observability

Every execution is stored with complete traceability:

  • Full request and response payloads
  • Timestamps for each lifecycle transition
  • Error details and stack traces
  • Correlation IDs for related executions

Query executions by:

  • Execution ID
  • Correlation ID
  • Status
  • Queue name
  • Time range

Use Cases

Scenario 1: Legacy PHP system calling a fragile third-party API

Problem: PHP monolith needs to call an external API that has strict rate limits (max 10 requests/second). The API breaks if you send too many requests at once.

Solution: The PHP system sends executions to Sqalin with type: "queued" and a queue configured for 10 req/s. Sqalin handles rate limiting automatically.

Scenario 2: Async notifications from a sync-only service

Problem: A legacy service needs to send notifications after processing an order, but it is synchronous and cannot implement async patterns.

Solution: The service sends an async execution to Sqalin and immediately returns. Sqalin handles the notification in the background.

Scenario 3: Audit all integration calls

Problem: Company needs to audit all outbound HTTP calls for compliance. Currently, calls are scattered across dozens of services.

Solution: Route all integration traffic through Sqalin. Every execution is stored with full traceability, making audits simple.

When to Use Sqalin

When to use

  • You need to control concurrency or rate limiting for external APIs
  • You need async execution but your system is synchronous
  • You need full traceability of outbound HTTP requests
  • You want to centralize integration logic
  • You need guaranteed ordering of requests

When NOT to use

  • Event streaming or pub/sub patterns (use Kafka, RabbitMQ)
  • Complex multi-step business workflows (use a workflow engine)
  • Scheduled recurring jobs (use cron or a scheduler)
  • Internal service-to-service calls with no constraints