saluki_app/
api.rs

1//! API server.
2
3use std::{convert::Infallible, error::Error, future::Future};
4
5use axum::Router;
6use http::{Request, Response};
7use rcgen::{generate_simple_self_signed, CertifiedKey};
8use rustls::{pki_types::PrivateKeyDer, ServerConfig};
9use rustls_pki_types::PrivatePkcs8KeyDer;
10use saluki_api::APIHandler;
11use saluki_error::GenericError;
12use saluki_io::net::{
13    listener::ConnectionOrientedListener,
14    server::{http::HttpServer, multiplex_service::MultiplexService},
15    util::hyper::TowerToHyperService,
16    ListenAddress,
17};
18use tokio::select;
19use tonic::{body::Body, server::NamedService, service::RoutesBuilder};
20use tower::Service;
21
22/// An API builder.
23///
24/// `APIBuilder` provides a simple and ergonomic builder pattern for constructing an API server from multiple handlers.
25/// This allows composing portions of an API from individual building blocks.
26///
27/// ## Missing
28///
29/// - TLS support
30/// - API-wide authentication support (can be added at the per-handler level)
31/// - graceful shutdown (shutdown stops new connections, but does not wait for existing connections to close)
32#[derive(Default)]
33pub struct APIBuilder {
34    http_router: Router,
35    grpc_router: RoutesBuilder,
36    tls_config: Option<ServerConfig>,
37}
38
39impl APIBuilder {
40    /// Create a new `APIBuilder` with an empty router.
41    ///
42    /// A fallback route will be provided that returns a 404 Not Found response for any route that isn't explicitly handled.
43    pub fn new() -> Self {
44        Self {
45            http_router: Router::new(),
46            grpc_router: RoutesBuilder::default(),
47            tls_config: None,
48        }
49    }
50
51    /// Adds the given handler to this builder.
52    ///
53    /// The initial state and routes provided by the handler will be merged into this builder.
54    pub fn with_handler<H>(mut self, handler: H) -> Self
55    where
56        H: APIHandler,
57    {
58        let handler_router = handler.generate_routes();
59        let handler_state = handler.generate_initial_state();
60        self.http_router = self.http_router.merge(handler_router.with_state(handler_state));
61
62        self
63    }
64
65    /// Adds the given optional handler to this builder.
66    ///
67    /// If the handler is `Some`, the initial state and routes provided by the handler will be merged into this builder.
68    /// Otherwise, this builder will be returned unchanged.
69    pub fn with_optional_handler<H>(self, handler: Option<H>) -> Self
70    where
71        H: APIHandler,
72    {
73        if let Some(handler) = handler {
74            self.with_handler(handler)
75        } else {
76            self
77        }
78    }
79
80    /// Add the given gRPC service to this builder.
81    pub fn with_grpc_service<S>(mut self, svc: S) -> Self
82    where
83        S: Service<Request<Body>, Response = Response<Body>, Error = Infallible>
84            + NamedService
85            + Clone
86            + Send
87            + Sync
88            + 'static,
89        S::Future: Send + 'static,
90        S::Error: Into<Box<dyn Error + Send + Sync>> + Send,
91    {
92        self.grpc_router.add_service(svc);
93        self
94    }
95
96    /// Sets the TLS configuration for the server.
97    ///
98    /// This will enable TLS for the server, and the server will only accept connections that are encrypted with TLS.
99    ///
100    /// Defaults to TLS being disabled.
101    pub fn with_tls_config(mut self, config: ServerConfig) -> Self {
102        self.tls_config = Some(config);
103        self
104    }
105
106    /// Sets the TLS configuration for the server based on a dynamically generated self-signed certificate.
107    ///
108    /// This will enable TLS for the server, and the server will only accept connections that are encrypted with TLS.
109    pub fn with_self_signed_tls(self) -> Self {
110        let CertifiedKey { cert, key_pair } = generate_simple_self_signed(["localhost".to_owned()]).unwrap();
111        let cert_chain = vec![cert.der().clone()];
112        let key = PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key_pair.serialize_der()));
113
114        let config = ServerConfig::builder()
115            .with_no_client_auth()
116            .with_single_cert(cert_chain, key)
117            .unwrap();
118
119        self.with_tls_config(config)
120    }
121
122    /// Serves the API on the given listen address until `shutdown` resolves.
123    ///
124    /// The listen address must be a connection-oriented address (TCP or Unix domain socket in SOCK_STREAM mode).
125    ///
126    /// # Errors
127    ///
128    /// If the given listen address is not connection-oriented, or if the server fails to bind to the address, or if
129    /// there is an error while accepting for new connections, an error will be returned.
130    pub async fn serve<F>(self, listen_address: ListenAddress, shutdown: F) -> Result<(), GenericError>
131    where
132        F: Future<Output = ()> + Send + 'static,
133    {
134        let listener = ConnectionOrientedListener::from_listen_address(listen_address).await?;
135
136        // Wrap up our HTTP and gRPC routers in a multiplexed service, allowing us to handle both types of requests on
137        // the same port. Additionally, we have to wrap the service to translate from `tower::Service` to `hyper::Service`.
138        let multiplexed_service = TowerToHyperService::new(MultiplexService::new(
139            self.http_router,
140            self.grpc_router.routes().into_axum_router(),
141        ));
142
143        // Create and spawn the HTTP server.
144        let mut http_server = HttpServer::from_listener(listener, multiplexed_service);
145        if let Some(tls_config) = self.tls_config {
146            http_server = http_server.with_tls_config(tls_config);
147        }
148        let (shutdown_handle, error_handle) = http_server.listen();
149
150        // Wait for our shutdown signal, which we'll forward to the listener to stop accepting new connections... or
151        // capture any errors thrown by the listener itself.
152        select! {
153            _ = shutdown =>  shutdown_handle.shutdown(),
154            maybe_err = error_handle => if let Some(e) = maybe_err {
155                return Err(GenericError::from(e))
156            },
157        }
158
159        Ok(())
160    }
161}
saluki_app/api.rs

saluki_app/
api.rs
