use crate::error::{Error, Result};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use zeroize::Zeroize;
pub const STORE_VERSION: u32 = 1;
pub const PROXY_DIRECT: &str = "direct";
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Store {
pub version: u32,
#[serde(default)]
pub password_hash: Option<String>,
#[serde(default)]
pub routes: BTreeMap<String, Route>,
}
impl Default for Store {
fn default() -> Self {
Self::new()
}
}
impl Store {
pub fn new() -> Self {
Self {
version: STORE_VERSION,
password_hash: None,
routes: BTreeMap::new(),
}
}
pub fn validate(&self) -> Result<()> {
if self.version != STORE_VERSION {
return Err(Error::msg(format!(
"store version {} is not supported (supported version: {})",
self.version, STORE_VERSION
)));
}
let mut vkeys = std::collections::HashSet::new();
for (name, route) in &self.routes {
validate_name(name, "route")?;
route.validate(name)?;
match &route.inline_key {
Some(value) if !value.is_empty() => {}
Some(_) => {
return Err(Error::msg(format!(
"route `{name}` has an empty route-only key"
)));
}
None => {
return Err(Error::msg(format!(
"route `{name}` is missing its key (use route update --route-key to re-enter it)"
)));
}
}
if !vkeys.insert(route.vkey.clone()) {
return Err(Error::msg(format!(
"route `{name}` has a vkey that duplicates another route"
)));
}
}
Ok(())
}
}
impl Drop for Route {
fn drop(&mut self) {
if let Some(value) = &mut self.inline_key {
value.zeroize();
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Route {
pub vkey: String,
pub base_url: String,
#[serde(default)]
pub inline_key: Option<String>,
#[serde(default)]
pub auth: Auth,
#[serde(default)]
pub headers: BTreeMap<String, String>,
#[serde(default = "default_true")]
pub enabled: bool,
#[serde(default)]
pub max_retries: Option<u8>,
#[serde(default)]
pub retry_on_status: Option<Vec<u16>>,
#[serde(default)]
pub sse_terminator: Terminator,
#[serde(default)]
pub proxy: Option<String>,
#[serde(default)]
pub note: String,
#[serde(default)]
pub created: u64,
}
fn default_true() -> bool {
true
}
impl Route {
pub fn new(
vkey: String,
base_url: String,
inline_key: String,
auth: Auth,
headers: BTreeMap<String, String>,
) -> Self {
Self {
vkey,
base_url,
inline_key: Some(inline_key),
auth,
headers,
enabled: true,
max_retries: None,
retry_on_status: None,
sse_terminator: Terminator::Auto,
proxy: None,
note: String::new(),
created: crate::util::now_secs(),
}
}
pub(crate) fn validate(&self, name: &str) -> Result<()> {
if !crate::vkey::is_well_formed(&self.vkey) {
return Err(Error::msg(format!(
"route `{name}` has an invalid vkey (expected ks_ + 43 chars of base64url)"
)));
}
if !(self.base_url.starts_with("http://") || self.base_url.starts_with("https://")) {
return Err(Error::msg(format!(
"route `{name}` base_url must start with http:// or https://"
)));
}
if self.base_url.ends_with('/') {
return Err(Error::msg(format!(
"route `{name}` base_url must not end with /"
)));
}
if self.base_url.contains('?') || self.base_url.contains('#') {
return Err(Error::msg(format!(
"route `{name}` base_url must not contain a query or fragment"
)));
}
match &self.auth {
Auth::Bearer | Auth::XApiKey | Auth::None => {}
Auth::Header {
name: header,
prefix,
} => {
if header.is_empty() {
return Err(Error::msg(format!(
"route `{name}` has an empty auth header name"
)));
}
if !header
.bytes()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_'))
{
return Err(Error::msg(format!(
"route `{name}` auth header name contains invalid characters"
)));
}
if axum::http::HeaderValue::from_str(prefix).is_err() {
return Err(Error::msg(format!(
"route `{name}` auth header prefix contains invalid characters (visible ASCII only)"
)));
}
}
Auth::Basic { username } => {
if username.is_empty() {
return Err(Error::msg(format!(
"route `{name}` has an empty basic username"
)));
}
if axum::http::HeaderValue::from_str(username).is_err() {
return Err(Error::msg(format!(
"route `{name}` basic username contains invalid characters (visible ASCII only)"
)));
}
}
Auth::Query { param } => {
if param.is_empty() {
return Err(Error::msg(format!(
"route `{name}` has an empty query parameter name"
)));
}
if !param
.bytes()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
{
return Err(Error::msg(format!(
"route `{name}` query parameter name contains invalid characters (only letters, digits, -, _, . are allowed)"
)));
}
}
}
for (key, value) in &self.headers {
if key.is_empty() {
return Err(Error::msg(format!(
"route `{name}` has an empty header name"
)));
}
if !key
.bytes()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_'))
{
return Err(Error::msg(format!(
"route `{name}` header `{key}` name contains invalid characters"
)));
}
if is_forbidden_static_header(key) {
return Err(Error::msg(format!(
"route `{name}` must not override `{key}` with a static header"
)));
}
if axum::http::HeaderValue::from_str(value).is_err() {
return Err(Error::msg(format!(
"route `{name}` header `{key}` value contains invalid characters (visible ASCII only)"
)));
}
}
if let Some(retries) = self.max_retries
&& retries > 10
{
return Err(Error::msg(format!(
"route `{name}` max_retries must not exceed 10"
)));
}
if let Some(statuses) = &self.retry_on_status
&& let Some(bad) = statuses.iter().find(|s| !(400..=599).contains(*s))
{
return Err(Error::msg(format!(
"route `{name}` retry_on_status contains {bad}: only status codes 400..=599 can be retried"
)));
}
if let Some(proxy) = &self.proxy
&& proxy != PROXY_DIRECT
&& !(proxy.starts_with("http://") || proxy.starts_with("https://"))
{
return Err(Error::msg(format!(
"route `{name}` proxy only supports an http(s):// URL or `direct` (default follows the system proxy)"
)));
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum Auth {
#[default]
Bearer,
XApiKey,
Header {
name: String,
#[serde(default)]
prefix: String,
},
Basic {
username: String,
},
Query {
param: String,
},
None,
}
impl Auth {
pub fn describe(&self) -> String {
match self {
Auth::Bearer => "bearer".into(),
Auth::XApiKey => "x-api-key".into(),
Auth::Header { name, prefix } => {
if prefix.is_empty() {
format!("header:{name}")
} else {
format!("header:{name} (prefix)")
}
}
Auth::Basic { username } => format!("basic:{username}"),
Auth::Query { param } => format!("query:{param}"),
Auth::None => "none".into(),
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, Default, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Terminator {
#[default]
Auto,
Openai,
Anthropic,
None,
}
impl Terminator {
pub fn parse(value: &str) -> Result<Self> {
match value {
"auto" => Ok(Self::Auto),
"openai" => Ok(Self::Openai),
"anthropic" => Ok(Self::Anthropic),
"none" => Ok(Self::None),
other => Err(Error::msg(format!(
"unknown sse-terminator `{other}` (options: auto/openai/anthropic/none)"
))),
}
}
pub fn as_str(&self) -> &'static str {
match self {
Self::Auto => "auto",
Self::Openai => "openai",
Self::Anthropic => "anthropic",
Self::None => "none",
}
}
}
fn is_forbidden_static_header(name: &str) -> bool {
const FORBIDDEN: &[&str] = &[
"host",
"content-length",
"connection",
"keep-alive",
"proxy-authenticate",
"proxy-authorization",
"proxy-connection",
"te",
"trailer",
"transfer-encoding",
"upgrade",
"authorization",
"x-api-key",
"x-goog-api-key",
"api-key",
"anthropic-api-key",
"openai-api-key",
];
FORBIDDEN.iter().any(|h| h.eq_ignore_ascii_case(name))
}
pub fn validate_name(name: &str, what: &str) -> Result<()> {
if name.is_empty() || name.len() > 64 {
return Err(Error::msg(format!(
"{what} name length must be within 1..=64"
)));
}
if !name
.bytes()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
{
return Err(Error::msg(format!(
"{what} name `{name}` may only contain letters, digits, -, _, ."
)));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn sample() -> Store {
let mut store = Store::new();
store.routes.insert(
"r".into(),
Route::new(
crate::vkey::generate(),
"https://api.example.com".into(),
"secret-value".into(),
Auth::Bearer,
BTreeMap::new(),
),
);
store
}
#[test]
fn validates_ok() {
sample().validate().unwrap();
}
#[test]
fn rejects_missing_inline_key() {
let mut s = sample();
s.routes.get_mut("r").unwrap().inline_key = None;
assert!(s.validate().is_err());
let mut s = sample();
s.routes.get_mut("r").unwrap().inline_key = Some(String::new());
assert!(s.validate().is_err());
}
#[test]
fn rejects_malformed_vkey_like_serve_does() {
let mut s = sample();
s.routes.get_mut("r").unwrap().vkey = "ks_short".into();
assert!(s.validate().is_err());
s.routes.get_mut("r").unwrap().vkey =
"sk_0000000000000000000000000000000000000000000".into();
assert!(s.validate().is_err());
}
#[test]
fn rejects_duplicate_vkey() {
let mut s = sample();
let vkey = s.routes["r"].vkey.clone();
let mut route = s.routes["r"].clone();
route.vkey = vkey;
s.routes.insert("r2".into(), route);
assert!(s.validate().is_err());
}
#[test]
fn rejects_bad_query_param_names() {
for bad in ["a=b", "a&b", "a b", "a/b"] {
let mut s = sample();
s.routes.get_mut("r").unwrap().auth = Auth::Query { param: bad.into() };
assert!(s.validate().is_err(), "param `{bad}` should be rejected");
}
let mut s = sample();
s.routes.get_mut("r").unwrap().auth = Auth::Query {
param: "api_key-x.1".into(),
};
s.validate().unwrap();
}
#[test]
fn rejects_header_values_headervalue_would_refuse() {
for bad in [
"bad\nvalue",
"bad\rvalue",
"bad\u{0}value",
"bad\u{7f}value",
] {
let mut s = sample();
s.routes
.get_mut("r")
.unwrap()
.headers
.insert("x-trace".into(), bad.into());
assert!(s.validate().is_err(), "value `{bad}` should be rejected");
}
let mut s = sample();
s.routes
.get_mut("r")
.unwrap()
.headers
.insert("x-trace".into(), "2023-06-01".into());
s.validate().unwrap();
}
#[test]
fn rejects_auth_fields_headervalue_would_refuse() {
let mut s = sample();
s.routes.get_mut("r").unwrap().auth = Auth::Header {
name: "x-custom-auth".into(),
prefix: "Bearer\n".into(),
};
assert!(s.validate().is_err());
let mut s = sample();
s.routes.get_mut("r").unwrap().auth = Auth::Basic {
username: "user\rname".into(),
};
assert!(s.validate().is_err());
let mut s = sample();
s.routes.get_mut("r").unwrap().auth = Auth::Header {
name: "x-custom-auth".into(),
prefix: String::new(),
};
s.validate().unwrap();
}
#[test]
fn rejects_retry_on_status_outside_4xx_5xx() {
for bad in [200u16, 302, 399, 600] {
let mut s = sample();
s.routes.get_mut("r").unwrap().retry_on_status = Some(vec![bad]);
assert!(s.validate().is_err(), "status {bad} should be rejected");
}
let mut s = sample();
s.routes.get_mut("r").unwrap().retry_on_status = Some(vec![429, 500, 503]);
s.validate().unwrap();
}
#[test]
fn validates_route_proxy() {
let mut s = sample();
s.validate().unwrap();
for ok in [
None,
Some("direct".into()),
Some("http://127.0.0.1:7890".into()),
Some("https://proxy.example.com".into()),
] {
s.routes.get_mut("r").unwrap().proxy = ok;
s.validate().unwrap();
}
for bad in ["127.0.0.1:7890", "socks5://127.0.0.1:7890", ""] {
s.routes.get_mut("r").unwrap().proxy = Some(bad.into());
assert!(s.validate().is_err(), "proxy `{bad}` should be rejected");
}
}
}