HTTP

Octo ships two HTTP connectors: http, a server connector whose sources turn inbound requests into flow executions and write the flow's result back as the response, and http-client, an outbound client that the rest block runs requests through.

http connector

The http connector (label: HTTP Server) owns a single HTTP server — host, port, base path, server timeouts, and CORS. Each flow fronted by an http source registers a route on that shared server.

Provides a source: yes — the HTTP route source (below). Blocks that bind to it: none; the rest block binds to http-client.

Settings

Duration settings accept Go duration strings (5s, 250ms).

CORS settings (cors)

CORS is off unless allowedOrigins is non-empty. When set, the connector answers OPTIONS preflights and adds CORS headers on every route.

http source

Each http source binds one route pattern to a flow. The request becomes the flow's input message; the flow's final message becomes the response.

How the request maps into the message

• Path parameters — every {name} in path lands in vars.name (e.g. /orders/{id} sets vars.id).
• Method — vars.method holds the HTTP method, so a flow can route on vars.method == "POST".
• Query string — vars.query is a map of query parameters (first value of each key); it is always present, possibly empty.
• Headers — each header listed in headers is copied into a variable of the same name, e.g. vars["X-Tenant"].
• Body — a JSON body becomes body. A malformed JSON body is rejected with 400 before the flow runs, unless rawBody: true, in which case the body enters the flow as raw content carrying the request's Content-Type. An empty body is valid (body stays null).
• Raw bytes — with rawBodyVar set, the exact request bytes are also stored in that variable as a string.

How the response is written

• A completed flow returns its final body as JSON with status 200, or as raw content with its own Content-Type when the body is raw content.
• Setting vars.httpStatus to a valid code (100–599) overrides the response status.
• Variables named in responseHeaders are emitted as response headers (scalar values only).
• A dropped message (e.g. a filter matched nothing) responds 204 No Content.
• A failed flow responds 500 with a JSON {"error": ...} body — see error handling.
• A flow that exceeds the timeout responds 504.

The runtime reads the whole request into memory and writes the whole response at once — there is no streaming. See Raw Content and Streaming for how to serve non-JSON payloads and why the payload is always materialized.

Example

Adapted from samples/http-orders.yaml:

service:
  name: http-orders

env:
  - name: HTTP_PORT
    default: "8080"

connectors:
  - name: api
    type: http
    settings:
      port: ${HTTP_PORT}
      basePath: /api/v1
      requestTimeout: 5s

flows:
  - name: orders-api
    source:
      connector: api
      type: http
      settings:
        path: /orders/{id}            # {id} -> vars.id
        correlationIdHeader: X-Request-Id
        headers: [X-Tenant]           # captured as vars["X-Tenant"]
    process:
      - type: set-payload
        settings:
          value: '{"orderId": vars.id, "tenant": vars["X-Tenant"], "status": "found"}'

curl -s localhost:8080/api/v1/orders/42 -H 'X-Tenant: acme'

http-client connector

The http-client connector (label: HTTP Client) owns a configured client for calling external HTTP APIs: base URL, authentication, default headers, a request timeout, retry on 429, and an opt-in in-memory response cache for GETs. The rest block references it by name.

Provides a source: no — it is outbound only. Blocks that bind to it: rest.

Settings

Authentication (auth)

For oauth2, the connector mints and refreshes a bearer token via the client-credentials grant and applies it to each request. A request that already carries an Authorization header is never overwritten.

Retry (retry)

When an upstream returns 429 Too Many Requests, the connector honors the Retry-After header when present, otherwise backs off exponentially. Each wait is capped at maxBackoff.

Cache (cache)

rest block

REST Call — make an HTTP request through an http-client connector. Method and path are static; query parameters, headers, and the request body are CEL expressions evaluated per message. The response is folded into the message body: JSON parses into body, anything else becomes raw content carrying the response's Content-Type, and an empty response leaves body null.

Example

Adapted from samples/weather.yaml — a scheduled GET against a public API, cached for 60 seconds:

service:
  name: weather

connectors:
  - name: open-meteo
    type: http-client
    settings:
      baseURL: https://api.open-meteo.com
      timeout: 10s
      cache:
        enabled: true
        ttl: 60s
  - name: ticker
    type: cron

flows:
  - name: weather
    source:
      connector: ticker
      type: cron
      settings:
        schedule: "@every 30s"
    process:
      - type: rest
        name: fetch-forecast
        settings:
          connector: open-meteo
          method: GET
          path: /v1/forecast
          query:                       # values are CEL expressions
            latitude: '"52.52"'
            longitude: '"13.41"'
            current: '"temperature_2m"'
      - type: log
        settings:
          message: '"current temperature: " + string(body.current.temperature_2m)'