gproxy_protocol/protocol/
endpoint.rs

1//! Target endpoint synthesis (M2): the provider-relative method/path/query a
2//! transformed request must hit for a given operation key. Passthrough keeps
3//! the inbound target and never calls this.
4
5use crate::protocol::operation::{
6    ContentGenerationKind, HttpMethod, Operation, OperationKey, OperationKind, Provider,
7};
8
9/// Provider-relative request target for a wired operation.
10#[derive(Debug, Clone, PartialEq, Eq, gproxy_protocol_macros::WireBuilder)]
11#[non_exhaustive]
12pub struct RequestTarget {
13    pub method: HttpMethod,
14    pub path: String,
15    /// Extra query the wire format requires (e.g. gemini `alt=sse`).
16    pub query: Option<String>,
17}
18
19impl RequestTarget {
20    fn get(path: impl Into<String>) -> Self {
21        Self {
22            method: HttpMethod::Get,
23            path: path.into(),
24            query: None,
25        }
26    }
27
28    fn post(path: impl Into<String>) -> Self {
29        Self {
30            method: HttpMethod::Post,
31            path: path.into(),
32            query: None,
33        }
34    }
35}
36
37#[derive(Debug, Clone, PartialEq, Eq)]
38#[non_exhaustive]
39pub enum EndpointError {
40    InconsistentOperationKey(OperationKey),
41    StreamMismatch {
42        operation: Operation,
43        stream: bool,
44    },
45    UnsupportedOperation {
46        operation: Operation,
47        provider: Provider,
48    },
49    MissingModel {
50        operation: Operation,
51        provider: Provider,
52    },
53}
54
55impl std::fmt::Display for EndpointError {
56    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57        match self {
58            Self::InconsistentOperationKey(key) => {
59                write!(formatter, "inconsistent operation key: {key:?}")
60            }
61            Self::StreamMismatch { operation, stream } => write!(
62                formatter,
63                "operation {operation:?} is incompatible with stream={stream}"
64            ),
65            Self::UnsupportedOperation {
66                operation,
67                provider,
68            } => write!(
69                formatter,
70                "operation {operation:?} is unsupported by {provider:?}"
71            ),
72            Self::MissingModel {
73                operation,
74                provider,
75            } => write!(
76                formatter,
77                "operation {operation:?} for {provider:?} requires a non-empty raw model id"
78            ),
79        }
80    }
81}
82
83impl std::error::Error for EndpointError {}
84
85/// Build the upstream request target for any wired operation key. `model` is
86/// the upstream model id (path-templated providers embed it); `stream` selects
87/// the streaming variant where the wire format distinguishes it by endpoint.
88pub fn request_target(
89    target: OperationKey,
90    model: &str,
91    stream: bool,
92) -> Result<RequestTarget, EndpointError> {
93    if !target.is_consistent() {
94        return Err(EndpointError::InconsistentOperationKey(target));
95    }
96    use Provider as P;
97    let provider = match target.kind() {
98        OperationKind::ContentGeneration(kind) => {
99            let operation_streams = target.operation() == Operation::StreamGenerateContent;
100            if operation_streams != stream {
101                return Err(EndpointError::StreamMismatch {
102                    operation: target.operation(),
103                    stream,
104                });
105            }
106            return content_target(target.operation(), kind, model, stream);
107        }
108        OperationKind::Provider(provider) => provider,
109    };
110    let request_target = match (target.operation(), provider) {
111        (Operation::ListModels, P::OpenAi | P::Claude) => RequestTarget::get("/v1/models"),
112        (Operation::ListModels, P::Gemini) => RequestTarget::get("/v1beta/models"),
113        (Operation::GetModel, P::OpenAi | P::Claude) => {
114            require_model(target.operation(), provider, model)?;
115            RequestTarget::get(format!("/v1/models/{}", encode_component(model)))
116        }
117        (Operation::GetModel, P::Gemini) => {
118            require_model(target.operation(), provider, model)?;
119            RequestTarget::get(format!("/v1beta/models/{}", encode_component(model)))
120        }
121        (Operation::CountTokens, P::OpenAi) => RequestTarget::post("/v1/responses/input_tokens"),
122        (Operation::CountTokens, P::Claude) => RequestTarget::post("/v1/messages/count_tokens"),
123        (Operation::CountTokens, P::Gemini) => {
124            require_model(target.operation(), provider, model)?;
125            RequestTarget::post(format!(
126                "/v1beta/models/{}:countTokens",
127                encode_component(model)
128            ))
129        }
130        (Operation::CreateEmbedding, P::OpenAi) => RequestTarget::post("/v1/embeddings"),
131        // single-embed form; batch (`:batchEmbedContents`) is a separate op
132        (Operation::CreateEmbedding, P::Gemini) => {
133            require_model(target.operation(), provider, model)?;
134            RequestTarget::post(format!(
135                "/v1beta/models/{}:embedContent",
136                encode_component(model)
137            ))
138        }
139        (Operation::CreateImage, P::OpenAi) => RequestTarget::post("/v1/images/generations"),
140        (Operation::EditImage, P::OpenAi) => RequestTarget::post("/v1/images/edits"),
141        (Operation::WebSearch, P::OpenAi) => RequestTarget::post("/v1/alpha/search"),
142        (Operation::CompactContent, P::OpenAi) => RequestTarget::post("/v1/responses/compact"),
143        (Operation::CreateConversation, P::OpenAi) => RequestTarget::post("/v1/conversations"),
144        (Operation::CreateRealtimeCall, P::OpenAi) => RequestTarget::post("/v1/realtime/calls"),
145        (Operation::ConnectRealtime, P::OpenAi) => {
146            require_model(target.operation(), provider, model)?;
147            RequestTarget {
148                method: HttpMethod::Get,
149                path: "/v1/realtime".to_owned(),
150                query: Some(format!("model={}", encode_component(model))),
151            }
152        }
153        (operation, provider) => {
154            return Err(EndpointError::UnsupportedOperation {
155                operation,
156                provider,
157            });
158        }
159    };
160    Ok(request_target)
161}
162
163/// Content-generation targets (POST; gemini selects the verb by `stream`).
164fn content_target(
165    operation: Operation,
166    kind: ContentGenerationKind,
167    model: &str,
168    stream: bool,
169) -> Result<RequestTarget, EndpointError> {
170    use ContentGenerationKind as K;
171    let target = match kind {
172        K::OpenAiChatCompletions => RequestTarget::post("/v1/chat/completions"),
173        K::OpenAiResponses => RequestTarget::post("/v1/responses"),
174        K::OpenAiResponsesWebSocket if stream => RequestTarget::get("/v1/responses"),
175        K::OpenAiResponsesWebSocket => {
176            return Err(EndpointError::StreamMismatch { operation, stream });
177        }
178        K::ClaudeMessages => RequestTarget::post("/v1/messages"),
179        K::GeminiGenerateContent => {
180            require_model(operation, Provider::Gemini, model)?;
181            let verb = if stream {
182                "streamGenerateContent"
183            } else {
184                "generateContent"
185            };
186            RequestTarget {
187                method: HttpMethod::Post,
188                path: format!("/v1beta/models/{}:{verb}", encode_component(model)),
189                query: stream.then(|| "alt=sse".to_owned()),
190            }
191        }
192    };
193    Ok(target)
194}
195
196fn require_model(
197    operation: Operation,
198    provider: Provider,
199    model: &str,
200) -> Result<(), EndpointError> {
201    if model.is_empty() {
202        Err(EndpointError::MissingModel {
203            operation,
204            provider,
205        })
206    } else {
207        Ok(())
208    }
209}
210
211/// Percent-encode one raw path/query component. Model ids passed to this
212/// module are always raw ids, never provider paths or pre-encoded fragments.
213fn encode_component(value: &str) -> String {
214    const HEX: &[u8; 16] = b"0123456789ABCDEF";
215    let mut encoded = String::with_capacity(value.len());
216    for byte in value.bytes() {
217        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~') {
218            encoded.push(char::from(byte));
219        } else {
220            encoded.push('%');
221            encoded.push(char::from(HEX[usize::from(byte >> 4)]));
222            encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
223        }
224    }
225    encoded
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231
232    #[test]
233    fn provider_endpoint_support_matrix_is_explicit() {
234        use Operation as O;
235        use Provider as P;
236        let rows = [
237            (O::ListModels, [true, true, true]),
238            (O::GetModel, [true, true, true]),
239            (O::CountTokens, [true, true, true]),
240            (O::CreateEmbedding, [true, false, true]),
241            (O::CreateImage, [true, false, false]),
242            (O::EditImage, [true, false, false]),
243            (O::WebSearch, [true, false, false]),
244            (O::CompactContent, [true, false, false]),
245            (O::CreateConversation, [true, false, false]),
246            (O::CreateRealtimeCall, [true, false, false]),
247            (O::ConnectRealtime, [true, false, false]),
248        ];
249        for (operation, supported) in rows {
250            for (provider, expected) in [P::OpenAi, P::Claude, P::Gemini].into_iter().zip(supported)
251            {
252                let result =
253                    request_target(OperationKey::provider(operation, provider), "model", false);
254                assert_eq!(result.is_ok(), expected, "{operation:?} / {provider:?}");
255            }
256        }
257    }
258
259    #[test]
260    fn content_endpoint_support_matrix_is_explicit() {
261        use ContentGenerationKind as K;
262        for kind in [
263            K::OpenAiResponses,
264            K::OpenAiResponsesWebSocket,
265            K::OpenAiChatCompletions,
266            K::ClaudeMessages,
267            K::GeminiGenerateContent,
268        ] {
269            for (operation, stream) in [
270                (Operation::GenerateContent, false),
271                (Operation::StreamGenerateContent, true),
272            ] {
273                let result = request_target(
274                    OperationKey::content_generation(operation, kind),
275                    "model",
276                    stream,
277                );
278                assert_eq!(
279                    result.is_ok(),
280                    kind != K::OpenAiResponsesWebSocket || stream,
281                    "{operation:?} / {kind:?}"
282                );
283            }
284        }
285    }
286
287    #[test]
288    fn rejects_inconsistent_keys_and_stream_flags() {
289        let inconsistent = OperationKey::new_unchecked(
290            Operation::GenerateContent,
291            OperationKind::Provider(Provider::OpenAi),
292        );
293        assert!(matches!(
294            request_target(inconsistent, "model", false),
295            Err(EndpointError::InconsistentOperationKey(_))
296        ));
297
298        let key = OperationKey::content_generation(
299            Operation::StreamGenerateContent,
300            ContentGenerationKind::OpenAiChatCompletions,
301        );
302        assert!(matches!(
303            request_target(key, "model", false),
304            Err(EndpointError::StreamMismatch { .. })
305        ));
306    }
307
308    #[test]
309    fn model_is_a_raw_encoded_component() {
310        let key = OperationKey::provider(Operation::GetModel, Provider::Gemini);
311        let target = request_target(key, "org/model ?", false).unwrap();
312        assert_eq!(target.path, "/v1beta/models/org%2Fmodel%20%3F");
313
314        let key = OperationKey::provider(Operation::ConnectRealtime, Provider::OpenAi);
315        let target = request_target(key, "gpt/a b", false).unwrap();
316        assert_eq!(target.query.as_deref(), Some("model=gpt%2Fa%20b"));
317    }
318}
gproxy_protocol/protocol/endpoint.rs

gproxy_protocol/protocol/
endpoint.rs
