lean_ctx/proxy/
models_api.rs

1//! `GET /v1/models` — the org's model catalog, served on the proxy port
2//! (enterprise#63).
3//!
4//! IDE clients (Cursor, OpenCode, Codex, Claude Code) call this endpoint to
5//! discover selectable models and to verify a configured API key. The catalog
6//! is the org's *curated* namespace: every `[proxy.routing]` alias (e.g.
7//! `"zuehlke/fast" = "foundry:deepseek-v4-flash"`) is listed under its alias
8//! name — the routing engine rewrites it to the real provider/model on the
9//! forward path. Tier rules are intent-based and transparent, so they are
10//! deliberately not listed as selectable names.
11//!
12//! Auth: the route sits behind the standard proxy auth guard — a personal
13//! gateway key (or the org Bearer token / a provider key on loopback)
14//! authenticates. A `200` from this endpoint therefore doubles as the
15//! "is my key valid?" check clients run at setup time.
16//!
17//! Shape: OpenAI list format by default; the Anthropic variant is returned
18//! when the request carries Anthropic client headers (`anthropic-version` /
19//! `x-api-key`). Output is deterministic (#498): alias order comes from the
20//! config's `BTreeMap`, the `created` stamp is a fixed constant — never a
21//! live clock.
22
23use axum::http::StatusCode;
24use axum::response::{IntoResponse, Json, Response};
25
26use crate::core::config::{RoutingRules, parse_route_target};
27
28/// Fixed `created` stamp for catalog entries (#498: no live clocks in bodies).
29/// 2025-01-01T00:00:00Z — clients only need a stable integer, not a real date.
30const CATALOG_CREATED_UNIX: i64 = 1_735_689_600;
31const CATALOG_CREATED_RFC3339: &str = "2025-01-01T00:00:00Z";
32
33/// `GET /v1/models` (and bare `/models`, normalized before routing).
34pub async fn handler(req: axum::extract::Request) -> Response {
35    let rules = crate::core::config::Config::load().proxy.routing.clone();
36    let body = if wants_anthropic_shape(&req) {
37        anthropic_model_list(&rules)
38    } else {
39        openai_model_list(&rules)
40    };
41    (StatusCode::OK, Json(body)).into_response()
42}
43
44/// Anthropic clients identify themselves by their credential/version headers;
45/// everything else (Cursor, OpenAI SDKs, plain curl) gets the OpenAI shape.
46fn wants_anthropic_shape(req: &axum::extract::Request) -> bool {
47    req.headers().contains_key("anthropic-version") || req.headers().contains_key("x-api-key")
48}
49
50/// The catalog rows: `(alias, owned_by)`. Empty when routing is inactive —
51/// an honest empty list, never an invented model set.
52fn catalog(rules: &RoutingRules) -> Vec<(String, String)> {
53    if !rules.is_active() {
54        return Vec::new();
55    }
56    rules
57        .aliases
58        .iter()
59        .map(|(alias, target)| {
60            let owned_by = parse_route_target(target)
61                .and_then(|(provider, _)| provider.map(str::to_string))
62                // Model-only alias (upstream unchanged) → owned by the gateway.
63                .unwrap_or_else(|| "gateway".to_string());
64            (alias.clone(), owned_by)
65        })
66        .collect()
67}
68
69/// OpenAI `GET /v1/models` list shape.
70fn openai_model_list(rules: &RoutingRules) -> serde_json::Value {
71    let data: Vec<serde_json::Value> = catalog(rules)
72        .into_iter()
73        .map(|(id, owned_by)| {
74            serde_json::json!({
75                "id": id,
76                "object": "model",
77                "created": CATALOG_CREATED_UNIX,
78                "owned_by": owned_by,
79            })
80        })
81        .collect();
82    serde_json::json!({ "object": "list", "data": data })
83}
84
85/// Anthropic `GET /v1/models` list shape (single page, `has_more: false`).
86fn anthropic_model_list(rules: &RoutingRules) -> serde_json::Value {
87    let entries = catalog(rules);
88    let first_id = entries.first().map(|(id, _)| id.clone());
89    let last_id = entries.last().map(|(id, _)| id.clone());
90    let data: Vec<serde_json::Value> = entries
91        .into_iter()
92        .map(|(id, _)| {
93            serde_json::json!({
94                "type": "model",
95                "id": id,
96                "display_name": id,
97                "created_at": CATALOG_CREATED_RFC3339,
98            })
99        })
100        .collect();
101    serde_json::json!({
102        "data": data,
103        "has_more": false,
104        "first_id": first_id,
105        "last_id": last_id,
106    })
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112
113    fn rules(aliases: &[(&str, &str)]) -> RoutingRules {
114        RoutingRules {
115            enabled: Some(true),
116            aliases: aliases
117                .iter()
118                .map(|(k, v)| (k.to_string(), v.to_string()))
119                .collect(),
120            tiers: std::collections::BTreeMap::new(),
121        }
122    }
123
124    #[test]
125    fn openai_list_exposes_aliases_with_provider_ownership() {
126        let body = openai_model_list(&rules(&[
127            ("zuehlke/fast", "foundry:deepseek-v4-flash"),
128            ("zuehlke/premium", "anthropic:claude-opus-4-5"),
129            ("claude-opus-4-5", "claude-sonnet-4-5"), // model-only downgrade
130        ]));
131        assert_eq!(body["object"], "list");
132        let data = body["data"].as_array().expect("data array");
133        assert_eq!(data.len(), 3);
134        // BTreeMap order: deterministic, alphabetical by alias (#498).
135        assert_eq!(data[0]["id"], "claude-opus-4-5");
136        assert_eq!(data[0]["owned_by"], "gateway", "model-only alias");
137        assert_eq!(data[1]["id"], "zuehlke/fast");
138        assert_eq!(data[1]["owned_by"], "foundry");
139        assert_eq!(data[2]["id"], "zuehlke/premium");
140        assert_eq!(data[2]["owned_by"], "anthropic");
141        for m in data {
142            assert_eq!(m["object"], "model");
143            assert_eq!(m["created"], CATALOG_CREATED_UNIX);
144        }
145    }
146
147    #[test]
148    fn anthropic_list_mirrors_the_same_catalog() {
149        let body = anthropic_model_list(&rules(&[
150            ("zuehlke/fast", "foundry:deepseek-v4-flash"),
151            ("zuehlke/premium", "anthropic:claude-opus-4-5"),
152        ]));
153        let data = body["data"].as_array().expect("data array");
154        assert_eq!(data.len(), 2);
155        assert_eq!(data[0]["type"], "model");
156        assert_eq!(data[0]["id"], "zuehlke/fast");
157        assert_eq!(data[0]["display_name"], "zuehlke/fast");
158        assert_eq!(body["has_more"], false);
159        assert_eq!(body["first_id"], "zuehlke/fast");
160        assert_eq!(body["last_id"], "zuehlke/premium");
161    }
162
163    #[test]
164    fn inactive_routing_yields_an_honest_empty_list() {
165        // enabled but no rules → inactive; disabled with rules → inactive.
166        let empty = rules(&[]);
167        assert_eq!(openai_model_list(&empty)["data"], serde_json::json!([]));
168        let mut off = rules(&[("a", "b:c")]);
169        off.enabled = Some(false);
170        assert_eq!(openai_model_list(&off)["data"], serde_json::json!([]));
171        let anth = anthropic_model_list(&off);
172        assert_eq!(anth["data"], serde_json::json!([]));
173        assert_eq!(anth["first_id"], serde_json::Value::Null);
174    }
175
176    #[test]
177    fn output_is_deterministic_across_calls() {
178        // Same rules → byte-identical JSON (#498: catalog responses must be
179        // stable for provider-side prompt caching and cheap client polling).
180        let r = rules(&[("z/fast", "foundry:m1"), ("a/slow", "local:m2")]);
181        let a = serde_json::to_string(&openai_model_list(&r)).unwrap();
182        let b = serde_json::to_string(&openai_model_list(&r)).unwrap();
183        assert_eq!(a, b);
184        // Alphabetical alias order regardless of insertion order.
185        let data = openai_model_list(&r);
186        assert_eq!(data["data"][0]["id"], "a/slow");
187        assert_eq!(data["data"][1]["id"], "z/fast");
188    }
189
190    #[test]
191    fn shape_detection_keys_on_anthropic_headers() {
192        let openai_req = axum::http::Request::builder()
193            .uri("/v1/models")
194            .header("authorization", "Bearer gk-alice-abc")
195            .body(axum::body::Body::empty())
196            .unwrap();
197        assert!(!wants_anthropic_shape(&openai_req));
198
199        let claude_req = axum::http::Request::builder()
200            .uri("/v1/models")
201            .header("x-api-key", "gk-alice-abc")
202            .header("anthropic-version", "2023-06-01")
203            .body(axum::body::Body::empty())
204            .unwrap();
205        assert!(wants_anthropic_shape(&claude_req));
206    }
207}
lean_ctx/proxy/models_api.rs

lean_ctx/proxy/
models_api.rs
