Skip to main content

firstpass_proxy/
config.rs

1//! Proxy configuration, loaded from the environment (SPEC §7.4: agent-first, zero-config
2//! by default — every knob has a sane local default and can be overridden by env var).
3
4use std::env;
5use std::num::NonZeroU32;
6
7use firstpass_core::{Config as RoutingConfig, Mode, PriceTable, RoutingMode};
8
9/// The built-in prompt salt used when `FIRSTPASS_PROMPT_SALT` is unset. Fine for local
10/// development; an operator should set their own before handling real traffic, since a
11/// shared default salt makes `prompt_hash` comparable/guessable across installs.
12const DEFAULT_PROMPT_SALT: &str = "firstpass-dev-salt";
13
14/// Controls what happens to audit traces when the background writer channel is full.
15///
16/// - [`BestEffort`](ReceiptsMode::BestEffort) — `try_send` drops the trace and increments
17///   `firstpass_traces_dropped_total`; bounded memory, zero added latency. The hash chain over
18///   persisted traces stays valid; a dropped trace is simply absent.
19/// - [`Durable`](ReceiptsMode::Durable) — on `TrySendError::Full` the trace is serialised as a
20///   JSON line and appended (with `sync_data`) to `<db_path>.spill.jsonl`. The background writer
21///   drains the spill file at startup and whenever the channel empties, inserting spilled traces
22///   BEFORE new channel arrivals so the hash chain remains append-only and valid.
23///   The blocking fs append on the hot path is the DELIBERATE tradeoff of durable mode —
24///   it only fires under sustained backpressure; switch to `best_effort` if disk latency
25///   under load is unacceptable.
26#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
27pub enum ReceiptsMode {
28    /// Drop traces when the writer channel is full (default — bounded memory, zero latency impact).
29    #[default]
30    BestEffort,
31    /// Spill traces to disk when the writer channel is full; drain and recover on the next boot
32    /// or whenever the channel empties.
33    Durable,
34}
35
36/// Runtime configuration for the proxy.
37#[derive(Debug, Clone)]
38pub struct ProxyConfig {
39    /// Address to bind the HTTP server to, e.g. `127.0.0.1:8080`.
40    pub bind: String,
41    /// Base URL of the upstream Anthropic-compatible API.
42    pub upstream_anthropic: String,
43    /// Base URL of the upstream OpenAI-compatible API.
44    pub upstream_openai: String,
45    /// Base URL of the upstream Gemini API (overridable via `FIRSTPASS_UPSTREAM_GEMINI`).
46    /// Default: `https://generativelanguage.googleapis.com`.
47    pub upstream_gemini: String,
48    /// Path to the SQLite trace database.
49    pub db_path: String,
50    /// Tenant identifier stamped on every trace when `require_auth` is off (single-operator
51    /// default). When `require_auth` is on, the per-request tenant comes from the verified API
52    /// key instead, and this is only the fallback for operator-scoped tooling.
53    pub tenant_id: String,
54    /// Multi-tenant auth gate (ADR 0004 §D1). Default `false` — single-operator behavior is
55    /// byte-identical: no auth checks, tenant is the static [`Self::tenant_id`]. Set via
56    /// `FIRSTPASS_REQUIRE_AUTH`. **Experimental / pre-external-review (ADR 0004 §D7).**
57    pub require_auth: bool,
58    /// Per-tenant Argon2id API-key hashes (ADR 0004 §D1). Empty unless configured via
59    /// `FIRSTPASS_TENANT_KEYS` (path to a JSON `{ tenant_id: hash }`) or `FIRSTPASS_TENANT_KEYS_JSON`
60    /// (inline JSON). Only consulted when `require_auth` is on.
61    ///
62    /// The stored `hash` is the Argon2id hash of a tenant's **secret** (make one with
63    /// `TenantKeys::hash_key`). A tenant then authenticates with the key `<tenant_id>.<secret>` —
64    /// the tenant id names which hash to verify, so a request does exactly one Argon2 check. Tenant
65    /// ids must not contain a `.` (the first `.` splits id from secret).
66    pub tenant_keys: crate::tenant_auth::TenantKeys,
67    /// Salt mixed into the prompt hash so raw prompt text never touches storage.
68    pub prompt_salt: String,
69    /// Default mode when no routing config matches (`observe` unless overridden).
70    pub mode: Mode,
71    /// Optional declarative routing config (§8.4). When present, its routes decide the mode,
72    /// ladder, and gates per request; enforce routes activate the escalation engine.
73    pub routing: Option<RoutingConfig>,
74    /// Model pricing table used to cost each attempt.
75    pub prices: PriceTable,
76    /// Max in-flight requests before new ones queue behind the concurrency limiter
77    /// (`FIRSTPASS_MAX_CONCURRENCY`, default 512). A load-shed valve, not a timeout — it never
78    /// severs an in-flight SSE stream.
79    pub max_concurrency: usize,
80    /// Per-tenant request rate limit, requests/sec (ADR 0004 §D6). `None` (the default) means
81    /// unlimited — single-operator and existing deployments are unaffected. Set via
82    /// `FIRSTPASS_TENANT_RATE_PER_SEC`; only enforced when configured.
83    pub tenant_rate_per_sec: Option<NonZeroU32>,
84    /// Whether to guarantee audit-trace durability under backpressure (`FIRSTPASS_RECEIPTS`).
85    /// Default [`ReceiptsMode::BestEffort`] is byte-identical to the previous behavior.
86    pub receipts_mode: ReceiptsMode,
87    /// Global default routing-mode preset (`FIRSTPASS_MODE_PROFILE`). Overridden by per-route
88    /// `routing_mode` and the per-request `x-firstpass-mode` header. Default `Balanced` is
89    /// byte-identical to existing behaviour (no knob changes at all).
90    pub default_routing_mode: RoutingMode,
91}
92
93/// Default for [`ProxyConfig::max_concurrency`] when `FIRSTPASS_MAX_CONCURRENCY` is unset.
94const DEFAULT_MAX_CONCURRENCY: usize = 512;
95
96/// Errors that prevent the proxy from starting.
97#[derive(Debug, thiserror::Error)]
98pub enum ConfigError {
99    /// `FIRSTPASS_MODE` named an unknown mode (valid: `observe`, `enforce`).
100    #[error(
101        "FIRSTPASS_MODE={0:?} is not a known mode; set `observe` or `enforce`, or leave it unset"
102    )]
103    UnsupportedMode(String),
104
105    /// `FIRSTPASS_RECEIPTS` named an unknown mode (valid: `best_effort`, `durable`).
106    #[error("FIRSTPASS_RECEIPTS={0:?} is not valid; set `best_effort` (default) or `durable`")]
107    UnsupportedReceiptsMode(String),
108
109    /// `FIRSTPASS_MODE_PROFILE` named an unknown routing mode.
110    #[error(
111        "FIRSTPASS_MODE_PROFILE={0:?} is not a known routing mode; \
112         valid: observe|cost|balanced|quality|latency|max"
113    )]
114    UnsupportedModeProfile(String),
115
116    /// The routing config file could not be read or parsed.
117    #[error("routing config error: {0}")]
118    Config(String),
119
120    /// The multi-tenant auth config (`FIRSTPASS_TENANT_KEYS`) is invalid (ADR 0004 §D1). The
121    /// message never echoes hash material — only the structural problem.
122    #[error("tenant auth config error: {0}")]
123    Auth(#[from] crate::tenant_auth::AuthConfigError),
124}
125
126impl ProxyConfig {
127    /// Load configuration from environment variables, falling back to local defaults.
128    ///
129    /// # Errors
130    /// [`ConfigError::UnsupportedMode`] for an unknown `FIRSTPASS_MODE`; [`ConfigError::Config`]
131    /// if the `FIRSTPASS_CONFIG` routing file cannot be read or parsed.
132    pub fn from_env() -> Result<Self, ConfigError> {
133        // Read the routing config file (if any) here, then hand its *content* to the pure
134        // `from_lookup` seam via the synthetic `FIRSTPASS_CONFIG_TOML` key — keeping file I/O
135        // out of the unit-testable path.
136        let routing_toml = match env::var("FIRSTPASS_CONFIG").ok() {
137            Some(path) => Some(
138                std::fs::read_to_string(&path)
139                    .map_err(|e| ConfigError::Config(format!("reading {path}: {e}")))?,
140            ),
141            None => None,
142        };
143        // Read the tenant-keys file (if any) here and hand its *content* to `from_lookup` via the
144        // synthetic `FIRSTPASS_TENANT_KEYS_JSON` key, keeping file I/O out of the testable path.
145        // An inline `FIRSTPASS_TENANT_KEYS_JSON` in the real env takes precedence if both are set.
146        let tenant_keys_json = match env::var("FIRSTPASS_TENANT_KEYS").ok() {
147            Some(path) => Some(
148                std::fs::read_to_string(&path)
149                    .map_err(|e| ConfigError::Config(format!("reading {path}: {e}")))?,
150            ),
151            None => None,
152        };
153        Self::from_lookup(|key| match key {
154            "FIRSTPASS_CONFIG_TOML" => routing_toml.clone(),
155            "FIRSTPASS_TENANT_KEYS_JSON" => env::var(key).ok().or_else(|| tenant_keys_json.clone()),
156            other => env::var(other).ok(),
157        })
158    }
159
160    /// Load configuration from an arbitrary key lookup — the seam `from_env` uses, exposed
161    /// so tests can exercise defaulting/validation without touching real process env vars.
162    /// The routing config is supplied inline via the `FIRSTPASS_CONFIG_TOML` key.
163    ///
164    /// # Errors
165    /// [`ConfigError::UnsupportedMode`] for an unknown `FIRSTPASS_MODE`; [`ConfigError::Config`]
166    /// if the inline routing TOML fails to parse.
167    pub fn from_lookup(lookup: impl Fn(&str) -> Option<String>) -> Result<Self, ConfigError> {
168        let bind = lookup("FIRSTPASS_BIND").unwrap_or_else(|| "127.0.0.1:8080".to_owned());
169        let upstream_anthropic = lookup("FIRSTPASS_UPSTREAM_ANTHROPIC")
170            .unwrap_or_else(|| "https://api.anthropic.com".to_owned());
171        let upstream_openai = lookup("FIRSTPASS_UPSTREAM_OPENAI")
172            .unwrap_or_else(|| "https://api.openai.com".to_owned());
173        let upstream_gemini = lookup("FIRSTPASS_UPSTREAM_GEMINI")
174            .unwrap_or_else(|| "https://generativelanguage.googleapis.com".to_owned());
175        let db_path = lookup("FIRSTPASS_DB").unwrap_or_else(|| "firstpass.db".to_owned());
176        let tenant_id = lookup("FIRSTPASS_TENANT").unwrap_or_else(|| "default".to_owned());
177        let prompt_salt = lookup("FIRSTPASS_PROMPT_SALT").unwrap_or_else(|| {
178            tracing::warn!(
179                "FIRSTPASS_PROMPT_SALT is unset — using the built-in dev default; \
180                 set a real secret before handling production traffic"
181            );
182            DEFAULT_PROMPT_SALT.to_owned()
183        });
184        let mode_str = lookup("FIRSTPASS_MODE").unwrap_or_else(|| "observe".to_owned());
185        let mode = match mode_str.as_str() {
186            "observe" => Mode::Observe,
187            "enforce" => Mode::Enforce,
188            other => return Err(ConfigError::UnsupportedMode(other.to_owned())),
189        };
190        let routing = match lookup("FIRSTPASS_CONFIG_TOML") {
191            Some(toml) => {
192                Some(RoutingConfig::parse(&toml).map_err(|e| ConfigError::Config(e.to_string()))?)
193            }
194            None => None,
195        };
196        let max_concurrency = match lookup("FIRSTPASS_MAX_CONCURRENCY") {
197            Some(s) => s.parse().map_err(|e| {
198                ConfigError::Config(format!("FIRSTPASS_MAX_CONCURRENCY={s:?}: {e}"))
199            })?,
200            None => DEFAULT_MAX_CONCURRENCY,
201        };
202
203        // Multi-tenant auth (ADR 0004 §D1) — default OFF. Anything other than an explicit truthy
204        // value leaves single-operator behavior byte-identical.
205        let require_auth = lookup("FIRSTPASS_REQUIRE_AUTH")
206            .map(|s| {
207                matches!(
208                    s.trim().to_ascii_lowercase().as_str(),
209                    "1" | "true" | "yes" | "on"
210                )
211            })
212            .unwrap_or(false);
213        let tenant_keys = match lookup("FIRSTPASS_TENANT_KEYS_JSON") {
214            Some(json) => crate::tenant_auth::TenantKeys::from_json(&json)?,
215            None => crate::tenant_auth::TenantKeys::default(),
216        };
217        if require_auth && tenant_keys.is_empty() {
218            tracing::warn!(
219                "FIRSTPASS_REQUIRE_AUTH is on but no tenant keys are configured — every request \
220                 will be rejected with 401 until FIRSTPASS_TENANT_KEYS is set"
221            );
222        }
223
224        // Per-tenant rate limiting (ADR 0004 §D6) — default OFF (unlimited).
225        let tenant_rate_per_sec = match lookup("FIRSTPASS_TENANT_RATE_PER_SEC") {
226            Some(s) => Some(s.trim().parse::<NonZeroU32>().map_err(|e| {
227                ConfigError::Config(format!("FIRSTPASS_TENANT_RATE_PER_SEC={s:?}: {e}"))
228            })?),
229            None => None,
230        };
231
232        // Receipts durability mode — default BestEffort (byte-identical to pre-Phase-3 behavior).
233        let receipts_mode = match lookup("FIRSTPASS_RECEIPTS").as_deref() {
234            None | Some("best_effort") => ReceiptsMode::BestEffort,
235            Some("durable") => ReceiptsMode::Durable,
236            Some(other) => {
237                return Err(ConfigError::UnsupportedReceiptsMode(other.to_owned()));
238            }
239        };
240
241        // Global routing-mode profile — default Balanced (byte-identical to existing behaviour).
242        let default_routing_mode = match lookup("FIRSTPASS_MODE_PROFILE").as_deref() {
243            None | Some("balanced") => RoutingMode::Balanced,
244            Some("observe") => RoutingMode::Observe,
245            Some("cost") => RoutingMode::Cost,
246            Some("quality") => RoutingMode::Quality,
247            Some("latency") => RoutingMode::Latency,
248            Some("max") => RoutingMode::Max,
249            Some(other) => {
250                return Err(ConfigError::UnsupportedModeProfile(other.to_owned()));
251            }
252        };
253
254        Ok(Self {
255            bind,
256            upstream_anthropic,
257            upstream_openai,
258            upstream_gemini,
259            db_path,
260            tenant_id,
261            require_auth,
262            tenant_keys,
263            prompt_salt,
264            mode,
265            prices: {
266                // Operator [[price]] overrides pin THIS deployment's real prices onto the
267                // built-in defaults — savings math tracks the contract, not a stale list.
268                let mut prices = PriceTable::defaults();
269                if let Some(cfg) = routing.as_ref() {
270                    for p in &cfg.price_defs {
271                        prices = prices.with_override(
272                            p.model.clone(),
273                            firstpass_core::ModelPrice {
274                                input_per_mtok: p.input_per_mtok,
275                                output_per_mtok: p.output_per_mtok,
276                            },
277                        );
278                    }
279                }
280                prices
281            },
282            routing,
283            max_concurrency,
284            tenant_rate_per_sec,
285            receipts_mode,
286            default_routing_mode,
287        })
288    }
289}
290
291#[cfg(test)]
292mod tests {
293    use super::*;
294
295    #[test]
296    fn defaults_are_sane_when_unset() {
297        let cfg = ProxyConfig::from_lookup(|_| None).unwrap();
298        assert_eq!(cfg.bind, "127.0.0.1:8080");
299        assert_eq!(cfg.upstream_anthropic, "https://api.anthropic.com");
300        assert_eq!(
301            cfg.upstream_gemini,
302            "https://generativelanguage.googleapis.com"
303        );
304        assert_eq!(cfg.db_path, "firstpass.db");
305        assert_eq!(cfg.tenant_id, "default");
306        assert_eq!(cfg.prompt_salt, DEFAULT_PROMPT_SALT);
307        assert_eq!(cfg.mode, Mode::Observe);
308        assert_eq!(cfg.max_concurrency, DEFAULT_MAX_CONCURRENCY);
309    }
310
311    #[test]
312    fn max_concurrency_is_parsed_from_env() {
313        let cfg = ProxyConfig::from_lookup(|key| {
314            (key == "FIRSTPASS_MAX_CONCURRENCY").then(|| "64".to_owned())
315        })
316        .unwrap();
317        assert_eq!(cfg.max_concurrency, 64);
318    }
319
320    #[test]
321    fn bad_max_concurrency_is_an_error() {
322        let result = ProxyConfig::from_lookup(|key| {
323            (key == "FIRSTPASS_MAX_CONCURRENCY").then(|| "not-a-number".to_owned())
324        });
325        assert!(matches!(result, Err(ConfigError::Config(_))));
326    }
327
328    #[test]
329    fn overrides_are_applied() {
330        let cfg = ProxyConfig::from_lookup(|key| match key {
331            "FIRSTPASS_BIND" => Some("0.0.0.0:9090".to_owned()),
332            "FIRSTPASS_TENANT" => Some("acme".to_owned()),
333            _ => None,
334        })
335        .unwrap();
336        assert_eq!(cfg.bind, "0.0.0.0:9090");
337        assert_eq!(cfg.tenant_id, "acme");
338    }
339
340    #[test]
341    fn enforce_mode_is_accepted() {
342        let cfg =
343            ProxyConfig::from_lookup(|key| (key == "FIRSTPASS_MODE").then(|| "enforce".to_owned()))
344                .unwrap();
345        assert_eq!(cfg.mode, Mode::Enforce);
346    }
347
348    #[test]
349    fn unknown_mode_is_rejected() {
350        let result =
351            ProxyConfig::from_lookup(|key| (key == "FIRSTPASS_MODE").then(|| "banana".to_owned()));
352        assert!(matches!(result, Err(ConfigError::UnsupportedMode(m)) if m == "banana"));
353    }
354
355    #[test]
356    fn routing_config_parses_inline() {
357        let toml = r#"
358[[route]]
359match = { task_kind = "code_edit" }
360mode = "enforce"
361ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
362gates = ["non-empty"]
363"#;
364        let cfg = ProxyConfig::from_lookup(|key| match key {
365            "FIRSTPASS_CONFIG_TOML" => Some(toml.to_owned()),
366            _ => None,
367        })
368        .unwrap();
369        let routing = cfg.routing.expect("routing config present");
370        assert_eq!(routing.routes.len(), 1);
371        assert_eq!(routing.routes[0].mode, Mode::Enforce);
372    }
373
374    #[test]
375    fn bad_routing_config_is_an_error() {
376        let result = ProxyConfig::from_lookup(|key| match key {
377            "FIRSTPASS_CONFIG_TOML" => Some("this is not valid = = toml".to_owned()),
378            _ => None,
379        });
380        assert!(matches!(result, Err(ConfigError::Config(_))));
381    }
382
383    #[test]
384    fn receipts_mode_defaults_to_best_effort() {
385        let cfg = ProxyConfig::from_lookup(|_| None).unwrap();
386        assert_eq!(cfg.receipts_mode, ReceiptsMode::BestEffort);
387    }
388
389    #[test]
390    fn receipts_mode_durable_is_accepted() {
391        let cfg =
392            ProxyConfig::from_lookup(|k| (k == "FIRSTPASS_RECEIPTS").then(|| "durable".to_owned()))
393                .unwrap();
394        assert_eq!(cfg.receipts_mode, ReceiptsMode::Durable);
395    }
396
397    #[test]
398    fn receipts_mode_best_effort_explicit_is_accepted() {
399        let cfg = ProxyConfig::from_lookup(|k| {
400            (k == "FIRSTPASS_RECEIPTS").then(|| "best_effort".to_owned())
401        })
402        .unwrap();
403        assert_eq!(cfg.receipts_mode, ReceiptsMode::BestEffort);
404    }
405
406    #[test]
407    fn receipts_mode_unknown_is_rejected() {
408        let result = ProxyConfig::from_lookup(|k| {
409            (k == "FIRSTPASS_RECEIPTS").then(|| "never_drop".to_owned())
410        });
411        assert!(
412            matches!(result, Err(ConfigError::UnsupportedReceiptsMode(m)) if m == "never_drop")
413        );
414    }
415
416    #[test]
417    fn default_routing_mode_is_balanced() {
418        let cfg = ProxyConfig::from_lookup(|_| None).unwrap();
419        assert_eq!(cfg.default_routing_mode, RoutingMode::Balanced);
420    }
421
422    #[test]
423    fn firstpass_mode_profile_is_parsed() {
424        let cfg = ProxyConfig::from_lookup(|k| {
425            (k == "FIRSTPASS_MODE_PROFILE").then(|| "quality".to_owned())
426        })
427        .unwrap();
428        assert_eq!(cfg.default_routing_mode, RoutingMode::Quality);
429    }
430
431    #[test]
432    fn unknown_mode_profile_is_rejected() {
433        let result = ProxyConfig::from_lookup(|k| {
434            (k == "FIRSTPASS_MODE_PROFILE").then(|| "turbo".to_owned())
435        });
436        assert!(matches!(result, Err(ConfigError::UnsupportedModeProfile(m)) if m == "turbo"));
437    }
438
439    #[test]
440    fn price_overrides_reach_the_price_table() {
441        let toml = "[[route]]\nmatch = {}\nmode = \"observe\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n\n[[price]]\nmodel = \"anthropic/claude-haiku-4-5\"\ninput_per_mtok = 2.0\noutput_per_mtok = 10.0\n";
442        let cfg = ProxyConfig::from_lookup(|k| match k {
443            "FIRSTPASS_CONFIG_TOML" => Some(toml.to_owned()),
444            _ => None,
445        })
446        .unwrap();
447        // 1000 in + 1000 out at 2.0/10.0 per Mtok = 0.002 + 0.010.
448        let cost = cfg
449            .prices
450            .cost_usd("anthropic/claude-haiku-4-5", 1000, 1000)
451            .unwrap();
452        assert!((cost - 0.012).abs() < 1e-9, "override must win: {cost}");
453    }
454}