HTTP

Expose functions as HTTP endpoints.

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.

Show Cors

allowed_origins · string[] · required

The allowed origins.

allowed_methods · string[] · required

The allowed methods.

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.

Show Trigger Config

api_path · string · required

The path of the API.

http_method · string · required

The HTTP method of the API.

condition_function_id · string

Function ID for conditional execution. The engine invokes it with the request; if it returns false, the handler function is not called.

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.

Show TriggerMetadata

type · string

The trigger type (e.g., http).

path · string

The matched route path pattern.

method · string

The HTTP method.

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

Show Trigger Config

phase · string · required

The lifecycle phase to attach to. One of: onRequest, preHandler, postHandler, onResponse, onError, onTimeout.

scope · object

Limits the middleware to requests matching a path prefix. When omitted, applies to all routes.

Show Scope

path · string · required

Path prefix to match. Supports :param segments and a trailing * wildcard (e.g., /api/*).

priority · number

Execution order within a phase. Lower values run first. Defaults to 0.

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',
  },
})