Crate junction_api

The Junction configuration API. This crate allows you to build configuration for a dynamic HTTP client and export it to a control plane or pass it directly to an in-process client. Junction configuration is expressable as plain Rust strucs, and can be serialized/deserialized with a serde compatible library.

All of the configuration here should be correct by construction - if you can create a struct, it’s valid Junction configuration. Different representations of the same configuration are possible, and clients and control planes may normalize your configuration differently, so when writing tests for your configuration be aware that it may be normalized while converting between different formats or data sources.

Core Concepts

Targets

The Junction API is built around the idea of a traffic Target, a a unique identifier for a place to send traffic. Targets are logical; a Kubernetes Service target represents the entire service, running anywhere in a multi-cluster deployment, not an individual Pod or Node or Service object.

Routes

An HTTP Route is the client facing half of Junction, and contains most of the things you’d traditionally find in a hand-rolled HTTP client - timeouts, retries, URL rewriting and more. The http module’s documentation goes into detail on how and why to configure a Route.

Backends

A Backend is the Service oriented half of Junction configuration. Backends configuration gives you control over the things you’d normally configure in a reverse proxy or a traditional load balancer, like load balancing. See the backend module’s documentation for more detail.

Crate Feature Flags

The following feature flags are available:

• The kube feature includes conversions from Junction configuration to and from Kubernetes objects. This feature depends on the kube and k8s-openapi crates. See the kube module docs for more detail.

• The xds feature includes conversions from Junction configuration to and from xDS types. This feature depends on the [xds-api][xds_api] crate.

Modules

• backend
  Backends are the logical target of network traffic. They have an identity and a load-balancing policy. See Backend to get started.
• http
  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.
• kube
  Types and re-exports for converting Junction types to Kubernetes objects.

Structs

• BackendId
  A target and port together uniquely represent a Backend.
• Dns
  A DNS name to target with traffic.
• Duration
  A wrapper around std::time::Duration that serializes to and from a f64 number of seconds.
• Error
  An error converting a Junction API type into another type.
• Fraction
  A fraction, expressed as a numerator and a denominator.
• Hostname
  AN RFC 1123 DNS domain name.
• KubeService
  A Kubernetes Service to target with traffic.
• Name
  An RFC 1035 compatible name. This name must be useable as a component of a DNS subdomain - it must start with a lowercase ascii alphabetic character and may only consist of ascii lowercase alphanumeric characters and the - character.
• Regex
  A regular expression.
• VirtualHost
  A virtual hostname. VirtualHosts represent the primary layer of indirection in Junction. Traffic sent to a VirtualHost is routed to an appropriate backend based on the content of the request.

Enums

• Target
  A traffic target. Traffic targets are abstract, uniquely identifiable places to route traffic, like a DNS name or a Kubernetes Service.