http
v0.23.5Expose functions as HTTP endpoints — hosts `http::on-request`; each observer of it declares a route, and its target answers the matched requests.
Install
iii trigger compose::add worker=httpRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
- concurrency_request_limit: 1024
cors:
allowed_methods:
- GET
- POST
- PUT
- DELETE
- OPTIONS
allowed_origins:
- *
default_timeout: 30000
host: 0.0.0.0
port: 3111
webhook_listener: nullhttp
Exposes registered functions as HTTP endpoints. A function becomes a route
when it observes http::on-request with the route as args: external clients
then call it with a plain HTTP request, which is what you want for webhooks,
browser clients, or any caller outside the engine's WebSocket protocol.
Routing, path params, per-route and global middleware, CORS, and chunked
streaming responses are handled by this worker; the function receives an
HttpRequest and returns the response.
Install
iii call compose::add worker=httpiii call compose::add resolves the worker and its dependencies, writes
exact declarations to worker-compose.yaml, and reconciles the Compose project.
Quickstart
Register a function and observe http::on-request with it, passing the route
(method and path) as args:
iii.registerFunction('orders::get', async (req: HttpRequest) => ({
status_code: 200,
body: { order_id: req.path_params.id },
}))
const route = iii.observe(
{ function_id: 'http::on-request', args: { method: 'GET', path: '/orders/:id' } },
'orders::get',
)
await route.ready() // rejected with HTTP_ROUTE_CONFLICT if the shape is taken
// later: await route.dispose() removes the routeThe same in Rust:
use iii_http::types::HttpRequest;
use iii_sdk::{errors::Error, register_worker, InitOptions, RegisterFunction, Source};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
iii.register_function(
"orders::get",
RegisterFunction::new_async(|req: HttpRequest| async move {
Ok::<Value, Error>(json!({
"status_code": 200,
"body": { "order_id": req.path_params.get("id") },
}))
}),
);
iii.observe(
Source::function("http::on-request").args(json!({ "method": "GET", "path": "/orders/:id" })),
"orders::get",
);
tokio::signal::ctrl_c().await?;
Ok(())
}curl http://localhost:3111/orders/42
# {"order_id":"42"}The function's return value becomes the response: status_code (default
200), headers (an object, or a list of "Name: value" lines), and body.
Path segments prefixed with : (e.g. :id) land in req.path_params; the
query string and headers arrive as req.query_params / req.headers.
Functions
| Function | Args or input | What it is |
|---|---|---|
http::on-request |
args { method, path, public_webhook?, middleware_function_ids? } |
One call per HTTP request the server receives. Each observer serves one route; its target receives the HttpRequest. |
http::status |
none | Where the server listens: { host, port, url, last_reload_error }. |
http::webhook-listener::status |
none | Internal: the restricted listener this process bound, and the last reload error. |
http::configuration-id |
none | Internal: this instance's configuration entry id. |
http::on-config-change |
the configuration::on-updated event |
Internal: reloads the configuration. |
http::on-request
| Arg | Required | Default | Description |
|---|---|---|---|
method |
yes | — | HTTP method to match (case insensitive). |
path |
yes | — | Route path, e.g. /orders/:id (or /orders/{id}). :name segments become path_params. |
public_webhook |
no | false |
Also expose this route on the restricted listener. |
middleware_function_ids |
no | [] |
Per-route middleware, run in list order after any global middleware and before the target. |
Unknown args are refused with INVALID_ARGS. Two observers cannot claim the
same method and path shape (/a/:x and /a/:y are one shape): the later one
is rejected with HTTP_ROUTE_CONFLICT.
A route lasts while its observer's worker is connected. When that worker's
connection goes away, the engine withdraws its observers from the http worker:
their routes answer 404, and another observer can claim the shape. A worker
that restarts under the same worker name and observes again under the same
observer id within the engine's observers.observer_grace_ms (30 s by
default) replaces its earlier observer and gets the route back. For this, give
the worker a name that stays the same across restarts: III_WORKER_NAME
(iii compose and iii worker set it for the workers they start) or the
SDK's worker name option. The default name, hostname:pid, changes when the
process restarts, so a restarted process under it is another worker. For any
other worker the id is taken until the grace period ends: its observe is
rejected with OBSERVER_ID_CONFLICT.
// A non-empty III_WORKER_NAME overrides workerName.
const iii = registerWorker('ws://localhost:49134', { workerName: 'orders-api' })
const route = iii.observe(
{ function_id: 'http::on-request', args: { method: 'GET', path: '/orders/:id' } },
'orders::get',
{ id: 'orders-get-route' }, // with the fixed worker name, the route survives a restart
)In Rust the name is WorkerMetadata::name:
use iii_sdk::runtime::WorkerMetadata;
use iii_sdk::{register_worker, InitOptions, ObserverOptions, Source};
use serde_json::json;
let iii = register_worker(
"ws://localhost:49134",
InitOptions {
metadata: Some(WorkerMetadata {
name: "orders-api".to_string(),
..WorkerMetadata::default()
}),
..InitOptions::default()
},
);
iii.observe_with(
Source::function("http::on-request").args(json!({ "method": "GET", "path": "/orders/:id" })),
"orders::get",
ObserverOptions::default().id("orders-get-route"),
);The server calls http::on-request once for every request it receives (its
CORS layer answers OPTIONS requests, and the restricted listener refuses
the ones no public route matches). The call's input is the request as the
server received it:
{
"method": "GET",
"path": "/orders/42", // the request's path
"query_params": { "expand": "items" },
"headers": { "content-type": "application/json" },
"body": null // the body parsed as JSON, else null
}The worker delivers each call itself:
- a path with no route gets
404, and a path whose routes are on other methods gets405withAllow; - a body over 16 MiB gets
413; - the observer's
filtersselect requests byinput(the request above); a request they reject gets422 CONDITION_NOT_MET; - the global middleware runs, then the route's middleware; a middleware that responds ends the request with its response;
- the target runs with the
HttpRequest, and its return value (or its writes to the response channel) is the response.
Steps 1 to 4 answer the call without calling the target. The middleware and
the target are called from the call's invocation, so a trace shows each
request as one call of http::on-request with them under it. What the
route's target receives:
{
"method": "GET",
"path": "/orders/:id", // the matched route's template
"path_params": { "id": "42" },
"query_params": { "expand": "items" },
"headers": { "content-type": "application/json" },
"body": null, // the body parsed as JSON, else null
"request_body": { /* channel ref: the exact request bytes */ },
"response": { /* channel ref: write a streamed response here */ }
}The target always receives the HttpRequest, whatever the observer's
capture says, and the observer's metadata arrives as the target's
metadata sidecar:
iii.observe(
{
function_id: 'http::on-request',
args: { method: 'POST', path: '/webhooks/stripe', public_webhook: true },
filters: { 'input.headers.stripe-signature': { $exists: true } },
},
'billing::on-stripe-event',
)http::on-request is private: only this worker calls it, and it cannot be an
observer's target. It has one host per namespace: a second http worker in
the same namespace cannot register it.
Streaming responses
A target can stream its response: write to req.response (a
StreamChannelRef) with a ChannelWriter to send set_status /
set_headers control frames and body chunks for a chunked HTTP response, and
return null. Returning a non-null value instead yields a regular buffered
response built from { status_code, headers, body }.
Configuration
| Field | Default | Description |
|---|---|---|
port |
3111 |
TCP port the HTTP server binds to. 0 binds an OS-assigned ephemeral port. |
host |
0.0.0.0 |
Host/interface to bind. |
webhook_listener |
null (disabled) |
Optional restricted listener; only explicitly opted-in routes. |
webhook_listener.host |
127.0.0.1 |
Restricted listener interface; does not inherit host. |
webhook_listener.port |
3112 |
Restricted listener port; separate from the normal/admin listener on 3111. |
default_timeout |
30000 (ms) |
Per-request timeout; on expiry the server returns 504. |
cors.allowed_origins |
[] (permissive) |
Allowed CORS origins. An empty list allows any origin. |
cors.allowed_methods |
[] (permissive) |
Allowed CORS methods. An empty list allows any method. |
concurrency_request_limit |
1024 |
Maximum in-flight requests; requests over the limit wait for a slot. |
middleware[] |
[] |
Global middleware, each { function_id, phase, priority }, run on every route in ascending priority order before the route's own middleware. |
Configuration is owned by the configuration worker — edit it from the
console (Configuration → Workers → http) or seed it once via
--config <file>.yaml on first boot. The worker observes
configuration::on-updated for its entry. middleware and default_timeout
hot-reload without a restart, as do cors and concurrency_request_limit.
Changing host/port or webhook_listener binds the new addresses before
stopping the old listeners. All required binds must succeed; otherwise both
old listeners and their live configuration remain unchanged. Set
webhook_listener: null to disable it live. Shutdown drains both listeners
and serializes with reload; a late reload cannot restart a stopped server.
http::status reports where the server actually listens: { host, port, url, last_reload_error }, where url is the base URL to open from this
machine (http://127.0.0.1:<port> when it listens on every interface). It
is read-only and open to agents, so code and agents build page URLs from it
instead of assuming port 3111.
Restricted webhook listener
Enable the optional listener in the existing http configuration:
host: 127.0.0.1
port: 3111
webhook_listener:
host: 127.0.0.1
port: 3112The internal http::webhook-listener::status function distinguishes saved
configuration from a listener that this process actually opened. Its applied
field contains the host from the applied configuration and the actual port from
the bound socket (including an OS-assigned port when configured with 0), or
null when the listener is off. The
last_reload_error field reports the most recent failed reload and is cleared
by the next successful one. The function waits for an in-progress reload
before responding and exposes no other HTTP configuration.
Opt a route in with public_webhook in its observer's args:
{"method":"POST","path":"/webhooks/github","public_webhook":true}Only that opted-in route is eligible on 3112; it remains available on 3111.
Do not expose 3111 through a public proxy/tunnel. The restricted listener
mounts no Console, engine, or admin endpoints. Its private paths return 404
(including OPTIONS); methods not opted in for an eligible path return 405
with only public methods in Allow. The listener answers both before CORS
and before it reads the body, so only a request a public route matches is a
call of http::on-request, whose deliver hook matches it against the public
routes again. Matching performs
no URL decoding, repeated/trailing-slash normalization, HEAD-to-GET aliasing,
or method-override handling. Parameter routes are still supported: opting
one in deliberately exposes every value matched by its parameter segments,
never a more specific private handler. Disposing a route's observer, or
observing it again without public_webhook, applies to subsequent requests.
Both listeners share the route table, configuration and layered router; global and per-route middleware, timeouts, concurrency and the 16 MiB body limit apply to both. A bind collision, including using the normal address for the restricted listener, fails safely rather than combining them.
Signature verification: read HttpRequest.request_body using the SDK
ChannelReader; it contains the exact received bytes (UTF-8, JSON whitespace,
newlines and binary data included). Never compute HMAC from body, which is
only a parsed JSON convenience projection. Header names follow HTTP's
case-insensitive/lowercase representation; ASCII values such as
x-hub-signature-256 and x-github-delivery pass through unchanged. The
header map is not a raw HTTP-header archive: duplicate headers and non-text
values are not represented byte-for-byte. This listener does not validate
signatures itself; the opted-in handler must authenticate deliveries.
Local tests
tests/webhook_listener.rs and tests/on_request.rs use the shared harness's
loopback fake engine, which plays the observer lifecycle of
http::on-request, and real SDK binary channels, without any external service
or skipped tests:
CARGO_TARGET_DIR=target-http-local cargo test --locked --test webhook_listener --test on_request
cargo fmt --all -- --check
CARGO_TARGET_DIR=target-http-local cargo clippy --all-targets --all-features --locked -- -D warningsThe e2e_* suites need a running engine. They connect to
III_ENGINE_WS_URL (default ws://127.0.0.1:49134): point it at a disposable
engine, or at a closed port to skip them.