Struct ProxyService 

pub struct ProxyService<U> { /* private fields */ }

The proxy as a tower service, built by ProxyServer::service.

A request with a gRPC or gRPC-Web content type goes to the upstream as it arrived, so one listener carries REST and native gRPC. gRPC-Web is the upstream’s to translate (tonic-web’s GrpcWebLayer around its services), or the proxy’s with grpc_web.translate for an upstream that speaks only gRPC. A gRPC-Web answer gets the proxy’s CORS policy (cors.grpc_web), since the proxy answers the browser’s preflight for it. Every other request goes to the proxy’s routes (transcoded RPCs, health, metrics, OpenAPI, OIDC, forward-auth, extra routes) behind the proxy’s middleware. A request no route matches is answered 404, or handed to the service set with with_fallback. Native gRPC and the fallback pass only the guards whose scope names them (grpc, fallback); a guard’s rejection of a gRPC call is a gRPC status.

Serve it with serve or serve_with (TLS, a connection limit), or hand it to any server that takes a tower service of http types: a Unix socket, an existing hyper or axum server. Native gRPC needs HTTP/2 on that server (ALPN h2 next to http/1.1 behind TLS). Such a server tells the proxy which connection a request came on with for_connection.

Examples

use structured_proxy::ProxyServer;

// The embedder's own tonic services, called in process.
let grpc = tonic::service::Routes::default();
let service = ProxyServer::from_yaml_str("service:\n  name: demo\n")?.service(grpc)?;

Implementations

impl<U: Upstream> ProxyService<U>

pub fn with_fallback<F>(self, fallback: F) -> Self

where F: Service<Request, Error = Infallible> + Clone + Send + Sync + 'static, F::Response: IntoResponse, F::Future: Send + 'static,

Hand the requests no route matches to fallback instead of answering 404: an embedder’s own REST routes, a static site, anything that is a tower service. Only the guards whose scope names fallback traffic see them; CORS and tracing are the fallback’s own.

A URL whose path a transcoded template’s route matches, but which no binding answers (its field template or custom verb does not fit), is the fallback’s too. A request whose path a route answers but not with its method stays with the proxy (405), as do every gRPC request and every browser preflight for a gRPC-Web call, which follows the call it announces.

pub fn for_connection(&self, connection: impl Into<ConnectionInfo>) -> Self

This service for the requests of one connection: the proxy’s middleware sees its client’s address (rate limits by IP, the auth decider), and a tonic upstream in process reads it with Request::remote_addr, and its TLS client certificates with Request::peer_certs, for native and transcoded calls alike.

A server of your own calls it once per accepted connection, with what tonic’s Connected trait reports for the stream. serve_with does this itself.

Examples

use structured_proxy::ProxyServer;
use tonic::transport::server::Connected;

let proxy = ProxyServer::from_yaml_str("service:\n  name: demo\n")?
    .service(tonic::service::Routes::default())?;
let listener = tokio::net::TcpListener::bind("0.0.0.0:8443").await?;
let (tcp, _) = listener.accept().await?;
// After a TLS handshake, the `TlsStream` reports the client's certificates too.
let service = proxy.for_connection(tcp.connect_info());

Without it, a request’s peer comes from the ConnectInfo an outer axum server recorded, when there is one.

Trait Implementations

impl<U: Clone> Clone for ProxyService<U>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<U> Debug for ProxyService<U>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<U, B> Service<Request<B>> for ProxyService<U>

where U: Upstream, B: Body<Data = Bytes> + Send + 'static, B::Error: Into<BoxError>,

type Response = Response<Body>

Responses given by the service.

type Error = !

Errors produced by the service.

type Future = ResponseFuture<U>

The future response value.

fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, request: Request<B>) -> Self::Future

Process the request and return the response asynchronously.