Skip to content

http://

HTTP/HTTPS client (producer only). Sends the exchange body as an outbound HTTP request and folds the response back onto the same exchange. For inbound (server-side) HTTP, see http-server://. For TLS endpoints use https:// (same component, different scheme).

URI shape

http://host[:port][/path]?param1=value&param2=value…
https://host[:port][/path]?param1=value&param2=value…

Everything after the scheme — including the path — is appended verbatim to the target URL: http://api.example.com/v1/users becomes a GET to http://api.example.com/v1/users. Per-request overrides flow through control headers (see below).

Parameters

Request shaping

Param Type Default Description
httpMethod enum GET HTTP method (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS/TRACE). Header HelixHttpMethod overrides per-request.
method enum — Legacy alias for httpMethod.
bridgeEndpoint boolean false Ignore HelixHttpUri override headers; always use the endpoint URI. Also forces a noop cookie store.
connectionClose boolean false Add Connection: close to outbound requests.
multipartUpload boolean false Wrap the body as a single multipart/form-data part.
multipartUploadName string data Form-field name for the multipart part.
customHostHeader string — Override outbound Host header.
preserveHostHeader boolean false Propagate inbound Host header to the upstream request.
deleteWithBody boolean false Allow HTTP DELETE to carry a body.
getWithBody boolean false Allow HTTP GET to carry a body.
userAgent string — User-Agent request header.
defaultUserAgentDisabled boolean false Suppress stdlib's Go-http-client/1.1 default UA.
logHttpActivity boolean false Debug-log request/response (method, URL, status, duration).

Response handling

Param Type Default Description
throwExceptionOnFailure boolean true Return a typed HTTP:* error when status falls outside okStatusCodeRange.
okStatusCodeRange string 200-299 CSV of N or N-M ranges, e.g. 200-204,209,301-304.
ignoreResponseBody boolean false Skip reading the response body (fire-and-forget).
responsePayloadStreamingThreshold integer 8192 Above this many bytes, the body is exposed as a StreamBody. -1 = always stream, 0 = never stream.
copyHeaders boolean true Copy IN exchange headers to OUT.
skipControlHeaders boolean false Ignore HelixHttp* control headers when shaping the request.
skipRequestHeaders boolean false Skip propagating any exchange headers as HTTP request headers.
skipResponseHeaders boolean false Skip mapping HTTP response headers back to the exchange.
contentTypeCharsetEnabled boolean true Append ; charset=UTF-8 to Content-Type for string bodies.
disableStreamCache boolean false Alias for responsePayloadStreamingThreshold=-1.

Cookies

Param Type Default Description
cookies enum enabled Cookie store mode: enabled (in-memory jar), disabled (no jar), noop (jar accepts but never returns).
cookieManagementDisabled boolean false Equivalent to cookies=disabled.

Connection pool

Param Type Default Description
maxTotalConnections integer 200 Max total idle connections across hosts.
connectionsPerRoute integer 20 Max idle (and total) connections per host.
connectionTimeToLive duration 0 (forever) Idle-connection TTL. Accepts Go duration (5s) or bare ms (30000).
useSystemProperties boolean false Honor HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars when no explicit proxy is set.
contentCompressionDisabled boolean false Disable automatic gzip decompression of responses.
followRedirects boolean false Follow up to 10 redirects automatically.

Proxy

Param Type Default Description
proxyHost string — Proxy server host.
proxyPort integer — Proxy server port.
proxyAuthScheme enum http Proxy URL scheme (http or https).
proxyAuthUsername string — Proxy basic-auth username.
proxyAuthPassword string — Proxy basic-auth password.
proxyAuthMethod enum — Proxy auth method. Only Basic is implemented. NTLM is rejected (deprecated upstream).
nonProxyHosts string — Comma-separated hosts that bypass the proxy. Supports leading-dot wildcards (.example.com) and trailing-* prefix.

Auth

Param Type Default Description
authUsername string — HTTP basic-auth username.
authPassword string — HTTP basic-auth password.
authBearerToken string — HTTP Bearer token.
authMethod enum implicit Basic or Bearer. Implicit from which credential field is set.
authenticationPreemptive boolean true (when creds set) Send Basic auth on the first request without waiting for a 401. Always preemptive — stdlib has no challenge mode.

