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        (Operation::CreateSpeech, P::OpenAi) => RequestTarget::post("/v1/audio/speech"),
132        (Operation::CreateTranscription, P::OpenAi) => {
133            RequestTarget::post("/v1/audio/transcriptions")
134        }
135        (Operation::CreateTranslation, P::OpenAi) => RequestTarget::post("/v1/audio/translations"),
136        (Operation::Rerank, P::OpenAi) => RequestTarget::post("/v1/rerank"),
137        // single-embed form; batch (`:batchEmbedContents`) is a separate op
138        (Operation::CreateEmbedding, P::Gemini) => {
139            require_model(target.operation(), provider, model)?;
140            RequestTarget::post(format!(
141                "/v1beta/models/{}:embedContent",
142                encode_component(model)
143            ))
144        }
145        (Operation::CreateImage, P::OpenAi) => RequestTarget::post("/v1/images/generations"),
146        (Operation::EditImage, P::OpenAi) => RequestTarget::post("/v1/images/edits"),
147        (Operation::WebSearch, P::OpenAi) => RequestTarget::post("/v1/alpha/search"),
148        (Operation::CompactContent, P::OpenAi) => RequestTarget::post("/v1/responses/compact"),
149        (Operation::CreateConversation, P::OpenAi) => RequestTarget::post("/v1/conversations"),
150        (Operation::CreateRealtimeCall, P::OpenAi) => RequestTarget::post("/v1/realtime/calls"),
151        (Operation::ConnectRealtime, P::OpenAi) => {
152            require_model(target.operation(), provider, model)?;
153            RequestTarget {
154                method: HttpMethod::Get,
155                path: "/v1/realtime".to_owned(),
156                query: Some(format!("model={}", encode_component(model))),
157            }
158        }
159        (operation, provider) => {
160            return Err(EndpointError::UnsupportedOperation {
161                operation,
162                provider,
163            });
164        }
165    };
166    Ok(request_target)
167}
168
169/// Content-generation targets (POST; gemini selects the verb by `stream`).
170fn content_target(
171    operation: Operation,
172    kind: ContentGenerationKind,
173    model: &str,
174    stream: bool,
175) -> Result<RequestTarget, EndpointError> {
176    use ContentGenerationKind as K;
177    let target = match kind {
178        K::OpenAiChatCompletions => RequestTarget::post("/v1/chat/completions"),
179        K::OpenAiResponses => RequestTarget::post("/v1/responses"),
180        K::OpenAiResponsesWebSocket if stream => RequestTarget::get("/v1/responses"),
181        K::OpenAiResponsesWebSocket => {
182            return Err(EndpointError::StreamMismatch { operation, stream });
183        }
184        K::ClaudeMessages => RequestTarget::post("/v1/messages"),
185        K::GeminiGenerateContent => {
186            require_model(operation, Provider::Gemini, model)?;
187            let verb = if stream {
188                "streamGenerateContent"
189            } else {
190                "generateContent"
191            };
192            RequestTarget {
193                method: HttpMethod::Post,
194                path: format!("/v1beta/models/{}:{verb}", encode_component(model)),
195                query: stream.then(|| "alt=sse".to_owned()),
196            }
197        }
198    };
199    Ok(target)
200}
201
202fn require_model(
203    operation: Operation,
204    provider: Provider,
205    model: &str,
206) -> Result<(), EndpointError> {
207    if model.is_empty() {
208        Err(EndpointError::MissingModel {
209            operation,
210            provider,
211        })
212    } else {
213        Ok(())
214    }
215}
216
217/// Percent-encode one raw path/query component. Model ids passed to this
218/// module are always raw ids, never provider paths or pre-encoded fragments.
219fn encode_component(value: &str) -> String {
220    const HEX: &[u8; 16] = b"0123456789ABCDEF";
221    let mut encoded = String::with_capacity(value.len());
222    for byte in value.bytes() {
223        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~') {
224            encoded.push(char::from(byte));
225        } else {
226            encoded.push('%');
227            encoded.push(char::from(HEX[usize::from(byte >> 4)]));
228            encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
229        }
230    }
231    encoded
232}
233
234#[cfg(test)]
235mod tests {
236    use super::*;
237
238    #[test]
239    fn provider_endpoint_support_matrix_is_explicit() {
240        use Operation as O;
241        use Provider as P;
242        let rows = [
243            (O::ListModels, [true, true, true]),
244            (O::GetModel, [true, true, true]),
245            (O::CountTokens, [true, true, true]),
246            (O::CreateEmbedding, [true, false, true]),
247            (O::CreateSpeech, [true, false, false]),
248            (O::CreateTranscription, [true, false, false]),
249            (O::CreateTranslation, [true, false, false]),
250            (O::Rerank, [true, false, false]),
251            (O::CreateImage, [true, false, false]),
252            (O::EditImage, [true, false, false]),
253            (O::WebSearch, [true, false, false]),
254            (O::CompactContent, [true, false, false]),
255            (O::CreateConversation, [true, false, false]),
256            (O::CreateRealtimeCall, [true, false, false]),
257            (O::ConnectRealtime, [true, false, false]),
258        ];
259        for (operation, supported) in rows {
260            for (provider, expected) in [P::OpenAi, P::Claude, P::Gemini].into_iter().zip(supported)
261            {
262                let result =
263                    request_target(OperationKey::provider(operation, provider), "model", false);
264                assert_eq!(result.is_ok(), expected, "{operation:?} / {provider:?}");
265            }
266        }
267    }
268
269    #[test]
270    fn content_endpoint_support_matrix_is_explicit() {
271        use ContentGenerationKind as K;
272        for kind in [
273            K::OpenAiResponses,
274            K::OpenAiResponsesWebSocket,
275            K::OpenAiChatCompletions,
276            K::ClaudeMessages,
277            K::GeminiGenerateContent,
278        ] {
279            for (operation, stream) in [
280                (Operation::GenerateContent, false),
281                (Operation::StreamGenerateContent, true),
282            ] {
283                let result = request_target(
284                    OperationKey::content_generation(operation, kind),
285                    "model",
286                    stream,
287                );
288                assert_eq!(
289                    result.is_ok(),
290                    kind != K::OpenAiResponsesWebSocket || stream,
291                    "{operation:?} / {kind:?}"
292                );
293            }
294        }
295    }
296
297    #[test]
298    fn rejects_inconsistent_keys_and_stream_flags() {
299        let inconsistent = OperationKey::new_unchecked(
300            Operation::GenerateContent,
301            OperationKind::Provider(Provider::OpenAi),
302        );
303        assert!(matches!(
304            request_target(inconsistent, "model", false),
305            Err(EndpointError::InconsistentOperationKey(_))
306        ));
307
308        let key = OperationKey::content_generation(
309            Operation::StreamGenerateContent,
310            ContentGenerationKind::OpenAiChatCompletions,
311        );
312        assert!(matches!(
313            request_target(key, "model", false),
314            Err(EndpointError::StreamMismatch { .. })
315        ));
316    }
317
318    #[test]
319    fn model_is_a_raw_encoded_component() {
320        let key = OperationKey::provider(Operation::GetModel, Provider::Gemini);
321        let target = request_target(key, "org/model ?", false).unwrap();
322        assert_eq!(target.path, "/v1beta/models/org%2Fmodel%20%3F");
323
324        let key = OperationKey::provider(Operation::ConnectRealtime, Provider::OpenAi);
325        let target = request_target(key, "gpt/a b", false).unwrap();
326        assert_eq!(target.query.as_deref(), Some("model=gpt%2Fa%20b"));
327    }
328}
gproxy_protocol/protocol/endpoint.rs

gproxy_protocol/protocol/
endpoint.rs
