Skip to content

http

v0.23.1

Expose functions as HTTP endpoints — hosts `http::on-request`; each observer of it declares a route, and its target answers the matched requests.

license: Apache-2.0apiendpointhttprest

Install

bash
iii trigger compose::add worker=http

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions5

http::configuration-id

Function

Returns this HTTP instance's configuration entry ID, without its value.

Request
Empty object
Response
  • idstringrequired

http::on-config-change

Function

Internal: reload http configuration from the authoritative store on change.

Request
Empty object
Response
  • okbooleanrequired

http::on-request

Function

One call per HTTP request the http worker receives (OPTIONS requests are answered by its CORS layer). Observe it with args { method, path } (plus optional public_webhook and middleware_function_ids) to serve that route: the worker calls the target with the HttpRequest (path template, path_params, query_params, headers, body, and the request_body and response channels), and its return value ({ status_code, headers, body }, or null after streaming to the response channel) is the response. A request without a route gets 404 (405 when the path has routes on other methods); a request the observer's filters reject gets 422. Filters read the request as the server received it: input.method, input.path, input.query_params, input.headers, input.body. Only the http worker calls it.

Request
  • bodyunknownrequired

    The body parsed as JSON; `null` when it is empty, not JSON, or over the server's body limit.

  • headersobjectrequired
  • methodstringrequired
  • pathstringrequired

    The request's path, e.g. `/orders/42`.

  • query_paramsobjectrequired
Response
  • bodyunknownrequired

    The body parsed as JSON; `null` when it is empty, not JSON, or over the server's body limit.

  • headersobjectrequired
  • methodstringrequired
  • pathstringrequired

    The request's path, e.g. `/orders/42`.

  • query_paramsobjectrequired

http::status

Function

Where the public HTTP server listens: its host, its port and the base URL to open from this machine (for example http://127.0.0.1:3111). Read-only; use it instead of assuming port 3111.

Request
Empty object
Response
  • hoststring

    The bound interface (`0.0.0.0` serves every network interface). None while the server is stopped.

  • last_reload_errorstring

    Last configuration reload failure, e.g. the port is already in use; cleared by the next successful reload.

  • portinteger· uint16min 0

    The bound port (the OS-assigned one for port 0). None while stopped.

  • urlstring

    The base URL to open from this machine, e.g. `http://127.0.0.1:3111`: loopback when the server listens on every interface.

http::webhook-listener::status

Function

Internal: the restricted webhook listener this process has actually bound and the last reload error.

Request
Empty object
Response
  • appliedany of

    The listener this process has bound: the last successfully applied configuration (a failed bind keeps the previous one). None when the listener is off or the server is stopped.

    any of (2)
    Variant 1
    • hoststring

      Loopback by default; expose only this listener through a reverse proxy.

    • portinteger· uint16min 0

      Restricted port, separate from the normal listener (3111).

    Variant 2
    valuenull
  • last_reload_errorstring

    Last configuration reload failure, e.g. the port is already in use; cleared by the next successful reload.

Search the registry

Find workers, kits and executables, or jump to a page.