HTTP

The HTTP Worker exposes registered functions as HTTP endpoints.

iii-http

Sample Configuration

- name: iii-http
  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

number

The port to listen on. Defaults to 3111.

string

The host to listen on. Defaults to 0.0.0.0.

number

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

number

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

Cors

The CORS configuration.

Show Cors

string[]

required

The allowed origins.

string[]

required

The allowed methods.

number

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

boolean

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

string

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

boolean

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

string

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

Trigger Type

This worker adds a new Trigger Type: http.

Show Trigger Config

string

required

The path of the API.

string

required

The HTTP method of the API.

string

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

string[]

Function IDs for per-route middleware. The engine invokes each in order before the handler. Each must return { action: "continue" } or { action: "respond", response }.

Sample code

const fn = iii.registerFunction('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:

string

The request path.

string

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

Record<string, string>

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

Record<string, string>

URL query string parameters.

any

The parsed request body (JSON).

Record<string, string>

HTTP request headers.

object

Metadata about the trigger that fired the function.

Show TriggerMetadata

string

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

string

The matched route path pattern.

string

The HTTP method.

object

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

ApiResponse

Functions must return an ApiResponse object:

number

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

any

The response payload.

string[]

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

Middleware

The HTTP worker supports middleware functions that run before the handler. There are two types:

Per-route middleware — attached to a specific trigger via middleware_function_ids in trigger config
Global middleware — configured in iii-config.yaml, runs on all HTTP routes

Global Middleware Configuration

MiddlewareConfig[]

List of global middleware functions. Each runs on every HTTP request, before conditions and per-route middleware.

Show MiddlewareConfig

string

required

Function ID of the middleware to invoke.

string

Lifecycle phase. Currently only preHandler is supported. Defaults to preHandler.

number

Execution order. Lower values run first. Defaults to 0.

- name: iii-http
  config:
    port: 3111
    middleware:
      - function_id: "global::rate-limiter"
        phase: preHandler
        priority: 5
      - function_id: "global::auth"
        phase: preHandler
        priority: 10

Middleware Function Contract

Middleware functions receive a lightweight request object (no body):

string

The phase in which the middleware is executing (preHandler).

object

Request metadata: path_params, query_params, headers, method. Does not include body.

object

Empty context object for future use.

Middleware must return one of:

{ action: "continue" } — proceed to the next middleware or handler.
{ action: "respond", response: { status_code, body, headers } } — short-circuit and return a response immediately. Remaining middleware and the handler are skipped.

Execution Order

Route match
Global middleware (from config, sorted by priority)
Condition check (if configured)
Per-route middleware (from trigger config, in order)
Body parsing
Handler function

See the HTTP Middleware how-to guide for full examples.

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('api.getUser', getUser)
iii.registerTrigger({
  type: 'http',
  function_id: fn.id,
  config: {
    api_path: '/users/:id',
    http_method: 'GET',
  },
})

Getting Started

Primitives & Concepts

How-to Guides

Architecture

Workers

Console

Advanced

Examples

Sample Configuration

Configuration

Trigger Type

Sample code

Request & Response Objects

ApiRequest

ApiResponse

Middleware

Global Middleware Configuration

Middleware Function Contract

Execution Order

Request Lifecycle

Example Handler

​Sample Configuration

​Configuration

​Trigger Type

​Sample code

​Request & Response Objects

​ApiRequest

​ApiResponse

​Middleware

​Global Middleware Configuration

​Middleware Function Contract

​Execution Order

​Request Lifecycle

​Example Handler

Sample Configuration

Configuration

Trigger Type

Sample code

Request & Response Objects

ApiRequest

ApiResponse

Middleware

Global Middleware Configuration

Middleware Function Contract

Execution Order

Request Lifecycle

Example Handler