Module junction_api::http
source · Expand description
HTTP Route configuration. Routes dynamically congfigure things you might put directly in client code like timeouts and retries, failure detection, or picking a different backend based on request data.
§Routes and URLs
Routes are uniquely identified by a VirtualHost, which is the combination of a Target and an optional port. Every VirtualHost has a DNS hostname and port. When making an HTTP request a Route is selected by using the hostname and port the request URL as the name of a VirtualHost and finding a matching route.
Once a Route has been selected, each rule is applied to an entire request to find an appropriate match. See the next section for a high-level description of matching, and the documentation of matches and RouteMatch for more detail.
§Route Rules
A Route contains zero or more rules that describe how to
match a request. Each rule is made of up a set of
matches, a set of backends to
send the request to once a match has been found, and policy on how to handle
retries and failures. For example, the following Route uses a Kubernetes
Service as a VirtualHost, matches all traffic to it, and splits it evenly
between a DNS and a Service backend, while applying a simple retry policy:
// an example route
let route = Route {
vhost: Target::kube_service("prod", "example-svc").unwrap().into_vhost(None),
tags: Default::default(),
rules: vec![
RouteRule {
retry: Some(RouteRetry {
codes: vec![500, 503],
attempts: Some(3),
backoff: Some(Duration::from_millis(500)),
}),
backends: vec![
WeightedBackend {
weight: 1,
backend: Target::dns("prod.old-thing.internal")
.unwrap()
.into_backend(1234),
},
WeightedBackend {
weight: 1,
backend: Target::kube_service("prod", "new-thing")
.unwrap()
.into_backend(8891),
},
],
..Default::default()
}
],
};See the RouteRule documentation for all of your configuration options, and RouteMatch for different ways to match an incoming request.
§Matching
A RouteRules is applied to an outgoing request if any of it’s
matches matches a request. For example, a rule with
the following matches:
let matches = vec![
RouteMatch {
path: Some(PathMatch::Exact { value: "/foo".to_string() }),
headers: vec![
HeaderMatch::Exact { name: "version".to_string(), value: "v2".to_string() },
],
..Default::default()
},
RouteMatch {
path: Some(PathMatch::Prefix { value: "/v2/foo".to_string() }),
..Default::default()
},
];would match a request with path /v2/foo OR a request with path /foo and
the version: v2 header set. Any request to /foo without that header set
would not match.
§Passthrough Routes
A RouteRule with no backends is called a “passthrough rule”. Instead of dead-ending traffic, it uses the Route’s VirtualHost as a traffic target, convering it into a BackendId on the fly, using the port of the incoming request if the VirtualHost has no port specified. (see VirtualHost::into_backend).
For example, given the following route will apply a retry policy to all
requests to http://example.internal and use the request port to find
a backend.
let route = Route {
vhost: Target::dns("example.internal").unwrap().into_vhost(None),
tags: Default::default(),
rules: vec![
RouteRule {
retry: Some(RouteRetry {
codes: vec![500, 503],
attempts: Some(3),
..Default::default()
}),
..Default::default()
}
],
};A request to http://example.internal:8801 would get sent to a
backend with the port 8801 and a request to
http://example.internal:443 would get sent to a backend with port :443.
A route with no rules is a more general case of a passthrough route; it’s equivalent to specifying a single RouteRule with no backends that always matches.
Structs§
- Defines configuration for the RequestHeaderModifier filter.
- Defines configuration for the RequestMirror filter.
- Defines a filter that redirects a request. This filter MUST not be used on the same Route rule as a URL Rewrite filter.
- A Route is a policy that describes how a request to a specific virtual host should be routed.
- Defines the predicate used to match requests to a given action. Multiple match types are ANDed together; the match will evaluate to true only if all conditions are satisfied. For example, if a match specifies a
pathmatch and twoquery_paramsmatches, it will match only if the request’s path matches and both of thequery_paramsare matches. - Configure client retry policy.
- A RouteRule contains a set of matches that define which requests it applies to, processing rules, and the final destination(s) for matching traffic.
- Defines timeouts that can be configured for a HTTP Route.
- Defines a filter that modifies a request during forwarding. At most one of these filters may be used on a Route rule. This may not be used on the same Route rule as a RequestRedirect filter.
- The combination of a backend and a weight.
Enums§
- Describes how to select a HTTP route by matching HTTP request headers.
- Describes how to select a HTTP route by matching the HTTP request path. The
typeof a match specifies how HTTP paths should be compared. - Defines configuration for path modifiers.
- Describes how to select a HTTP route by matching HTTP query parameters.
- Defines processing steps that must be completed during the request or response lifecycle.
Type Aliases§
- The name of an HTTP header.