[−][src]Crate conjure_runtime
An HTTP client for use with Conjure servers.
This crate provides both asynchronous and blocking clients. The clients can either be used in Conjure-generated wrapper types or standalone for use with non-Conjure servers.
Configuration
While a conjure_runtime
client's configuration can be built up programmatically, the more common approach is for
the configuration to be deserialized from a service's runtime-reloadable configuration file. The ServicesConfig
supports configuration for multiple downstream services, as well as allowing for both global and per-service
configuration overrides:
services:
auth-service:
uris:
- https://auth.my-network.com/auth-service
cache-service:
uris:
- https://cache-1.my-network.com/cache-service
- https://cache-2.my-network.com/cache-service
request-timeout: 10s
# options set at this level will apply as defaults to all configured services
security:
ca-file: var/security/ca.pem
Once a client is constructed, its configuration can be dynamically reloaded by calling RefreshHandle::refresh
on a handle obtained via Client::refresh_handle
. Note that the refresh process will throw away the client's
TLS session cache and HTTP connection pool, so it should not be called needlessly often.
Usage
First construct a raw conjure_runtime::Client
:
use conjure_runtime::{UserAgent, Agent, HostMetricsRegistry, Client}; use conjure_runtime::config::{ServiceConfig, SecurityConfig}; use std::path::PathBuf; use std::sync::Arc; use witchcraft_metrics::MetricRegistry; let user_agent = UserAgent::new(Agent::new("my-user-agent", "1.0.0")); let host_metrics = Arc::new(HostMetricsRegistry::new()); let metrics = Arc::new(MetricRegistry::new()); let config = ServiceConfig::builder() .uris(vec!["https://url-to-server:1234/test-service".parse().unwrap()]) .security( SecurityConfig::builder() .ca_file(Some(PathBuf::from("path/to/ca_file.pem"))) .build(), ) .build(); let client = Client::new( "test-service", user_agent, &host_metrics, &metrics, &config, )?;
The client can then be used with Conjure-generated service interfaces:
use conjure_codegen::example_types::another::TestServiceAsyncClient; use conjure_object::BearerToken; let client = TestServiceAsyncClient::new(client); let auth = BearerToken::new("my_auth_token").unwrap(); let file_systems = client.get_file_systems(&auth).await?;
Or manually if a service does not provide a Conjure API:
let response = client.delete("/widgets/{widgetId}") .param("widgetId", 12345) .send() .await?;
The blocking::Client
's API is identical, with the exception that you don't .await
on methods:
use conjure_codegen::example_types::another::TestServiceClient; use conjure_object::BearerToken; let client = TestServiceClient::new(client); let auth = BearerToken::new("my_auth_token").unwrap(); let file_systems = client.get_file_systems(&auth)?;
let response = client.delete("/widgets/{widgetId}") .param("widgetId", 12345) .send()?;
Behavior
conjure_runtime
wraps the hyper
HTTP library with opinionated behavior designed to more effectively communicate
between services in a distributed system. It is broadly designed to align with the conjure-java-runtime
Java
library, though it does differ in various ways.
Error Propagation
Servers should use the standard Conjure error format to propagate application-specific errors to callers. Non-QoS
(see below) errors received from the server are treated as fatal. By default, conjure_runtime
will return a
conjure_error::Error
that will generate a generic 500 Internal Server Error response. Its cause will be a
RemoteError
object that contains the serialized Conjure error information sent by the server. The
Client::set_propagate_service_errors
method can be used to change that behavior to instead transparently propagate
the error received from the server. Rather than producing a generic 500 response, the returned
conjure_error::Error
will produce the same response the client received from the server.
Call Tracing
The client propagates trace information via the zipkin
crate using the traditional X-B3-*
HTTP headers. It
also creates local spans covering various stages of request processing:
conjure-runtime: get /widget-service/{widgetId}
- The name of this span is built from the request's method and path pattern.conjure-runtime: attempt 1
conjure-runtime: wait-for-headers
- This span is sent to the server, and lasts until the server sends the headers of the response.conjure-runtime: wait-for-body
- This span is tracked along with the response body, and lasts until theResponseBody
object is dropped. It is "detached" from the zipkin tracer so new spans created outside ofconjure-runtime
will not be parented to it, and can outlive the parentconjure-runtime
spans. It will not be created if an IO error occurs before headers are received.
conjure-runtime: backoff-with-jitter
- If the request encounters an IO error before receiving headers, this span covers the time spent waiting before the request is retried.conjure-runtime: attempt 2
- ...
Quality of Service: Retry, Failover, Throttling, and Backpressure
The client treats certain HTTP errors specially. Servers can advertise an overloaded state via the 429 Too Many
Requests or 503 Service Unavailable status codes. Unlike other 4xx and 5xx status codes, these responses do not
cause the request to fail. Instead, conjure_runtime
will throttle itself and retry the request. Requests are
retried a fixed number of times, with an exponentially growing backoff in between attempts. If a 429 response
contains a Retry-After
header, its backoff will be used rather than the default. IO errors also trigger a retry.
A 503 response or IO error will also cause that host to be temporarily "blacklisted" so it will not be used by other requests unless there is no other option.
Only some requests can be retried. By default, conjure_runtime
will only retry requests with HTTP methods
identified as idempotent - GET
, PUT
, DELETE
, HEAD
, TRACE
, and OPTIONS
. Non-idempotent requests cannot be
safely retried to avoid the risk of unexpected behavior if the request ends up being applied twice. The
Client::set_assume_idempotent
method can be used to override this behavior and have the client assume all requests
are idempotent. In addition, requests with streaming request bodies can only be retried if the body had either not
started to be written when the error occurred or if it was successfully reset for another attempt.
Metrics
Clients record metrics to both a standard MetricsRegistry
and a conjure_runtime
-specific HostMetricsRegistry
.
Standard Metrics
client.request (service: <service_name>)
- ATimer
recording request durations, tagged by service. Note that the requests timed by this metric are the individual raw HTTP request attempts, notconjure_runtime
-level requests with retries/backoffs/etc. It only records the time until response headers are received, not until the entire response body is read.client.request.error (service: <service_name>, reason: IOException)
- AMeter
tracking the rate of IO errors, tagged by service. Like theclient.request
metric, this tracks the raw HTTP requests. Thereason
tag has a value ofIOException
to align withconjure-java-runtime
's metric.
Host Metrics
The HostMetricsRegistry
contains metrics for every host of every service being actively used by a
conjure_runtime
client.
Modules
blocking | A blocking version of the client. |
config | Client configuration. |
errors | Error types. |
Structs
Agent | A component of a |
BodyWriter | The asynchronous writer passed to |
BytesBody | A simple type implementing |
Client | An asynchronous HTTP client to a remote service. |
HostMetrics | Metrics about requests made to a specific host of a service. |
HostMetricsRegistry | A collection of metrics about requests to service hosts. |
Hosts | A snapshot of the nodes in a registry. |
HostsIter | An iterator over host metrics. |
RefreshHandle | A handle used to update the configuration of a |
RequestBuilder | A builder for an asynchronous HTTP request. |
Response | An asynchronous HTTP response. |
ResponseBody | An asynchronous streaming response body. |
UserAgent | A representation of an HTTP |
Traits
Body | A request body. |