---
source: apollo-http/crates/apollo-http-client/src/lib.rs
expression: "apollo_configuration::export_json_schema::<HttpClientConfig>()"
---
{
"$defs": {
"ClientAuthentication": {
"additionalProperties": false,
"description": "Client identity used for mutual TLS authentication.\n\nThe certificate is offered to servers during the TLS handshake; servers\nthat do not require client authentication ignore it. Encrypted private\nkeys are not supported.",
"properties": {
"certificate_chain": {
"description": "PEM-encoded client certificate followed by any intermediate\ncertificates needed to complete the chain to a CA the server trusts.\n\nTypically loaded from disk with `${file:./certs/client.pem}`.",
"type": "string"
},
"key": {
"description": "PEM-encoded unencrypted private key matching the leaf certificate in\n`certificate_chain`. PKCS#1, PKCS#8, and SEC1 formats are accepted.\n\nTypically loaded from disk with `${file:./certs/client.key}`.",
"type": "string"
}
},
"required": [
"certificate_chain",
"key"
],
"type": "object"
},
"Duration": {
"type": "string"
},
"HeaderName": {
"type": "string"
},
"Http1Config": {
"additionalProperties": false,
"description": "HTTP/1.1 connection pool settings.\n\nThese apply when `protocol` is `http1`, and to HTTP/1.1 connections\nnegotiated under `protocol: alpn`. They have no effect when `protocol`\nis `http2` — HTTP/2 uses a single persistent connection per host.",
"properties": {
"pool_idle_timeout": {
"$ref": "#/$defs/Duration",
"default": "1m 30s",
"description": "How long idle connections are kept alive before being closed."
},
"pool_max_idle_per_host": {
"default": 10,
"description": "Maximum idle connections kept open per host.",
"format": "uint",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"Http2Config": {
"additionalProperties": false,
"description": "HTTP/2 connection settings.\n\nThese apply when `protocol` is `http2`, and to HTTP/2 connections\nnegotiated under `protocol: alpn`.",
"properties": {
"connection_idle_timeout": {
"$ref": "#/$defs/Duration",
"default": "5m",
"description": "How long an idle HTTP/2 connection is kept before being closed. The\nconnection is considered idle when no requests are in flight."
},
"keep_alive_interval": {
"$ref": "#/$defs/Duration",
"default": "30s",
"description": "Interval at which HTTP/2 PING frames are sent to detect dead\nconnections and prevent proxies from closing idle connections."
},
"keep_alive_timeout": {
"$ref": "#/$defs/Duration",
"default": "20s",
"description": "How long to wait for a PING acknowledgement before closing the\nconnection."
},
"keep_alive_while_idle": {
"default": true,
"description": "Whether to send keep-alive pings when there are no active streams.",
"type": "boolean"
}
},
"type": "object"
},
"MetricsConfig": {
"additionalProperties": false,
"description": "Metrics opt-in settings.\n\nControls which optional OTel HTTP client metrics are recorded and which opt-in attributes\nare included. All are disabled by default, as required by the OTel HTTP semantic conventions.",
"properties": {
"request_body_size": {
"default": false,
"description": "Enable recording of `http.client.request.body.size`.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"response_body_size": {
"default": false,
"description": "Enable recording of `http.client.response.body.size`.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"url_scheme": {
"default": false,
"description": "Include the `url.scheme` attribute on all HTTP client metrics.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
}
},
"type": "object"
},
"Protocol": {
"description": "HTTP protocol version to use for connections.",
"oneOf": [
{
"const": "http1",
"description": "HTTP/1.1 only (default).",
"type": "string"
},
{
"const": "http2",
"description": "HTTP/2 only.\n\nOver HTTPS, ALPN is configured automatically — the server selects HTTP/2 during\nthe TLS handshake if it supports it. Over plain HTTP and `unix://`, prior-knowledge\nHTTP/2 is used: the client speaks HTTP/2 directly without an Upgrade round trip.\nUse this only when you know the server supports HTTP/2 on that transport.",
"type": "string"
},
{
"const": "alpn",
"description": "Negotiate HTTP/1.1 or HTTP/2 automatically.\n\nOver HTTPS, ALPN is used: the server selects HTTP/1.1 or HTTP/2 during the TLS\nhandshake. Over plain HTTP and `unix://`, there is no TLS handshake, so ALPN\ncannot negotiate a protocol and the connection always falls back to HTTP/1.1 —\nuse `http2` explicitly for prior-knowledge HTTP/2 on those transports.",
"type": "string"
}
]
},
"ProxyConfig": {
"additionalProperties": false,
"description": "Proxy server configuration.\n\nRoutes outbound `http://` and `https://` requests through a proxy server.\n`unix://` requests bypass the proxy and reach the socket directly.\n\n```yaml\nproxy:\n url: \"http://user:${PROXY_PASSWORD}@proxy.corp.example.com:3128\"\n```",
"properties": {
"url": {
"$ref": "#/$defs/Url",
"description": "Proxy server URL.\n\nSupports Basic authentication via embedded credentials:\n`http://user:password@proxy.corp.example.com:3128`\n\nUse env-var expansion to avoid hardcoding addresses or credentials:\n`url: \"${EGRESS_PROXY_URL}\"`"
}
},
"required": [
"url"
],
"type": "object"
},
"SpansConfig": {
"additionalProperties": false,
"description": "Spans opt-in settings.",
"properties": {
"network_local_address": {
"default": null,
"description": "Static `network.local.address` span attribute: the outbound IP address of this service\n(e.g. `\"192.168.1.10\"`). Opt-In per the OTel HTTP semantic conventions.",
"type": [
"string",
"null"
]
},
"network_local_port": {
"default": null,
"description": "Static `network.local.port` span attribute: the source port this service binds to, if fixed.\nOpt-In per the OTel HTTP semantic conventions.",
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"type": [
"integer",
"null"
]
},
"network_transport": {
"default": false,
"description": "Capture `network.transport` as a span attribute. Always `\"tcp\"` for HTTP/1.1 and HTTP/2.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"request_body_size": {
"default": false,
"description": "Capture `http.request.body.size` as a span attribute (actual bytes sent).\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"request_headers": {
"default": [],
"description": "HTTP request header names to capture as span attributes (case-insensitive).\n\nEach header `x-foo` becomes `http.request.header.x-foo` with a string-array value.\nOpt-In per the OTel HTTP semantic conventions.",
"items": {
"$ref": "#/$defs/HeaderName"
},
"type": "array"
},
"response_body_size": {
"default": false,
"description": "Capture `http.response.body.size` as a span attribute (actual bytes received).\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"response_headers": {
"default": [],
"description": "HTTP response header names to capture as span attributes (case-insensitive).\n\nEach header `x-foo` becomes `http.response.header.x-foo` with a string-array value.\nOpt-In per the OTel HTTP semantic conventions.",
"items": {
"$ref": "#/$defs/HeaderName"
},
"type": "array"
},
"url_scheme": {
"default": false,
"description": "Capture `url.scheme` as a span attribute.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
},
"user_agent": {
"default": false,
"description": "Capture `user_agent.original` from the outgoing `User-Agent` request header.\n\nOpt-In per the OTel HTTP semantic conventions.",
"type": "boolean"
}
},
"type": "object"
},
"TcpConfig": {
"additionalProperties": false,
"description": "TCP socket settings applied to every outbound connection.\n\nThese apply regardless of HTTP protocol version (HTTP/1.1, HTTP/2, or\nnegotiated under `protocol: alpn`).",
"properties": {
"keepalive": {
"$ref": "#/$defs/Duration",
"default": "1m",
"description": "Idle period before the OS starts sending TCP keep-alive probes.\n\nDefaults to 60 s. Probes detect dead connections before a new request\nis dispatched on them and prevent intermediate proxies (load balancers,\nNATs) from silently dropping long-lived idle connections."
},
"nodelay": {
"default": true,
"description": "Whether to disable Nagle's algorithm (`TCP_NODELAY`).\n\nWhen `true` (default), small payloads are sent immediately, reducing\ntail latency on small request/response bodies. Set to `false` to enable\nNagle's algorithm, in which the kernel may briefly buffer small writes\nto coalesce them into fewer segments.",
"type": "boolean"
}
},
"type": "object"
},
"TelemetryConfig": {
"additionalProperties": false,
"description": "Telemetry settings.",
"properties": {
"metrics": {
"$ref": "#/$defs/MetricsConfig",
"description": "Metrics opt-in settings."
},
"spans": {
"$ref": "#/$defs/SpansConfig",
"description": "Spans opt-in settings."
}
},
"type": "object"
},
"TlsConfig": {
"additionalProperties": false,
"description": "TLS settings for outbound connections.",
"properties": {
"certificate_authorities": {
"description": "PEM-encoded CA certificate bundle to trust. Multiple certificates may\nbe concatenated in a single PEM blob. When `use_native_certificate_store`\nis also enabled (the default), these CAs are added to the OS native\nstore; set `use_native_certificate_store: false` to trust only the\nsupplied bundle.\n\nTypically loaded from disk with `${file:./certs/ca.pem}`.",
"type": [
"string",
"null"
]
},
"client_authentication": {
"anyOf": [
{
"$ref": "#/$defs/ClientAuthentication"
},
{
"type": "null"
}
],
"description": "Client certificate and key to present during mutual TLS handshakes.\nOmit to disable client authentication."
},
"danger_accept_invalid_certs": {
"default": false,
"description": "Skip TLS certificate verification. **Never use in production.** When\nenabled, the client accepts any certificate regardless of issuer or\nvalidity, making all outbound HTTPS connections vulnerable to\nmachine-in-the-middle interception.",
"type": "boolean"
},
"use_native_certificate_store": {
"default": true,
"description": "Whether the OS native certificate store is trusted. When `true` (the\ndefault), any CAs supplied via `certificate_authorities` are layered\non top. Set to `false` to trust only the supplied bundle — useful in\nair-gapped environments.",
"type": "boolean"
}
},
"type": "object"
},
"Url": {
"format": "uri",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "HTTP client configuration.\n\nControls the protocol, connection pool, timeouts, and opt-in OTel telemetry.",
"properties": {
"connect_timeout": {
"$ref": "#/$defs/Duration",
"default": "10s",
"description": "Connection timeout covering both the TCP dial and TLS handshake."
},
"http1": {
"$ref": "#/$defs/Http1Config",
"description": "HTTP/1.1 connection pool settings."
},
"http2": {
"$ref": "#/$defs/Http2Config",
"description": "HTTP/2 connection settings."
},
"protocol": {
"$ref": "#/$defs/Protocol",
"description": "HTTP protocol version to use."
},
"proxy": {
"anyOf": [
{
"$ref": "#/$defs/ProxyConfig"
},
{
"type": "null"
}
],
"description": "Proxy server configuration. When set, outbound `http://` and `https://`\nrequests are routed through the specified proxy; `unix://` requests\nalways reach the socket directly.\n\nWhen absent (the default), TCP connections are made directly to the target."
},
"tcp": {
"$ref": "#/$defs/TcpConfig",
"description": "TCP socket settings applied to every outbound connection."
},
"telemetry": {
"$ref": "#/$defs/TelemetryConfig",
"description": "Telemetry opt-in settings."
},
"tls": {
"$ref": "#/$defs/TlsConfig",
"description": "TLS settings for outbound connections."
}
},
"title": "HttpClientConfig",
"type": "object"
}