refactor(core): type URL endpoint completion

This commit is contained in:
Yujong Lee 2026-09-09 17:08:02 -07:00
parent 601f45f9a9
commit fa4b13f6eb
22 changed files with 412 additions and 193 deletions

View file

@ -1791,7 +1791,6 @@ dependencies = [
"data-url",
"gcp_auth",
"moka",
"percent-encoding",
"rand 0.8.7",
"reqwest 0.12.28",
"rstest",
@ -1805,6 +1804,7 @@ dependencies = [
"tokio",
"tracing",
"tracing-subscriber",
"url",
"veil",
]

View file

@ -45,6 +45,7 @@ azure_identity = { version = "1.0.0", features = ["tokio"] }
moka = { version = "0.12.16", features = ["future"] }
strum = { version = "0.28.0", features = ["derive"] }
veil = "0.3.0"
url = "2.5.8"
[profile.release]
opt-level = 3

View file

@ -74,7 +74,7 @@ pub(crate) async fn dial_upstream(
api_key: &str,
api_base: Option<&str>,
) -> Result<UpstreamWs, Error> {
let url = OPENAI_REALTIME_CONFIG.complete_url(api_base, model);
let url = OPENAI_REALTIME_CONFIG.complete_url(api_base, model)?;
let mut request = url
.as_str()

View file

@ -130,7 +130,7 @@ async fn dial_upstream(
api_key: &str,
api_base: Option<&str>,
) -> Result<ResponsesUpstreamWs, Error> {
let url = OPENAI_RESPONSES_WS_CONFIG.complete_url(api_base, model);
let url = OPENAI_RESPONSES_WS_CONFIG.complete_url(api_base, model)?;
let mut request = url
.as_str()
.into_client_request()

View file

@ -22,7 +22,6 @@ reqwest.workspace = true
serde.workspace = true
serde_json.workspace = true
serde_path_to_error = "0.1"
percent-encoding = "2.3"
tokio.workspace = true
thiserror.workspace = true
strum.workspace = true
@ -31,6 +30,7 @@ tracing.workspace = true
tracing-subscriber = { workspace = true, optional = true }
sha2.workspace = true
veil.workspace = true
url.workspace = true
aws-config = { version = "1.9.0", default-features = false, features = ["rustls", "rt-tokio"], optional = true }
aws-credential-types = { version = "1.3.0", features = ["hardcoded-credentials"], optional = true }
aws-sdk-sts = { version = "1.108.0", default-features = false, features = ["rustls", "rt-tokio"], optional = true }

View file

@ -71,15 +71,6 @@ where
<Option<T> as serde::Deserialize>::deserialize(deserializer).map(Some)
}
pub(crate) fn encode_query_value(value: &str) -> String {
const QUERY_VALUE: &percent_encoding::AsciiSet = &percent_encoding::NON_ALPHANUMERIC
.remove(b'-')
.remove(b'.')
.remove(b'_')
.remove(b'~');
percent_encoding::utf8_percent_encode(value, QUERY_VALUE).to_string()
}
#[cfg(test)]
mod tests {
use super::*;

View file

@ -15,5 +15,6 @@ pub mod realtime;
pub mod responses;
pub mod router;
pub mod routing_utils;
mod url_utils;
pub use error::{AuthError, Error};

View file

@ -10,19 +10,14 @@ use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument, OcrRequestFormat};
use crate::ocr::wire::DecodedOcrResponse;
use crate::providers::azure_ai::auth;
use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, utf8_percent_encode};
use crate::url_utils::ApiUrl;
fn encode_model_id(model: &str) -> Result<String, OcrRequestError> {
const PATH_SEGMENT: &AsciiSet = &NON_ALPHANUMERIC
.remove(b'-')
.remove(b'_')
.remove(b'.')
.remove(b'~');
fn model_id(model: &str) -> Result<&str, OcrRequestError> {
let model = model.rsplit('/').next().unwrap_or(model);
if matches!(model, "." | "..") {
return Err(OcrRequestError::DotModel);
}
Ok(utf8_percent_encode(model, PATH_SEGMENT).to_string())
Ok(model)
}
#[derive(Clone, Debug)]
@ -51,8 +46,14 @@ impl OcrIntegration for AzureMistral {
env_lookup,
)
.await?;
let path: Vec<&str> = AZURE_AI_OCR_PATH.trim_matches('/').split('/').collect();
Ok(PreparedOcrBackend {
url: format!("{}{AZURE_AI_OCR_PATH}", base.trim_end_matches('/')),
url: ApiUrl::parse(&base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers,
})
}
@ -102,20 +103,26 @@ impl OcrIntegration for AzureDocumentIntelligence {
connection.api_base.as_deref(),
env_lookup,
)?;
let mut url = format!(
"{}/documentintelligence/documentModels/{}:analyze?api-version={}",
endpoint.trim_end_matches('/'),
encode_model_id(model)?,
AZURE_DI_API_VERSION
);
if let Some(pages) = &params.pages {
url.push_str("&pages=");
url.push_str(&pages.0);
}
if let Some(features) = &params.features {
url.push_str("&features=");
url.push_str(&features.0);
}
let model = format!("{}:analyze", model_id(model)?);
let url = ApiUrl::parse(&endpoint)
.and_then(|url| url.complete_path(&["documentintelligence", "documentModels", &model]))
.map(|url| {
url.append_query_pairs(
[("api-version", AZURE_DI_API_VERSION)]
.into_iter()
.chain(params.pages.iter().map(|pages| ("pages", pages.0.as_str())))
.chain(
params
.features
.iter()
.map(|features| ("features", features.0.as_str())),
),
)
.into_string()
})
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
let headers = auth::authenticate_document_intelligence(
connection.extra_headers.clone(),
connection.api_key.as_deref(),

View file

@ -1,21 +1,25 @@
use crate::constants::MISTRAL_OCR_API_BASE;
use crate::ocr::backends::{BackendConfig, OcrBackend, OcrIntegration, PreparedOcrBackend};
use crate::ocr::error::OcrError;
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::providers::mistral::auth;
use crate::url_utils::ApiUrl;
pub fn complete_url(api_base: Option<&str>) -> String {
pub fn complete_url(api_base: Option<&str>) -> Result<String, OcrError> {
let base = api_base
.map(str::trim)
.filter(|base| !base.is_empty())
.unwrap_or(MISTRAL_OCR_API_BASE)
.trim_end_matches('/');
if base.ends_with("/v1") {
format!("{base}/ocr")
} else {
format!("{base}/v1/ocr")
}
.unwrap_or(MISTRAL_OCR_API_BASE);
ApiUrl::parse(base)
.and_then(|url| url.complete_path(&["v1", "ocr"]))
.map(|url| url.into_string())
.map_err(|_| {
OcrRequestError::RequestField {
path: "api_base".into(),
}
.into()
})
}
#[derive(Clone, Debug)]
@ -41,7 +45,7 @@ impl OcrIntegration for MistralDirect {
env_lookup,
)?;
Ok(PreparedOcrBackend {
url: complete_url(connection.api_base.as_deref()),
url: complete_url(connection.api_base.as_deref())?,
headers,
})
}

View file

@ -8,6 +8,7 @@ use crate::ocr::formats::reducto::{
};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::providers::reducto::auth;
use crate::url_utils::ApiUrl;
#[derive(Clone, Debug)]
pub struct ReductoBackend;
@ -17,12 +18,20 @@ impl OcrBackend for ReductoBackend {
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::Reducto;
}
pub fn normalize_api_base(api_base: Option<&str>) -> &str {
api_base
pub fn complete_url(api_base: Option<&str>, path: &str) -> Result<String, OcrError> {
let base = api_base
.map(str::trim)
.filter(|base| !base.is_empty())
.unwrap_or(REDUCTO_OCR_API_BASE)
.trim_end_matches('/')
.unwrap_or(REDUCTO_OCR_API_BASE);
ApiUrl::parse(base)
.and_then(|url| url.complete_path(&[path]))
.map(|url| url.into_string())
.map_err(|_| {
OcrRequestError::RequestField {
path: "api_base".into(),
}
.into()
})
}
async fn prepare_reducto_document(
@ -44,10 +53,7 @@ async fn prepare_reducto_document(
.map_err(|_| OcrRequestError::InvalidDataUri)?;
let mut builder = client
.provider_http()
.post(format!(
"{}/upload",
normalize_api_base(connection.api_base.as_deref())
))
.post(complete_url(connection.api_base.as_deref(), "upload")?)
.multipart(reqwest::multipart::Form::new().part("file", part))
.timeout(connection.timeout);
for (name, value) in headers {
@ -97,10 +103,7 @@ macro_rules! impl_reducto_backend {
env_lookup,
)?;
Ok(PreparedOcrBackend {
url: format!(
"{}/parse",
normalize_api_base(connection.api_base.as_deref())
),
url: complete_url(connection.api_base.as_deref(), "parse")?,
headers,
})
}

View file

@ -5,6 +5,7 @@ use crate::ocr::formats::deepseek::{DeepSeekOcrFormat, types::DeepSeekOcrParams}
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::providers::vertex_ai::auth::{self, VertexAuthInputs};
use crate::url_utils::ApiUrl;
async fn authenticate(
connection: &OcrConnection,
@ -47,16 +48,26 @@ impl OcrIntegration for VertexMistral {
let authentication = authenticate(connection, config, env_lookup).await?;
let location = location(config, env_lookup);
let default_base = format!("https://{location}-aiplatform.googleapis.com");
let base = connection
.api_base
.as_deref()
.unwrap_or(&default_base)
.trim_end_matches('/');
let base = connection.api_base.as_deref().unwrap_or(&default_base);
let prediction = format!("{model}:rawPredict");
let path = [
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"publishers",
"mistralai",
"models",
prediction.as_str(),
];
Ok(PreparedOcrBackend {
url: format!(
"{base}/v1/projects/{}/locations/{location}/publishers/mistralai/models/{model}:rawPredict",
authentication.project_id
),
url: ApiUrl::parse(base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| crate::ocr::error::OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers: authentication.headers,
})
}
@ -107,13 +118,26 @@ impl OcrIntegration for VertexDeepSeek {
let base = connection
.api_base
.as_deref()
.unwrap_or(VERTEX_DEEPSEEK_API_BASE)
.trim_end_matches('/');
.unwrap_or(VERTEX_DEEPSEEK_API_BASE);
Ok(PreparedOcrBackend {
url: format!(
"{base}/v1/projects/{}/locations/{location}/endpoints/openapi/chat/completions",
authentication.project_id
),
url: ApiUrl::parse(base)
.and_then(|url| {
url.complete_path(&[
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"endpoints",
"openapi",
"chat",
"completions",
])
})
.map(|url| url.into_string())
.map_err(|_| crate::ocr::error::OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers: authentication.headers,
})
}

View file

@ -129,7 +129,7 @@ impl ChatCompletionsProviderConfig for AnthropicChatCompletionsConfig {
_optional_params: &Map<String, Value>,
env_lookup: &dyn Fn(&str) -> Option<String>,
) -> Result<String, Error> {
Ok(complete_anthropic_url(api_base, env_lookup))
complete_anthropic_url(api_base, env_lookup)
}
fn auth(

View file

@ -2,11 +2,11 @@ use crate::auth::CredentialPlacement;
use crate::auth::error::MissingCredential;
use crate::error::{AuthError, Error};
use crate::messages::transformation::AnthropicMessagesProviderConfig;
use crate::url_utils::ApiUrl;
const ANTHROPIC_API_KEY_ENV: &str = "ANTHROPIC_API_KEY";
const ANTHROPIC_API_BASE_ENV: &str = "ANTHROPIC_API_BASE";
const DEFAULT_ANTHROPIC_API_BASE: &str = "https://api.anthropic.com";
const MESSAGES_PATH_SUFFIX: &str = "/v1/messages";
pub struct AnthropicMessagesConfig;
@ -31,17 +31,16 @@ pub fn resolve_anthropic_api_key(
pub fn complete_anthropic_url(
api_base: Option<&str>,
env_lookup: &dyn Fn(&str) -> Option<String>,
) -> String {
) -> Result<String, Error> {
let api_base = non_empty(api_base)
.map(str::to_string)
.or_else(|| env_lookup(ANTHROPIC_API_BASE_ENV).filter(|value| !value.trim().is_empty()))
.unwrap_or_else(|| DEFAULT_ANTHROPIC_API_BASE.to_string());
let api_base = api_base.trim_end_matches('/');
if api_base.ends_with(MESSAGES_PATH_SUFFIX) {
return api_base.to_string();
}
format!("{api_base}{MESSAGES_PATH_SUFFIX}")
ApiUrl::parse(&api_base)
.and_then(|url| url.complete_path(&["v1", "messages"]))
.map(|url| url.into_string())
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))
}
impl AnthropicMessagesProviderConfig for AnthropicMessagesConfig {
@ -52,7 +51,7 @@ impl AnthropicMessagesProviderConfig for AnthropicMessagesConfig {
_model: &str,
env_lookup: &dyn Fn(&str) -> Option<String>,
) -> Result<String, Error> {
Ok(complete_anthropic_url(api_base, env_lookup))
complete_anthropic_url(api_base, env_lookup)
}
fn resolve_api_key(
@ -75,7 +74,7 @@ mod tests {
#[test]
fn url_defaults_to_public_anthropic_endpoint() {
assert_eq!(
complete_anthropic_url(None, &|_| None),
complete_anthropic_url(None, &|_| None).expect("url builds"),
"https://api.anthropic.com/v1/messages"
);
}
@ -83,7 +82,7 @@ mod tests {
#[test]
fn url_appends_messages_suffix_to_custom_base() {
assert_eq!(
complete_anthropic_url(Some("https://proxy.internal"), &|_| None),
complete_anthropic_url(Some("https://proxy.internal"), &|_| None).expect("url builds"),
"https://proxy.internal/v1/messages"
);
}
@ -91,18 +90,28 @@ mod tests {
#[test]
fn url_leaves_complete_messages_endpoint_untouched() {
assert_eq!(
complete_anthropic_url(Some("https://proxy.internal/v1/messages"), &|_| None),
complete_anthropic_url(Some("https://proxy.internal/v1/messages"), &|_| None)
.expect("url builds"),
"https://proxy.internal/v1/messages"
);
}
#[test]
fn url_completes_path_before_existing_query() {
assert_eq!(
complete_anthropic_url(Some("https://proxy.internal/v1?tenant=a"), &|_| None)
.expect("url builds"),
"https://proxy.internal/v1/messages?tenant=a"
);
}
#[test]
fn url_falls_back_to_env_base() {
let with_env = |key: &str| {
(key == ANTHROPIC_API_BASE_ENV).then(|| "https://env.anthropic".to_string())
};
assert_eq!(
complete_anthropic_url(Some(" "), &with_env),
complete_anthropic_url(Some(" "), &with_env).expect("url builds"),
"https://env.anthropic/v1/messages"
);
}
@ -125,7 +134,7 @@ mod tests {
}
#[test]
fn auth_strategy_and_default_headers_match_anthropic() {
fn credential_placement_and_default_headers_match_anthropic() {
assert_eq!(
ANTHROPIC_MESSAGES_CONFIG
.credential_placement()

View file

@ -9,12 +9,11 @@ use crate::messages::types::{
use crate::providers::anthropic::messages::transformation::{
ANTHROPIC_MESSAGES_CONFIG, AnthropicMessagesConfig, non_empty,
};
use crate::url_utils::ApiUrl;
use serde_json::{Map, Value};
const AZURE_API_KEY_ENV: &str = "AZURE_API_KEY";
const AZURE_API_BASE_ENV: &str = "AZURE_API_BASE";
const ANTHROPIC_PATH_SEGMENT: &str = "/anthropic";
const MESSAGES_PATH_SUFFIX: &str = "/v1/messages";
const SYSTEM_ROLE: &str = "system";
const TEXT_BLOCK_TYPE: &str = "text";
@ -50,17 +49,13 @@ pub fn complete_azure_anthropic_url(
MissingCredential::AzureApiBase,
)))?;
let api_base = api_base.trim_end_matches('/');
if api_base.ends_with(MESSAGES_PATH_SUFFIX) {
return Ok(api_base.to_string());
}
let with_anthropic = match api_base.split_once(ANTHROPIC_PATH_SEGMENT) {
Some((prefix, _)) => format!("{prefix}{ANTHROPIC_PATH_SEGMENT}"),
None => format!("{api_base}{ANTHROPIC_PATH_SEGMENT}"),
};
Ok(format!("{with_anthropic}{MESSAGES_PATH_SUFFIX}"))
ApiUrl::parse(&api_base)
.and_then(|url| url.truncate_path_after("anthropic"))
.and_then(|url| {
url.complete_path_with_aliases(&["anthropic", "v1", "messages"], &[&["v1", "messages"]])
})
.map(|url| url.into_string())
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))
}
fn strip_scope_from_block(block: &mut ContentBlock) {
@ -285,7 +280,7 @@ mod tests {
}
#[test]
fn auth_strategy_is_x_api_key() {
fn credential_placement_is_x_api_key() {
assert_eq!(
AZURE_ANTHROPIC_MESSAGES_CONFIG
.credential_placement()

View file

@ -12,6 +12,7 @@ use crate::audio_transcription::types::{
TranscriptionAudio, TranscriptionParams,
};
use crate::error::Error;
use crate::url_utils::ApiUrl;
pub use super::aws_base::{aws_auth_config, bedrock_model_id_and_region, resolve_bedrock_region};
use super::constants::BEDROCK_RUNTIME_ENDPOINT_TEMPLATE;
@ -102,10 +103,10 @@ impl AudioTranscriptionProviderConfig for BedrockAudioTranscriptionConfig {
.filter(|value| !value.is_empty())
.map(str::to_string)
.unwrap_or_else(|| BEDROCK_RUNTIME_ENDPOINT_TEMPLATE.replace("{region}", &region));
Ok(format!(
"{}/model/{model_id}/converse",
endpoint.trim_end_matches('/')
))
ApiUrl::parse(&endpoint)
.and_then(|url| url.complete_path(&["model", &model_id, "converse"]))
.map(|url| url.into_string())
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))
}
fn auth(

View file

@ -16,6 +16,7 @@ use crate::chat_completions::types::{
ChatCompletionsUsage, ChatMessage, ChatMessageContent,
};
use crate::error::Error;
use crate::url_utils::ApiUrl;
use super::super::aws_base::{bedrock_model_id_and_region, resolve_bedrock_region};
use super::super::constants::{AWS_BEARER_TOKEN_BEDROCK, BEDROCK_RUNTIME_ENDPOINT_TEMPLATE};
@ -47,8 +48,6 @@ const CONFIG_PARAMS: &[&str] = &[
AWS_BEDROCK_RUNTIME_ENDPOINT,
];
const CONVERSE_PATH_SUFFIX: &str = "/converse";
pub struct BedrockChatCompletionsConfig;
pub const BEDROCK_CHAT_COMPLETIONS_CONFIG: BedrockChatCompletionsConfig =
@ -88,14 +87,12 @@ impl ChatCompletionsProviderConfig for BedrockChatCompletionsConfig {
.filter(|value| !value.is_empty())
.map(str::to_string)
.unwrap_or_else(|| BEDROCK_RUNTIME_ENDPOINT_TEMPLATE.replace("{region}", &region));
let endpoint = endpoint.trim_end_matches('/');
// A host that already built the full Converse URL (LiteLLM's Python
// path encodes the model id itself) passes it through untouched, the
// way the Anthropic config leaves a complete `/v1/messages` URL alone.
if endpoint.ends_with(CONVERSE_PATH_SUFFIX) {
return Ok(endpoint.to_string());
}
Ok(format!("{endpoint}/model/{model_id}{CONVERSE_PATH_SUFFIX}"))
ApiUrl::parse(&endpoint)
.and_then(|url| {
url.complete_path_with_aliases(&["model", &model_id, "converse"], &[&["converse"]])
})
.map(|url| url.into_string())
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))
}
fn auth(

View file

@ -1,6 +1,7 @@
use crate::Error;
use crate::realtime::transformation::RealtimeProviderConfig;
use crate::realtime::types::{RealtimeEvent, RealtimeTransformResult};
use crate::url_utils::ApiUrl;
/// Default OpenAI API base, used when the caller does not override `api_base`.
pub const OPENAI_REALTIME_DEFAULT_API_BASE: &str = "https://api.openai.com";
@ -18,28 +19,22 @@ pub const OPENAI_REALTIME_PATH: &str = "/v1/realtime";
/// a deliberate hardening over Python's `_construct_url`, which would emit a
/// scheme-less URL here). A trailing `/` is trimmed before the path and
/// `?model=<encoded>` are appended.
pub fn complete_url(api_base: Option<&str>, model: &str) -> String {
pub fn complete_url(api_base: Option<&str>, model: &str) -> Result<String, Error> {
let base = api_base
.map(str::trim)
.filter(|base| !base.is_empty())
.unwrap_or(OPENAI_REALTIME_DEFAULT_API_BASE);
let base = if let Some(rest) = base.strip_prefix("https://") {
format!("wss://{rest}")
} else if let Some(rest) = base.strip_prefix("http://") {
format!("ws://{rest}")
} else if base.starts_with("wss://") || base.starts_with("ws://") {
base.to_string()
} else {
format!("wss://{base}")
};
let base = base.trim_end_matches('/');
format!(
"{base}{OPENAI_REALTIME_PATH}?model={}",
crate::http_utils::encode_query_value(model)
)
let url = ApiUrl::parse_with_default_scheme(base, "wss")
.and_then(|url| match url.scheme() {
"https" => url.with_scheme("wss"),
"http" => url.with_scheme("ws"),
"wss" | "ws" => Ok(url),
_ => url.with_scheme("wss"),
})
.and_then(|url| url.complete_path(&["v1", "realtime"]))
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))?;
Ok(url.append_query_pair("model", model).into_string())
}
pub struct OpenAiRealtimeConfig;
@ -47,7 +42,7 @@ pub struct OpenAiRealtimeConfig;
pub const OPENAI_REALTIME_CONFIG: OpenAiRealtimeConfig = OpenAiRealtimeConfig;
impl RealtimeProviderConfig for OpenAiRealtimeConfig {
fn complete_url(&self, api_base: Option<&str>, model: &str) -> String {
fn complete_url(&self, api_base: Option<&str>, model: &str) -> Result<String, Error> {
complete_url(api_base, model)
}
@ -89,7 +84,7 @@ mod tests {
#[test]
fn complete_url_defaults_to_openai_wss() {
assert_eq!(
complete_url(None, "gpt-4o-realtime-preview"),
complete_url(None, "gpt-4o-realtime-preview").expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview"
);
}
@ -97,7 +92,7 @@ mod tests {
#[test]
fn complete_url_blank_base_uses_default() {
assert_eq!(
complete_url(Some(" "), "gpt-4o-realtime-preview"),
complete_url(Some(" "), "gpt-4o-realtime-preview").expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview"
);
}
@ -105,7 +100,8 @@ mod tests {
#[test]
fn complete_url_swaps_http_to_ws() {
assert_eq!(
complete_url(Some("http://localhost:8080"), "gpt-4o-realtime-preview"),
complete_url(Some("http://localhost:8080"), "gpt-4o-realtime-preview")
.expect("url builds"),
"ws://localhost:8080/v1/realtime?model=gpt-4o-realtime-preview"
);
}
@ -113,7 +109,8 @@ mod tests {
#[test]
fn complete_url_dedupes_trailing_slash() {
assert_eq!(
complete_url(Some("https://api.openai.com/"), "gpt-4o-realtime-preview"),
complete_url(Some("https://api.openai.com/"), "gpt-4o-realtime-preview")
.expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview"
);
}
@ -121,7 +118,8 @@ mod tests {
#[test]
fn complete_url_custom_base() {
assert_eq!(
complete_url(Some("https://oai.azure.example"), "gpt-4o-realtime-preview"),
complete_url(Some("https://oai.azure.example"), "gpt-4o-realtime-preview")
.expect("url builds"),
"wss://oai.azure.example/v1/realtime?model=gpt-4o-realtime-preview"
);
}
@ -129,7 +127,7 @@ mod tests {
#[test]
fn complete_url_preserves_existing_wss_scheme() {
assert_eq!(
complete_url(Some("wss://api.openai.com"), "gpt-realtime"),
complete_url(Some("wss://api.openai.com"), "gpt-realtime").expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt-realtime"
);
}
@ -137,7 +135,7 @@ mod tests {
#[test]
fn complete_url_bare_host_defaults_to_wss() {
assert_eq!(
complete_url(Some("api.openai.com"), "gpt-realtime"),
complete_url(Some("api.openai.com"), "gpt-realtime").expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt-realtime"
);
}
@ -145,8 +143,8 @@ mod tests {
#[test]
fn complete_url_percent_encodes_model_space() {
assert_eq!(
complete_url(None, "gpt 4o"),
"wss://api.openai.com/v1/realtime?model=gpt%204o"
complete_url(None, "gpt 4o").expect("url builds"),
"wss://api.openai.com/v1/realtime?model=gpt+4o"
);
}

View file

@ -4,7 +4,7 @@ use crate::realtime::types::{RealtimeEvent, RealtimeTransformResult};
pub trait RealtimeProviderConfig: Sync {
/// Build the upstream WebSocket URL (e.g. `wss://api.openai.com/v1/realtime?model=…`).
/// Pure string construction only — no network, no env.
fn complete_url(&self, api_base: Option<&str>, model: &str) -> String;
fn complete_url(&self, api_base: Option<&str>, model: &str) -> Result<String, Error>;
/// Transform a client → backend event before it is forwarded upstream.
fn transform_request(

View file

@ -1,13 +1,14 @@
use crate::Error;
use crate::constants::{OPENAI_RESPONSES_DEFAULT_API_BASE, OPENAI_RESPONSES_PATH};
use crate::constants::OPENAI_RESPONSES_DEFAULT_API_BASE;
use crate::responses::types::{ResponsesWsEvent, ResponsesWsEventType, ResponsesWsTransformResult};
use crate::url_utils::ApiUrl;
pub trait ResponsesWebSocketProviderConfig: Sync {
fn model_in_websocket_url(&self) -> bool {
true
}
fn complete_url(&self, api_base: Option<&str>, model: &str) -> String {
fn complete_url(&self, api_base: Option<&str>, model: &str) -> Result<String, Error> {
complete_url(api_base, model, self.model_in_websocket_url())
}
@ -24,43 +25,27 @@ pub trait ResponsesWebSocketProviderConfig: Sync {
) -> Result<ResponsesWsTransformResult, Error>;
}
pub fn complete_url(api_base: Option<&str>, model: &str, model_in_websocket_url: bool) -> String {
pub fn complete_url(
api_base: Option<&str>,
model: &str,
model_in_websocket_url: bool,
) -> Result<String, Error> {
let base = api_base
.map(str::trim)
.filter(|value| !value.is_empty())
.unwrap_or(OPENAI_RESPONSES_DEFAULT_API_BASE);
let (base_without_query, query) = base
.split_once('?')
.map_or((base, None), |(value, query)| (value, Some(query)));
let response_url = format!(
"{}{}",
base_without_query.trim_end_matches('/'),
OPENAI_RESPONSES_PATH
);
let scheme_flipped = if let Some(rest) = response_url.strip_prefix("https://") {
format!("wss://{rest}")
} else if let Some(rest) = response_url.strip_prefix("http://") {
format!("ws://{rest}")
} else {
response_url
};
let url = query.map_or(scheme_flipped.clone(), |value| {
format!("{scheme_flipped}?{value}")
});
if !model_in_websocket_url
|| query.is_some_and(|value| {
value
.split('&')
.any(|part| part.split('=').next() == Some("model"))
let url = ApiUrl::parse(base)
.and_then(|url| match url.scheme() {
"https" => url.with_scheme("wss"),
"http" => url.with_scheme("ws"),
_ => Ok(url),
})
{
return url;
.and_then(|url| url.complete_path(&["responses"]))
.map_err(|error| Error::InvalidRequest(format!("invalid api_base: {error}")))?;
if !model_in_websocket_url || url.has_query_key("model") {
return Ok(url.into_string());
}
format!(
"{url}{}model={}",
if query.is_some() { "&" } else { "?" },
crate::http_utils::encode_query_value(model)
)
Ok(url.append_query_pair("model", model).into_string())
}
pub fn enforce_model(event: &ResponsesWsEvent, model: &str) -> ResponsesWsEvent {
@ -115,21 +100,32 @@ mod tests {
#[test]
fn url_construction_matches_python_defaults_and_query_behavior() {
assert_eq!(
complete_url(None, "gpt-5", true),
complete_url(None, "gpt-5", true).expect("url builds"),
"wss://api.openai.com/v1/responses?model=gpt-5"
);
assert_eq!(
complete_url(Some("http://localhost:8080/"), "gpt 5", true),
"ws://localhost:8080/responses?model=gpt%205"
complete_url(Some("http://localhost:8080/"), "gpt 5", true).expect("url builds"),
"ws://localhost:8080/responses?model=gpt+5"
);
assert_eq!(
complete_url(Some("https://example.test/v1?foo=bar"), "gpt-5", true),
complete_url(Some("https://example.test/v1?foo=bar"), "gpt-5", true)
.expect("url builds"),
"wss://example.test/v1/responses?foo=bar&model=gpt-5"
);
assert_eq!(
complete_url(Some("https://example.test?model=existing"), "gpt-5", true),
complete_url(Some("https://example.test?model=existing"), "gpt-5", true)
.expect("url builds"),
"wss://example.test/responses?model=existing"
);
assert_eq!(
complete_url(
Some("https://example.test/v1/responses?foo=bar"),
"gpt-5",
true,
)
.expect("url builds"),
"wss://example.test/v1/responses?foo=bar&model=gpt-5"
);
}
#[test]

View file

@ -0,0 +1,178 @@
use std::marker::PhantomData;
use thiserror::Error;
use url::Url;
#[derive(Debug, Error)]
pub(crate) enum ApiUrlError {
#[error("invalid URL: {0}")]
Parse(#[from] url::ParseError),
#[error("URL cannot be used as a base")]
CannotBeBase,
#[error("unsupported URL scheme: {0}")]
Scheme(String),
}
pub(crate) struct Base;
pub(crate) struct Complete;
pub(crate) struct ApiUrl<State> {
url: Url,
state: PhantomData<State>,
}
impl ApiUrl<Base> {
pub(crate) fn parse(value: &str) -> Result<Self, ApiUrlError> {
Ok(Self {
url: Url::parse(value.trim())?,
state: PhantomData,
})
}
pub(crate) fn parse_with_default_scheme(
value: &str,
default_scheme: &str,
) -> Result<Self, ApiUrlError> {
let value = value.trim();
if value.contains("://") {
return Self::parse(value);
}
Self::parse(&format!("{default_scheme}://{value}"))
}
pub(crate) fn with_scheme(mut self, scheme: &str) -> Result<Self, ApiUrlError> {
self.url
.set_scheme(scheme)
.map_err(|()| ApiUrlError::Scheme(scheme.to_string()))?;
Ok(self)
}
pub(crate) fn scheme(&self) -> &str {
self.url.scheme()
}
pub(crate) fn truncate_path_after(mut self, segment: &str) -> Result<Self, ApiUrlError> {
let segments: Vec<String> = self
.url
.path_segments()
.ok_or(ApiUrlError::CannotBeBase)?
.filter(|value| !value.is_empty())
.map(str::to_string)
.collect();
let Some(index) = segments.iter().position(|value| value == segment) else {
return Ok(self);
};
self.url
.path_segments_mut()
.map_err(|()| ApiUrlError::CannotBeBase)?
.clear()
.extend(segments[..=index].iter().map(String::as_str));
Ok(self)
}
pub(crate) fn complete_path(self, target: &[&str]) -> Result<ApiUrl<Complete>, ApiUrlError> {
self.complete_path_with_aliases(target, &[])
}
pub(crate) fn complete_path_with_aliases(
mut self,
target: &[&str],
aliases: &[&[&str]],
) -> Result<ApiUrl<Complete>, ApiUrlError> {
let existing: Vec<String> = self
.url
.path_segments()
.ok_or(ApiUrlError::CannotBeBase)?
.filter(|segment| !segment.is_empty())
.map(str::to_string)
.collect();
let ends_with = |suffix: &[&str]| {
existing.len() >= suffix.len()
&& existing[existing.len() - suffix.len()..]
.iter()
.map(String::as_str)
.eq(suffix.iter().copied())
};
let already_complete = aliases.iter().any(|suffix| ends_with(suffix));
let overlap = if already_complete {
target.len()
} else {
(0..=existing.len().min(target.len()))
.rev()
.find(|&length| {
existing[existing.len() - length..]
.iter()
.map(String::as_str)
.eq(target[..length].iter().copied())
})
.unwrap_or(0)
};
self.url
.path_segments_mut()
.map_err(|()| ApiUrlError::CannotBeBase)?
.pop_if_empty()
.extend(target[overlap..].iter().copied());
Ok(ApiUrl {
url: self.url,
state: PhantomData,
})
}
}
impl ApiUrl<Complete> {
pub(crate) fn has_query_key(&self, key: &str) -> bool {
self.url.query_pairs().any(|(name, _)| name == key)
}
pub(crate) fn append_query_pair(mut self, key: &str, value: &str) -> Self {
self.url.query_pairs_mut().append_pair(key, value);
self
}
pub(crate) fn append_query_pairs<'a>(
mut self,
pairs: impl IntoIterator<Item = (&'a str, &'a str)>,
) -> Self {
self.url.query_pairs_mut().extend_pairs(pairs);
self
}
pub(crate) fn into_string(self) -> String {
self.url.into()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn completion_appends_only_the_missing_path_suffix() {
for (base, expected) in [
("https://example.test", "https://example.test/v1/ocr"),
("https://example.test/v1", "https://example.test/v1/ocr"),
("https://example.test/v1/ocr", "https://example.test/v1/ocr"),
] {
let actual = ApiUrl::parse(base)
.and_then(|url| url.complete_path(&["v1", "ocr"]))
.map(|url| url.into_string())
.expect("url builds");
assert_eq!(actual, expected);
}
}
#[test]
fn completion_places_paths_before_queries_and_encodes_query_values() {
let actual = ApiUrl::parse("https://example.test/v1?tenant=a")
.and_then(|url| url.complete_path(&["v1", "ocr"]))
.map(|url| {
url.append_query_pair("model", "name with spaces")
.into_string()
})
.expect("url builds");
assert_eq!(
actual,
"https://example.test/v1/ocr?tenant=a&model=name+with+spaces"
);
}
}

View file

@ -31,6 +31,13 @@ async fn prepared_url(
.map(|prepared| prepared.url)
}
fn query_value(url: &str, key: &str) -> Option<String> {
url::Url::parse(url)
.expect("prepared URL parses")
.query_pairs()
.find_map(|(name, value)| (name == key).then(|| value.into_owned()))
}
#[rstest]
#[case(json!([2,0,0,1]), "1,2,3")]
#[case(json!("1-3, 5"), "1-3,5")]
@ -43,7 +50,7 @@ async fn document_intelligence_url_normalizes_zero_based_pages(
) {
let mapped = params(&AZURE_DOCUMENT_INTELLIGENCE, json!({"pages":pages}));
let url = prepared_url("prebuilt-read", &mapped).await.unwrap();
assert!(url.ends_with(&format!("&pages={expected}")));
assert_eq!(query_value(&url, "pages").as_deref(), Some(expected));
}
#[rstest]
#[case(json!([true]))]
@ -91,12 +98,8 @@ async fn document_intelligence_page_mapping_omits_empty_list() {
#[tokio::test]
async fn document_intelligence_maps_features(#[case] features: Value, #[case] expected: &str) {
let mapped = params(&AZURE_DOCUMENT_INTELLIGENCE, json!({"features":features}));
assert!(
prepared_url("prebuilt-read", &mapped)
.await
.unwrap()
.ends_with(&format!("&features={expected}"))
);
let url = prepared_url("prebuilt-read", &mapped).await.unwrap();
assert_eq!(query_value(&url, "features").as_deref(), Some(expected));
}
#[rstest]
#[case(json!(["languages,ocr"]))]
@ -329,7 +332,7 @@ async fn polling_forwards_subscription_or_bearer_and_preserves_native(#[case] be
Some(operation().as_object().unwrap().clone())
);
let seen = requests.lock().unwrap();
assert!(seen[0].contains("&pages=1,3"));
assert!(seen[0].contains("&pages=1%2C3"));
for poll in &seen[1..] {
assert!(poll.to_ascii_lowercase().contains(if bearer {
"authorization: bearer token"

View file

@ -69,14 +69,25 @@ fn transform_ocr_response_normalizes_mistral_json() {
#[test]
fn complete_url_defaults_and_dedupes_v1() {
assert_eq!(complete_url(None), "https://api.mistral.ai/v1/ocr");
assert_eq!(complete_url(Some(" ")), "https://api.mistral.ai/v1/ocr");
assert_eq!(complete_url(None).unwrap(), "https://api.mistral.ai/v1/ocr");
assert_eq!(
complete_url(Some("https://example.com")),
complete_url(Some(" ")).unwrap(),
"https://api.mistral.ai/v1/ocr"
);
assert_eq!(
complete_url(Some("https://example.com")).unwrap(),
"https://example.com/v1/ocr"
);
assert_eq!(
complete_url(Some("https://example.com/v1/")),
complete_url(Some("https://example.com/v1/")).unwrap(),
"https://example.com/v1/ocr"
);
assert_eq!(
complete_url(Some("https://example.com/v1/ocr?tenant=a")).unwrap(),
"https://example.com/v1/ocr?tenant=a"
);
assert_eq!(
complete_url(Some("https://example.com/v1?tenant=a")).unwrap(),
"https://example.com/v1/ocr?tenant=a"
);
}