http

# http The `http` worker exposes registered functions as HTTP endpoints, turning a function into a route that browsers, webhooks, and external clients can call without using the iii SDK. It exposes no callable `http::*` functions; a route is declared by binding the `http` trigger type with a worker SDK trigger registration such as `iii.registerTrigger({ type: 'http', function_id, config })`, or, on iii 0.25 engines, by observing `http::on-request` with `iii.observe({ function_id: 'http::on-request', args: { method, path } }, target)`. Install it with `iii trigger compose::add worker=http`. The legacy in-engine HTTP service must not run on the same engine because it also owns the `http` trigger type. Remove the legacy built-in from the engine config before starting this worker; the standalone worker refuses to boot when the builtin is active. Incoming requests are matched by HTTP method and path. The invoked handler receives method, path, headers, query params, extracted `:path` params, parsed body, trigger metadata, and request/response stream channels. Returning a JSON value yields a buffered response; writing to the response channel yields a chunked streaming response. ## When to Use - A webhook, browser, mobile app, or third-party service needs to call an iii function over plain HTTP. - You need route matching with path params such as `/orders/:id`. - A route should have per-route middleware or a condition function before the handler runs. - You need CORS, HTTP status codes, headers, JSON bodies, or chunked streaming responses at the edge of the engine. - Several external routes should dispatch into normal iii functions while keeping their handler code in workers you control. ## Boundaries - No callable functions are exposed. Never invoke `http::*`; bind the `http` trigger type to one of your own functions, or observe `http::on-request` with it as the target (invoking `http::on-request` is refused with `FORBIDDEN`). - This is inbound HTTP. For outbound network requests from an agent or worker, use `web::fetch` instead. - This is not a scheduler or event queue. For clock-based execution, use `cron`; for data-change reactions, use the relevant state, stream, queue, or database worker. - The legacy in-engine HTTP service cannot run beside this standalone worker on the same engine because both own the `http` trigger type. - Route shapes with the same method and equivalent path structure conflict: `/orders/:id` and `/orders/:order_id` are the same shape. Triggers and `http::on-request` observers share one route table: the later one is refused (an observer with `HTTP_ROUTE_CONFLICT`). ## Reactive triggers Bind an `http` trigger when a handler should run automatically for each matching HTTP request. The handler runs through the engine as a normal function invocation, and the worker turns the handler's return value or stream writes back into an HTTP response. Reach for it when: - A public or internal API endpoint should call a registered function. - A webhook provider should invoke an iii workflow without a custom server. - Middleware should authenticate, enrich, or reject requests before the route handler runs. - A handler should stream chunks to the client instead of returning one buffered body. ### How to bind 1. Register a handler: `iii.registerFunction('orders::get', handler)`. 2. Register the trigger: ```typescript iii.registerTrigger({ type: 'http', function_id: 'orders::get', config: { api_path: '/orders/:id', http_method: 'GET', // condition_function_id and middleware_function_ids are optional. }, }) ``` `api_path` is required. `http_method` defaults to `GET`. Path segments prefixed with `:` are extracted into `path_params`; query string values arrive in `query_params`; request headers arrive in `headers`. Trigger config: | Field | Required | Default | Description | |---|---|---|---| | `api_path` | yes | - | Route path such as `/orders/:id`; `:name` segments become path params. | | `http_method` | no | `GET` | HTTP method to match. | | `condition_function_id` | no | - | Function invoked before middleware and handler; a falsy result rejects the request with `422`. | | `middleware_function_ids` | no | `[]` | Per-route middleware functions, run before the handler in list order. | ### How to observe (iii 0.25) Instead of a trigger, observe `http::on-request` with the route as its args and your handler as the target. The handler receives the same request and returns the same response as with a trigger. ```typescript const route = iii.observe( { function_id: 'http::on-request', args: { method: 'GET', path: '/orders/:id' }, // optional: filters on the request, e.g. { 'input.headers.x-api-key': { $exists: true } } }, 'orders::get', ) await route.ready() ``` Args: `method` and `path` are required; `public_webhook`, `middleware_function_ids` and the deprecated `condition_function_id` are optional and mean what they mean in the trigger config. Unknown args are refused with `INVALID_ARGS`. A request the observer's `filters` reject gets `422 CONDITION_NOT_MET` without calling the handler. `route.dispose()` removes the route. On a 0.24 engine `observe` fails with `UNSUPPORTED`: use the trigger. Handler return values become buffered responses with `status_code`, `headers`, and `body`; `status_code` defaults to `200` and `body` defaults to an empty object. For streaming, write `set_status` and `set_headers` control messages plus body chunks to the request's `response` channel; return `null` or no final buffered body from the handler. Configure the server through the central configuration entry for worker `http`: ```yaml port: 3111 host: 0.0.0.0 default_timeout: 30000 concurrency_request_limit: 1024 cors: allowed_origins: [] allowed_methods: [] middleware: [] ``` Global `middleware` runs on every route in ascending `priority` order. Per-route `middleware_function_ids` run after global middleware and before the handler. `middleware` and `default_timeout` hot-reload; `port`, `host`, CORS, and `concurrency_request_limit` take effect on the next restart.