HTTP client for Apollo platform services.

[HttpClient] is a Tower Service: HTTP/1.1 and HTTP/2 over TCP and Unix domain sockets. Configure via [HttpClientConfig].

Example

use apollo_http_client::{HttpClient, HttpClientConfig};
use http_body_util::Full;
use bytes::Bytes;
use tower::ServiceExt;

# #[tokio::main]
# async fn main() {
let client = HttpClient::new(&HttpClientConfig::default()).expect("valid config");

let req = http::Request::builder()
    .method("POST")
    .uri("https://api.example.com/")
    .body(Full::new(Bytes::from_static(b"payload")))
    .unwrap();

let _resp = client.oneshot(req).await.expect("request ok");
# }

Protocol selection

HTTP/1.1 is the default. Set protocol: http2 when the server requires HTTP/2, such as gRPC endpoints. Set protocol: alpn to negotiate the version via the TLS handshake. Plain HTTP and unix:// connections have no TLS and always use HTTP/1.1.

Unlike reqwest, which negotiates HTTP/1.1 or HTTP/2 automatically under HTTPS, this client defaults to HTTP/1.1 and requires an explicit [Protocol] setting for HTTP/2 or negotiation.

TLS

Configure trust anchors and client identity under tls. The example below trusts a private CA bundle in addition to the OS native store and presents a client certificate for mutual TLS:

tls:
  # PEM bundle of CA certificates to trust. Multiple certificates may be
  # concatenated. Loaded from disk via apollo-configuration file expansion.
  certificate_authorities: ${file:./certs/internal-ca.pem}

  # Trust the OS native certificate store in addition to the supplied CAs.
  # Set false to trust only the supplied CAs (air-gapped environments).
  use_native_certificate_store: true

  client_authentication:
    # PEM chain: leaf certificate followed by intermediates.
    certificate_chain: ${file:./certs/client.pem}
    # PEM-encoded unencrypted private key (PKCS#1, PKCS#8, or SEC1).
    # Encrypted keys are not supported.
    key: ${file:./certs/client.key}

Invalid PEM, empty bundles, encrypted keys, and configurations with no trust anchors all fail at [HttpClient::new] with a dedicated [HttpClientError] variant naming the offending field.

To supply a pre-built [rustls::ClientConfig] instead, for example, a FIPS-compliant config or one backed by a custom certificate store, use [HttpClient::builder]:

use std::sync::Arc;
use apollo_http_client::{HttpClient, HttpClientConfig};

# fn main() -> Result<(), apollo_http_client::HttpClientError> {
let tls: Arc<rustls::ClientConfig> = todo!("build your ClientConfig");
let client = HttpClient::builder(HttpClientConfig::default())
    .with_tls_config(tls)
    .build()?;
# Ok(())
# }

Unix domain sockets

On Unix targets, unix:// URIs dispatch over Unix domain sockets. Build the request URI with [unix_uri]:

# #[cfg(not(unix))]
# fn main() {}
# #[cfg(unix)]
# #[tokio::main]
# async fn main() {
use apollo_http_client::{HttpClient, HttpClientConfig, unix_uri};
use http_body_util::Empty;
use bytes::Bytes;
use tower::ServiceExt;

let client = HttpClient::new(&HttpClientConfig::default()).expect("valid config");

let uri = unix_uri("/var/run/app.sock")
    .expect("valid path")
    .path_and_query("/health")
    .build()
    .expect("uri builds");

let req = http::Request::builder().uri(uri).body(Empty::<Bytes>::new()).unwrap();

let _resp = client.oneshot(req).await.expect("request ok");
# }

HttpClientConfig::protocol selects HTTP/1.1 or HTTP/2 over the socket the same way it does over TCP. ALPN has no TLS to negotiate over and falls back to HTTP/1.1. Proxy configuration applies only to TCP.

On non-Unix targets, [HttpClient::new] still builds; sending a unix:// request returns [HttpClientError::UnsupportedScheme].

Metrics

Every request emits the following OpenTelemetry metrics:

For unix:// requests, server.address carries the socket path.

When a proxy is configured, connection-state metrics (http.client.open_connections, http.client.connection.duration) also include network.peer.address and network.peer.port, set to the proxy host and port.

All metrics also include url.scheme when telemetry.metrics.url_scheme is enabled.

Span attributes

Follows the OTel HTTP client span semantic conventions.

Always recorded:

• http.request.method — _OTHER for non-standard methods, with the original verb preserved in http.request.method_original
• url.full
• server.address
• server.port — absent for unix://
• http.response.status_code
• network.protocol.version
• error.type — 4xx/5xx/transport

Opt-in (disabled by default, configure under telemetry.spans):

Not supported: url.template, http.request.size, http.response.size, network.peer.address, network.peer.port, user_agent.synthetic.type.