OAuth2 (client credentials)

Param Type Default Description
oauth2ClientId string — OAuth2 client_id.
oauth2ClientSecret string — OAuth2 client_secret.
oauth2TokenEndpoint string — Token endpoint URL.
oauth2Scope string — Space-separated scope list.
oauth2ResourceIndicator string — OAuth2 resource indicator (RFC 8707).
oauth2BodyAuthentication boolean false Send client_id+client_secret as form fields instead of HTTP Basic.
oauth2CacheTokens boolean false Cache tokens in memory keyed by (endpoint, client_id, scope, resource).
oauth2CachedTokensDefaultExpirySeconds integer 3600 Fallback TTL when token response omits expires_in.
oauth2CachedTokensExpirationMarginSeconds integer 5 Refresh tokens this many seconds before expiry.

TLS

Param Type Default Description
tls boolean auto Auto-enabled when tlsCert/tlsKey are set.
tlsCert string — Client certificate file path.
tlsKey string — Client private key file path.
tlsCA string — CA certificate file path.
tlsInsecure boolean false Skip certificate verification (testing only).
tlsMinVersion enum 1.2 Minimum TLS version (1.2 or 1.3).
tlsServerName string — SNI server name override.

Timeouts

Param Type Default Description
connectTimeout duration 180s Dial timeout. Accepts Go duration (5s) or bare ms (5000).
connectionRequestTimeout duration 180s Pool-wait timeout (Helix takes the max of this and connectTimeout since stdlib doesn't separate them).
responseTimeout duration 0 (unbounded) Time to wait for response headers after the request is sent.
soTimeout duration 180s Socket read timeout (post-headers).
timeout duration 30s Overall request deadline (Helix-specific). Set 0 to disable. Suppressed automatically when the response is promoted to a StreamBody.

Control headers

Header Purpose
HelixHttpMethod Per-request method override (unless skipControlHeaders=true).
HelixHttpPath Append to the endpoint path.
HelixHttpQuery Append (URL-encoded) query string.
HelixHttpRawQuery Append raw query string (no encoding).
HelixHttpUri Replace the target URL entirely (unless bridgeEndpoint=true).
HelixHttpResponseCode HTTP status code on the response.
HelixHttpResponseText HTTP reason phrase on the response.
HelixHttpProtocolVersion HTTP protocol version of the response (e.g. HTTP/1.1).

Body shape

Request: the In body is sent as the request body.

  • []byte → sent verbatim.
  • string → sent verbatim; Content-Type auto-set to text/plain; charset=UTF-8 when contentTypeCharsetEnabled=true.
  • io.Reader → streamed with chunked transfer encoding.
  • Anything else → fmt.Sprintf("%v", body).

Response: the body lands on ex.In():

  • Buffered as []byte when smaller than responsePayloadStreamingThreshold.
  • Promoted to a StreamBody above the threshold (or always when disableStreamCache=true / responsePayloadStreamingThreshold=-1).
  • Dropped when ignoreResponseBody=true.

Errors

Code When
HTTP:CONNECTIVITY Transport-level failure (dial, DNS, TLS, OAuth2 token fetch).
HTTP:BAD_REQUEST (and friends) Status code outside okStatusCodeRange (and throwExceptionOnFailure=true). The error wraps a body preview for downstream classification.

See error handling for the typed error matching pattern.

Examples

GET with a custom UA and timeout

- to: http://api.example.com/v1/users?userAgent=helix/1.0&timeout=5s

POST multipart upload

- to: http://api.example.com/files
  params:
    httpMethod: POST
    multipartUpload: "true"
    multipartUploadName: "file"

OAuth2 client-credentials with caching

- to: http://api.example.com/v1/things
  params:
    oauth2ClientId: "my-id"
    oauth2ClientSecret: "my-secret"
    oauth2TokenEndpoint: "https://issuer.example.com/token"
    oauth2Scope: "read:things"
    oauth2CacheTokens: "true"

Custom success codes (don't throw on 302)

- to: http://example.com/redirector?okStatusCodeRange=200-204,302

Proxy with bypass

- to: http://internal.local/data
  params:
    proxyHost: "proxy.corp.example"
    proxyPort: "3128"
    nonProxyHosts: ".local,127.0.0.1,localhost"

See also