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        // Video: resource identifiers (video id, operation name, file id)
151        // travel in the `model` argument slot, like `GetModel`.
152        (Operation::CreateVideo, P::OpenAi) => RequestTarget::post("/v1/videos"),
153        (Operation::ListVideos, P::OpenAi) => RequestTarget::get("/v1/videos"),
154        (Operation::RetrieveVideo, P::OpenAi) => {
155            require_model(target.operation(), provider, model)?;
156            RequestTarget::get(format!("/v1/videos/{}", encode_component(model)))
157        }
158        (Operation::DeleteVideo, P::OpenAi) => {
159            require_model(target.operation(), provider, model)?;
160            RequestTarget {
161                method: HttpMethod::Delete,
162                path: format!("/v1/videos/{}", encode_component(model)),
163                query: None,
164            }
165        }
166        (Operation::DownloadVideoContent, P::OpenAi) => {
167            require_model(target.operation(), provider, model)?;
168            RequestTarget::get(format!("/v1/videos/{}/content", encode_component(model)))
169        }
170        (Operation::RemixVideo, P::OpenAi) => {
171            require_model(target.operation(), provider, model)?;
172            RequestTarget::post(format!("/v1/videos/{}/remix", encode_component(model)))
173        }
174        (Operation::CreateVideoCharacter, P::OpenAi) => {
175            RequestTarget::post("/v1/videos/characters")
176        }
177        (Operation::GetVideoCharacter, P::OpenAi) => {
178            require_model(target.operation(), provider, model)?;
179            RequestTarget::get(format!("/v1/videos/characters/{}", encode_component(model)))
180        }
181        (Operation::EditVideo, P::OpenAi) => RequestTarget::post("/v1/videos/edits"),
182        (Operation::ExtendVideo, P::OpenAi) => RequestTarget::post("/v1/videos/extensions"),
183        (Operation::CreateVideo, P::Gemini) => {
184            require_model(target.operation(), provider, model)?;
185            RequestTarget::post(format!(
186                "/v1beta/models/{}:predictLongRunning",
187                encode_component(model)
188            ))
189        }
190        // The poll target is the operation resource name
191        // (`models/<model>/operations/<id>`); slashes are structural.
192        (Operation::RetrieveVideo, P::Gemini) => {
193            require_model(target.operation(), provider, model)?;
194            RequestTarget::get(format!("/v1beta/{}", model.trim_start_matches('/')))
195        }
196        (Operation::DownloadVideoContent, P::Gemini) => {
197            require_model(target.operation(), provider, model)?;
198            RequestTarget {
199                method: HttpMethod::Get,
200                path: format!("/v1beta/files/{}:download", encode_component(model)),
201                query: Some("alt=media".to_owned()),
202            }
203        }
204        (Operation::CreateRealtimeCall, P::OpenAi) => RequestTarget::post("/v1/realtime/calls"),
205        (Operation::ConnectRealtime, P::OpenAi) => {
206            require_model(target.operation(), provider, model)?;
207            RequestTarget {
208                method: HttpMethod::Get,
209                path: "/v1/realtime".to_owned(),
210                query: Some(format!("model={}", encode_component(model))),
211            }
212        }
213        (operation, provider) => {
214            return Err(EndpointError::UnsupportedOperation {
215                operation,
216                provider,
217            });
218        }
219    };
220    Ok(request_target)
221}
222
223/// Content-generation targets (POST; gemini selects the verb by `stream`).
224fn content_target(
225    operation: Operation,
226    kind: ContentGenerationKind,
227    model: &str,
228    stream: bool,
229) -> Result<RequestTarget, EndpointError> {
230    use ContentGenerationKind as K;
231    let target = match kind {
232        K::OpenAiChatCompletions => RequestTarget::post("/v1/chat/completions"),
233        K::OpenAiResponses => RequestTarget::post("/v1/responses"),
234        K::OpenAiResponsesWebSocket if stream => RequestTarget::get("/v1/responses"),
235        K::OpenAiResponsesWebSocket => {
236            return Err(EndpointError::StreamMismatch { operation, stream });
237        }
238        K::ClaudeMessages => RequestTarget::post("/v1/messages"),
239        K::GeminiGenerateContent => {
240            require_model(operation, Provider::Gemini, model)?;
241            let verb = if stream {
242                "streamGenerateContent"
243            } else {
244                "generateContent"
245            };
246            RequestTarget {
247                method: HttpMethod::Post,
248                path: format!("/v1beta/models/{}:{verb}", encode_component(model)),
249                query: stream.then(|| "alt=sse".to_owned()),
250            }
251        }
252    };
253    Ok(target)
254}
255
256fn require_model(
257    operation: Operation,
258    provider: Provider,
259    model: &str,
260) -> Result<(), EndpointError> {
261    if model.is_empty() {
262        Err(EndpointError::MissingModel {
263            operation,
264            provider,
265        })
266    } else {
267        Ok(())
268    }
269}
270
271/// Percent-encode one raw path/query component. Model ids passed to this
272/// module are always raw ids, never provider paths or pre-encoded fragments.
273fn encode_component(value: &str) -> String {
274    const HEX: &[u8; 16] = b"0123456789ABCDEF";
275    let mut encoded = String::with_capacity(value.len());
276    for byte in value.bytes() {
277        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~') {
278            encoded.push(char::from(byte));
279        } else {
280            encoded.push('%');
281            encoded.push(char::from(HEX[usize::from(byte >> 4)]));
282            encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
283        }
284    }
285    encoded
286}
287
288#[cfg(test)]
289mod tests {
290    use super::*;
291
292    #[test]
293    fn provider_endpoint_support_matrix_is_explicit() {
294        use Operation as O;
295        use Provider as P;
296        let rows = [
297            (O::ListModels, [true, true, true]),
298            (O::GetModel, [true, true, true]),
299            (O::CountTokens, [true, true, true]),
300            (O::CreateEmbedding, [true, false, true]),
301            (O::CreateSpeech, [true, false, false]),
302            (O::CreateTranscription, [true, false, false]),
303            (O::CreateTranslation, [true, false, false]),
304            (O::Rerank, [true, false, false]),
305            (O::CreateImage, [true, false, false]),
306            (O::EditImage, [true, false, false]),
307            (O::WebSearch, [true, false, false]),
308            (O::CompactContent, [true, false, false]),
309            (O::CreateConversation, [true, false, false]),
310            (O::CreateRealtimeCall, [true, false, false]),
311            (O::ConnectRealtime, [true, false, false]),
312            (O::CreateVideo, [true, false, true]),
313            (O::RetrieveVideo, [true, false, true]),
314            (O::ListVideos, [true, false, false]),
315            (O::DeleteVideo, [true, false, false]),
316            (O::DownloadVideoContent, [true, false, true]),
317            (O::RemixVideo, [true, false, false]),
318            (O::CreateVideoCharacter, [true, false, false]),
319            (O::GetVideoCharacter, [true, false, false]),
320            (O::EditVideo, [true, false, false]),
321            (O::ExtendVideo, [true, false, false]),
322        ];
323        for (operation, supported) in rows {
324            for (provider, expected) in [P::OpenAi, P::Claude, P::Gemini].into_iter().zip(supported)
325            {
326                let result =
327                    request_target(OperationKey::provider(operation, provider), "model", false);
328                assert_eq!(result.is_ok(), expected, "{operation:?} / {provider:?}");
329            }
330        }
331    }
332
333    #[test]
334    fn content_endpoint_support_matrix_is_explicit() {
335        use ContentGenerationKind as K;
336        for kind in [
337            K::OpenAiResponses,
338            K::OpenAiResponsesWebSocket,
339            K::OpenAiChatCompletions,
340            K::ClaudeMessages,
341            K::GeminiGenerateContent,
342        ] {
343            for (operation, stream) in [
344                (Operation::GenerateContent, false),
345                (Operation::StreamGenerateContent, true),
346            ] {
347                let result = request_target(
348                    OperationKey::content_generation(operation, kind),
349                    "model",
350                    stream,
351                );
352                assert_eq!(
353                    result.is_ok(),
354                    kind != K::OpenAiResponsesWebSocket || stream,
355                    "{operation:?} / {kind:?}"
356                );
357            }
358        }
359    }
360
361    #[test]
362    fn rejects_inconsistent_keys_and_stream_flags() {
363        let inconsistent = OperationKey::new_unchecked(
364            Operation::GenerateContent,
365            OperationKind::Provider(Provider::OpenAi),
366        );
367        assert!(matches!(
368            request_target(inconsistent, "model", false),
369            Err(EndpointError::InconsistentOperationKey(_))
370        ));
371
372        let key = OperationKey::content_generation(
373            Operation::StreamGenerateContent,
374            ContentGenerationKind::OpenAiChatCompletions,
375        );
376        assert!(matches!(
377            request_target(key, "model", false),
378            Err(EndpointError::StreamMismatch { .. })
379        ));
380    }
381
382    #[test]
383    fn model_is_a_raw_encoded_component() {
384        let key = OperationKey::provider(Operation::GetModel, Provider::Gemini);
385        let target = request_target(key, "org/model ?", false).unwrap();
386        assert_eq!(target.path, "/v1beta/models/org%2Fmodel%20%3F");
387
388        let key = OperationKey::provider(Operation::ConnectRealtime, Provider::OpenAi);
389        let target = request_target(key, "gpt/a b", false).unwrap();
390        assert_eq!(target.query.as_deref(), Some("model=gpt%2Fa%20b"));
391    }
392}
gproxy_protocol/protocol/endpoint.rs

gproxy_protocol/protocol/
endpoint.rs
