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

gproxy_protocol/protocol/
endpoint.rs
