docs/modules/module-http.mdx
The HTTP Module exposes registered functions as HTTP endpoints.
modules::api::RestApiModule
- 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
This module adds a new Trigger Type: http.
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',
},
})
When an API trigger fires, the function receives an ApiRequest object:
Functions must return an ApiResponse object:
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.
| 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).
<Expandable title="Scope">
<ResponseField name="path" type="string" required>
Path prefix to match. Supports `:param` segments and a trailing `*` wildcard (e.g., `/api/*`).
</ResponseField>
</Expandable>
Middleware functions receive a MiddlewareRequest object:
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.sequenceDiagram
participant Client
participant Engine
participant Worker
Client->>+Engine: HTTP Request (GET /users/123)
Note over Engine: Match route
in registry
Engine->>+Worker: Invoke Function (JSON)
Note over Worker: Execute handler
Worker-->>-Engine: Return {status_code, body, headers}
Engine-->>-Client: HTTP Response
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',
},
})