Skip to main content

loqui_server/
lib.rs

1//! An authenticated, explicitly exposed HTTP front end for a loqui
2//! [`Engine`](loqui::Engine), speaking the OpenAI audio API.
3//!
4//! The defaults are the narrow ones:
5//!
6//! - It listens on a Unix socket in `$XDG_RUNTIME_DIR` (mode 0600, in a
7//!   0700 directory) and accepts only processes running as the same user.
8//!   TCP must be asked for, and network-wide TCP must be asked for twice.
9//!   See [`Listen`].
10//! - Every TCP request needs a bearer token, loopback included. With none
11//!   configured, one is generated and stored with mode 0600. See [`auth`].
12//! - Requests from web pages (anything carrying `Origin`) are refused, TCP
13//!   requests must name an expected `Host`, and there is no CORS.
14//! - Bodies, text length, audio length, queue depth, header arrival and
15//!   request time are all bounded.
16//!
17//! [SECURITY.md](https://github.com/Awakened-Labs/loqui/blob/main/SECURITY.md) describes the exposure model in full, and
18//! [Embedding loqui safely](https://github.com/Awakened-Labs/loqui/blob/main/docs/embedding.md) covers choosing a listener and tokens.
19
20pub mod api;
21pub mod auth;
22mod error;
23pub mod fs;
24pub mod listen;
25pub mod policy;
26mod serve;
27
28use std::future::Future;
29use std::path::PathBuf;
30use std::sync::Arc;
31use std::time::Duration;
32
33pub use listen::{Acknowledgements, Listen};
34
35#[derive(Debug, thiserror::Error)]
36pub enum Error {
37    #[error("{0}")]
38    Config(String),
39    #[error("token: {0}")]
40    Token(String),
41    #[error("{0}")]
42    Io(String),
43    #[error(transparent)]
44    Engine(#[from] loqui::Error),
45}
46
47/// Everything about how the server is exposed.
48#[derive(Debug, Clone, Default)]
49pub struct ServerConfig {
50    pub listen: Listen,
51    pub acknowledgements: Acknowledgements,
52    /// Read tokens from this file (one per line). Otherwise `LOQUI_TOKEN`,
53    /// otherwise a generated token at [`fs::default_token_path`].
54    pub token_file: Option<PathBuf>,
55    /// Require a token on the Unix socket as well.
56    pub require_token_on_unix: bool,
57    /// Extra `Host` names TCP clients may use.
58    pub allowed_hosts: Vec<String>,
59    pub public_health: bool,
60    pub tls_cert: Option<PathBuf>,
61    pub tls_key: Option<PathBuf>,
62    /// Requests allowed to wait per model before 503. Default 8.
63    pub max_queue: Option<usize>,
64    /// Open connections. Default 64.
65    pub max_connections: Option<usize>,
66    /// Per-request deadline. Default 120 s.
67    pub request_timeout: Option<Duration>,
68}
69
70/// A server ready to run: bound, with its tokens resolved.
71pub struct Server {
72    bound: serve::Bound,
73    router: axum::Router,
74    tls: serve::Tls,
75    max_connections: usize,
76    token_source: auth::TokenSource,
77    listen: Listen,
78}
79
80impl Server {
81    /// Validates the exposure, resolves tokens and binds. Fails before
82    /// binding anything if the configuration is unsafe.
83    pub async fn bind(config: ServerConfig, engine: loqui::Engine) -> Result<Self, Error> {
84        let tls_requested = config.tls_cert.is_some() || config.tls_key.is_some();
85        config.listen.check(config.acknowledgements, tls_requested)?;
86        let tls = tls_from(&config)?;
87
88        let env_token = std::env::var("LOQUI_TOKEN").ok().filter(|t| !t.is_empty()).map(zeroize::Zeroizing::new);
89        let generated = fs::default_token_path()
90            .ok_or_else(|| Error::Config("cannot find a config directory for the token; set HOME or pass --token-file".into()))?;
91        let tokens = auth::Tokens::resolve(config.token_file.as_deref(), env_token, &generated)?;
92        let token_source = tokens.source().clone();
93
94        let state = Arc::new(api::AppState {
95            engine,
96            tts_gate: api::Gate::new(config.max_queue.unwrap_or(8)),
97            stt_gate: api::Gate::new(config.max_queue.unwrap_or(8)),
98            request_timeout: config.request_timeout.unwrap_or(Duration::from_secs(120)),
99        });
100        let policy = Arc::new(policy::Policy {
101            tokens,
102            listen: config.listen.clone(),
103            require_token_on_unix: config.require_token_on_unix,
104            allowed_hosts: config.allowed_hosts.clone(),
105            public_health: config.public_health,
106        });
107        let router = api::router(state).layer(axum::middleware::from_fn_with_state(policy, policy::enforce));
108        let bound = serve::bind(&config.listen).await?;
109        Ok(Self { bound, router, tls, max_connections: config.max_connections.unwrap_or(64), token_source, listen: config.listen })
110    }
111
112    /// Where the server is listening, e.g. `unix:/run/user/1000/loqui/loqui.sock`.
113    pub fn address(&self) -> String {
114        self.bound.describe()
115    }
116
117    pub fn token_source(&self) -> &auth::TokenSource {
118        &self.token_source
119    }
120
121    pub fn listen(&self) -> &Listen {
122        &self.listen
123    }
124
125    /// Serves until `shutdown` resolves, then removes the socket file.
126    pub async fn run(self, shutdown: impl Future<Output = ()>) -> Result<(), Error> {
127        serve::run(self.bound, self.router, self.tls, self.max_connections, shutdown).await
128    }
129}
130
131#[cfg(feature = "tls")]
132fn tls_from(config: &ServerConfig) -> Result<serve::Tls, Error> {
133    match (&config.tls_cert, &config.tls_key) {
134        (Some(cert), Some(key)) => Ok(Some(serve::tls_acceptor(cert, key)?)),
135        (None, None) => Ok(None),
136        _ => Err(Error::Config("--tls-cert and --tls-key go together".into())),
137    }
138}
139
140#[cfg(not(feature = "tls"))]
141fn tls_from(config: &ServerConfig) -> Result<serve::Tls, Error> {
142    if config.tls_cert.is_some() || config.tls_key.is_some() {
143        return Err(Error::Config("TLS was requested but loqui-server was built without the `tls` feature".into()));
144    }
145    Ok(None)
146}