HTTP

The HTTP Module exposes registered functions as HTTP endpoints.

modules::api::RestApiModule

Sample Configuration

- class: modules::api::RestApiModule
  config:
    port: 3111
    host: 0.0.0.0
    cors:
      allowed_origins:
        - http://localhost:3000
        - http://localhost:5173
      allowed_methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS

Configuration

port

number

The port to listen on. Defaults to 3111.

host

string

The host to listen on. Defaults to 0.0.0.0.

default_timeout

number

The default timeout in milliseconds for request processing. Defaults to 30000.

concurrency_request_limit

number

The maximum number of concurrent requests the server will handle. Defaults to 1024.

cors

Cors

The CORS configuration.

body_limit

number

Maximum request body size in bytes. Defaults to 1048576 (1 MB).

trust_proxy

boolean

When true, the engine trusts proxy headers such as X-Forwarded-For for client IP resolution. Defaults to false.

request_id_header

string

Header name used to propagate or generate a request ID. Defaults to x-request-id.

ignore_trailing_slash

boolean

When true, routes with and without a trailing slash are treated as equivalent. Defaults to false.

not_found_function

string

Function ID to invoke when no route matches a request. When unset, the engine returns a default 404 response.

Trigger Type

This module adds a new Trigger Type: http.

Sample code

const fn = iii.registerFunction({ id: 'api.getUsers' }, handler)
iii.registerTrigger({
  type: 'http',
  function_id: fn.id,
  config: {
    api_path: '/api/v1/users',
    http_method: 'GET',
  },
})

Request & Response Objects

ApiRequest

When an API trigger fires, the function receives an ApiRequest object:

path

string

The request path.

method

string

The HTTP method of the request (e.g., GET, POST).

path_params

Record<string, string>

Variables extracted from the URL path (e.g., /users/:id).

query_params

Record<string, string>

URL query string parameters.

body

any

The parsed request body (JSON).

headers

Record<string, string>

HTTP request headers.

trigger

object

Metadata about the trigger that fired the function.

context

object

Request context object. Populated by middleware and available to handler functions.

ApiResponse

Functions must return an ApiResponse object:

status_code

number

HTTP status code (e.g., 200, 404, 500).

body

any

The response payload.

headers

string[]

HTTP response headers as "Header-Name: value" strings (e.g., ["Content-Type: application/json"]). Optional.

Middleware

The HTTP module supports a middleware system that runs functions at defined phases of the request lifecycle. Middleware functions are registered using the http_middleware trigger type.

Phases

Phase	Description
`onRequest`	Runs before route matching.
`preHandler`	Runs after route match, before the handler.
`postHandler`	Runs after the handler returns a response.
`onResponse`	Runs after the response is sent (fire-and-forget).
`onError`	Runs when the handler returns an error.
`onTimeout`	Runs when the handler exceeds the configured timeout.

Phases execute in priority order (lower number = higher priority).

Middleware Trigger Config

Middleware Function Contract

Middleware functions receive a MiddlewareRequest object:

phase

string

The phase in which the middleware is executing.

request

object

The current ApiRequest object.

context

object

Accumulated context from previous middleware in the same phase.

matched_route

object

Present on preHandler and later phases. Contains function_id and path_pattern.

response

object

Present on onResponse phase only. The response that was sent.

Middleware must return one of:

{ action: "continue", request?: object, context?: object } — pass control to the next middleware. Optional request and context patches are deep-merged into the current values.
{ action: "respond", response: { status_code, body, headers } } — short-circuit and return a response immediately. Subsequent middleware in the same phase is skipped.

Request Lifecycle

Example Handler

import { registerWorker } from 'iii-sdk'
import type { ApiRequest, ApiResponse } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

async function getUser(req: ApiRequest): Promise<ApiResponse> {
  const userId = req.path_params?.id
  const user = await database.findUser(userId)
  return {
    status_code: 200,
    body: { user },
    headers: { 'Content-Type': 'application/json' },
  }
}

const fn = iii.registerFunction({ id: 'api.getUser' }, getUser)
iii.registerTrigger({
  type: 'http',
  function_id: fn.id,
  config: {
    api_path: '/users/:id',
    http_method: 'GET',
  },
})

Sample Configuration

Configuration

Cors

Trigger Type

Trigger Config

Sample code

Request & Response Objects

ApiRequest

TriggerMetadata

ApiResponse

Middleware

Phases

Middleware Trigger Config

Trigger Config

Middleware Function Contract

Request Lifecycle

Example Handler

On this page