`http-server://`¶

HTTP server endpoint — receives inbound HTTP requests and dispatches each into a route. Consumer-side only (from:). Multiple routes can bind to the same host:port and share a single listener+mux, so a REST API that exposes five paths on :8080 opens exactly one socket.

For outbound HTTP calls, use http:// or https://.

URI shape¶

http-server://<bind>[/path][?cors=true&tlsCert=...&tlsKey=...&tlsCA=...]

<bind> is host:port (e.g. 0.0.0.0:8080). If no port is supplied, 8080 is used. path is the request path the route handles (/-prefixed). Go 1.22 ServeMux method routing is supported via the httpMethodRestrict parameter.

Parameters¶

Pulled from (*ServerComponent).Describe(). TLS parameter aliases (certFile → tlsCert, keyFile → tlsKey, caFile → tlsCA) are accepted; providing both certFile + keyFile auto-enables TLS unless tls=false is set explicitly.

Param	Type	Default	Description
`bind`	path	—	`host:port[/path]`.
`cors`	boolean	`false`	Enable CORS headers (every CORS response is `*` unless `corsOrigin` is set).
`corsOrigin`	string	`*`	Origin sent in `Access-Control-Allow-Origin`.
`httpMethodRestrict`	string	—	Restrict the handler to a single HTTP method (`GET`, `POST`, …) using Go 1.22 `METHOD /path` mux pattern.
`tlsCert`	string	—	Path to PEM-encoded server certificate.
`tlsKey`	string	—	Path to PEM-encoded server private key.
`tlsCA`	string	—	Path to CA certificate for client auth (mTLS).
`tls`	boolean	auto	Enable TLS. Auto-enabled when `tlsCert`+`tlsKey` are present.
`certFile` / `keyFile` / `caFile`	string	—	Aliases for the `tls*` knobs.

Body shape¶

For every request, the consumer creates an InOut exchange with:

In body: request body bytes (read up to 100 MB).
In headers: every HTTP header (first value), plus query params exposed individually (e.g. ?lang=en ⇒ lang=en header).
HelixHttpMethod = request method.
HelixHttpPath = r.URL.Path.
HelixHttpQuery = r.URL.RawQuery.
fromUri = the endpoint URI (e.g. http-server://0.0.0.0:8080/api).

After the processor returns:

The In body becomes the response body bytes (ex.In().BodyAsBytes()).
HelixHttpResponseCode (an int header) becomes the status code (default 200).
Content-Type header is forwarded if set.
Any X-* (and other custom) headers are forwarded; HTTP-protocol and Helix* internal headers are filtered.

Special body types short-circuit to streaming:

Body type	Behaviour
`*llm.StreamReader`	Streams as Server-Sent Events (`text/event-stream`), one `data:` line per chunk, ending with `data: [DONE]`.
`<-chan string`	Same SSE wrapping per channel send.

If the processor returns security.ErrUnauthorized, the server replies 401; any other error becomes 500 with the error message in the body.

Headers¶

Header	Direction	Description
`HelixHttpMethod`	inbound	Request method.
`HelixHttpPath`	inbound	Request path.
`HelixHttpQuery`	inbound	Raw query string.
Query params as headers	inbound	`?foo=bar` ⇒ `foo=bar` header.
`HelixHttpResponseCode`	outbound	Sets the response status (int). Default 200.
`Content-Type`	outbound	Forwarded to the response.

CORS preflight (OPTIONS) is auto-handled with 204 No Content when cors=true.

Examples¶

Minimal JSON API:

- id: customers
  from: http-server://0.0.0.0:8080/v1/customers
  steps:
    - to: postgres://customers/find
    - setHeader:
        name: Content-Type
        constant: application/json

Method-restricted route (multiple verbs on the same path):

- id: get-customer
  from: http-server://0.0.0.0:8080/v1/customers?httpMethodRestrict=GET
  steps:
    - to: direct://load-customer

- id: post-customer
  from: http-server://0.0.0.0:8080/v1/customers?httpMethodRestrict=POST
  steps:
    - to: direct://create-customer

TLS-terminating server with mTLS:

- from: http-server://0.0.0.0:8443/secure?tlsCert=/etc/ssl/server.crt&tlsKey=/etc/ssl/server.key&tlsCA=/etc/ssl/clients-ca.pem

Streaming LLM response (SSE):

- id: chat
  from: http-server://0.0.0.0:8080/chat
  steps:
    - to: openai://gpt-4o-mini?stream=true
  # The body returned by openai:// is *llm.StreamReader; the server
  # auto-frames it as SSE.

Behavior notes¶

Shared listener. All endpoints with the same host:port register on a single *http.ServeMux and one listener. The first endpoint starts the server goroutine; later ones add handlers to the same mux. The reference-counted listener is shut down by ServerComponent.Stop.
Metrics hook. RegisterHTTPMetricsHook lets the metrics package observe every request after it's served — used to emit http_requests_total{method,path,status} and http_request_duration_seconds without an import cycle.
CORS. Always sends Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS and a permissive Allow-Headers list. Override the origin with corsOrigin. Preflight returns 204 immediately.
No producer. http-server:// is consumer-only; CreateProducer errors. For server-push, use ws-server://.

Source¶

pkg/component/http/http.go — ServerComponent, ServerEndpoint, ServerConsumer, shared-listener bookkeeping, CORS / TLS normalisation, internal-header filter, SSE streaming.

http-server://¶