feat(provider): add provider macros (#19)

bzp2010 · web-flow · commit a95ba1a58df2 · 2026-04-07T02:09:21.000+08:00
diff --git a/docs/internals/llm-types.md b/docs/internals/llm-types.md
@@ -134,6 +134,10 @@ The provider side is split into three layers.
 
 `ProviderCapabilities` is capability discovery. It returns typed trait objects such as `as_native_anthropic_messages()` and `as_native_openai_responses()` instead of booleans, so a provider cannot claim support for a feature without also exposing the methods behind that feature.
 
+For OpenAI-compatible providers, the concrete definition can stay very small. The `provider!()` macro generates `ProviderMeta`, a default `ChatTransform`, and an empty `ProviderCapabilities` implementation from a declarative block of base URL, auth shape, stream reader kind, and compatibility quirks.
+
+`OpenAIDef` remains hand-written because it needs its own default quirk profile, while `DeepSeek` is the first macro-generated provider in the new stack.
+
 ### Runtime provider instances
 
 `ProviderInstance` binds a shared provider definition to runtime auth, base URL overrides, and custom headers.
diff --git a/src/gateway/mod.rs b/src/gateway/mod.rs
@@ -1,5 +1,6 @@
 pub mod error;
 pub mod formats;
 pub mod provider_instance;
+pub mod providers;
 pub mod traits;
 pub mod types;
diff --git a/src/gateway/provider_instance.rs b/src/gateway/provider_instance.rs
@@ -25,6 +25,26 @@ impl fmt::Debug for ProviderAuth {
     }
 }
 
+impl ProviderAuth {
+    pub fn api_key(&self) -> Result<&str> {
+        match self {
+            Self::ApiKey(api_key) => Ok(api_key),
+            Self::None => Err(GatewayError::Validation(
+                "missing ProviderAuth::ApiKey value".into(),
+            )),
+        }
+    }
+
+    pub fn api_key_for(&self, provider: &str) -> Result<&str> {
+        self.api_key().map_err(|error| match error {
+            GatewayError::Validation(message) => {
+                GatewayError::Validation(format!("provider {}: {}", provider, message))
+            }
+            other => other,
+        })
+    }
+}
+
 /// Runtime provider configuration: definition, auth, and deployment overrides.
 #[derive(Clone)]
 pub struct ProviderInstance {
@@ -207,6 +227,33 @@ mod tests {
         assert_eq!(format!("{:?}", ProviderAuth::None), "None");
     }
 
+    #[test]
+    fn provider_auth_api_key_requires_api_key_variant() {
+        assert_eq!(
+            ProviderAuth::ApiKey("sk-secret".into()).api_key().unwrap(),
+            "sk-secret"
+        );
+
+        let error = ProviderAuth::None.api_key().unwrap_err();
+        assert!(matches!(
+            error,
+            GatewayError::Validation(message)
+                if message.contains("ProviderAuth::ApiKey")
+        ));
+    }
+
+    #[test]
+    fn provider_auth_api_key_for_adds_provider_context() {
+        let error = ProviderAuth::None.api_key_for("deepseek").unwrap_err();
+
+        assert!(matches!(
+            error,
+            GatewayError::Validation(message)
+                if message.contains("deepseek")
+                    && message.contains("ProviderAuth::ApiKey")
+        ));
+    }
+
     #[test]
     fn provider_instance_build_url_uses_provider_path() {
         let instance = ProviderInstance {
diff --git a/src/gateway/providers/deepseek.rs b/src/gateway/providers/deepseek.rs
@@ -0,0 +1,7 @@
+use crate::gateway::providers::macros::provider;
+
+provider!(DeepSeek {
+    display_name: "deepseek",
+    base_url: "https://api.deepseek.com",
+    auth: bearer,
+});
diff --git a/src/gateway/providers/macros.rs b/src/gateway/providers/macros.rs
@@ -0,0 +1,212 @@
+macro_rules! provider {
+    (@chat_path) => {};
+    (@chat_path $path:literal) => {
+        fn chat_endpoint_path(&self, _model: &str) -> std::borrow::Cow<'static, str> {
+            std::borrow::Cow::Borrowed($path)
+        }
+    };
+
+    (@stream) => {};
+    (@stream $kind:expr) => {
+        fn stream_reader_kind(&self) -> $crate::gateway::traits::StreamReaderKind {
+            $kind
+        }
+    };
+
+    (@auth bearer) => {
+        fn build_auth_headers(
+            &self,
+            auth: &$crate::gateway::provider_instance::ProviderAuth,
+        ) -> $crate::gateway::error::Result<http::HeaderMap> {
+            let mut headers = http::HeaderMap::new();
+            let value = http::HeaderValue::from_str(&format!(
+                "Bearer {}",
+                auth.api_key_for(self.name())?
+            ))
+                .map_err(|error| $crate::gateway::error::GatewayError::Validation(error.to_string()))?;
+            headers.insert(http::header::AUTHORIZATION, value);
+            Ok(headers)
+        }
+    };
+
+    (@auth api_key_header($header:literal)) => {
+        fn build_auth_headers(
+            &self,
+            auth: &$crate::gateway::provider_instance::ProviderAuth,
+        ) -> $crate::gateway::error::Result<http::HeaderMap> {
+            const HEADER_NAME: http::header::HeaderName =
+                http::header::HeaderName::from_static($header);
+            let mut headers = http::HeaderMap::new();
+            let value = http::HeaderValue::from_str(auth.api_key_for(self.name())?)
+                .map_err(|error| $crate::gateway::error::GatewayError::Validation(error.to_string()))?;
+            headers.insert(HEADER_NAME, value);
+            Ok(headers)
+        }
+    };
+
+    (@quirks { $($field:ident : $value:expr),* $(,)? }) => {
+        fn default_quirks(&self) -> $crate::gateway::traits::CompatQuirks {
+            $crate::gateway::traits::CompatQuirks {
+                $($field: $value,)*
+                ..$crate::gateway::traits::CompatQuirks::NONE
+            }
+        }
+    };
+
+    (@impl_provider
+        $name:ident,
+        $display:literal,
+        $base:literal,
+        [$($path:tt)?],
+        [$($stream_kind:tt)?],
+        [$($auth_kind:tt)+]
+    ) => {
+        pub struct $name;
+
+        impl $crate::gateway::traits::ProviderMeta for $name {
+            fn name(&self) -> &'static str {
+                $display
+            }
+
+            fn default_base_url(&self) -> &'static str {
+                $base
+            }
+
+            provider!(@chat_path $($path)?);
+            provider!(@stream $($stream_kind)?);
+            provider!(@auth $($auth_kind)+);
+        }
+
+        impl $crate::gateway::traits::ProviderCapabilities for $name {}
+    };
+
+    (
+        $name:ident {
+            display_name: $display:literal,
+            base_url: $base:literal,
+            $(chat_path: $path:literal,)?
+            $(stream: $stream_kind:expr,)?
+            auth: bearer,
+            quirks: { $($quirk_field:ident : $quirk_value:expr),* $(,)? }
+        }
+    ) => {
+        provider!(@impl_provider $name, $display, $base, [$($path)?], [$($stream_kind)?], [bearer]);
+
+        impl $crate::gateway::traits::ChatTransform for $name {
+            provider!(@quirks { $($quirk_field : $quirk_value),* });
+        }
+    };
+
+    (
+        $name:ident {
+            display_name: $display:literal,
+            base_url: $base:literal,
+            $(chat_path: $path:literal,)?
+            $(stream: $stream_kind:expr,)?
+            auth: bearer $(,)?
+        }
+    ) => {
+        provider!(@impl_provider $name, $display, $base, [$($path)?], [$($stream_kind)?], [bearer]);
+
+        impl $crate::gateway::traits::ChatTransform for $name {}
+    };
+
+    (
+        $name:ident {
+            display_name: $display:literal,
+            base_url: $base:literal,
+            $(chat_path: $path:literal,)?
+            $(stream: $stream_kind:expr,)?
+            auth: api_key_header($header:literal),
+            quirks: { $($quirk_field:ident : $quirk_value:expr),* $(,)? }
+        }
+    ) => {
+        provider!(@impl_provider $name, $display, $base, [$($path)?], [$($stream_kind)?], [api_key_header($header)]);
+
+        impl $crate::gateway::traits::ChatTransform for $name {
+            provider!(@quirks { $($quirk_field : $quirk_value),* });
+        }
+    };
+
+    (
+        $name:ident {
+            display_name: $display:literal,
+            base_url: $base:literal,
+            $(chat_path: $path:literal,)?
+            $(stream: $stream_kind:expr,)?
+            auth: api_key_header($header:literal) $(,)?
+        }
+    ) => {
+        provider!(@impl_provider $name, $display, $base, [$($path)?], [$($stream_kind)?], [api_key_header($header)]);
+
+        impl $crate::gateway::traits::ChatTransform for $name {}
+    };
+}
+
+pub(crate) use provider;
+
+#[cfg(test)]
+mod tests {
+    use std::borrow::Cow;
+
+    use crate::gateway::{
+        provider_instance::ProviderAuth,
+        traits::{ChatTransform, ProviderMeta, StreamReaderKind},
+    };
+
+    provider!(MacroTestProvider {
+        display_name: "macro-test",
+        base_url: "https://provider.example.com",
+        chat_path: "/custom/chat",
+        stream: StreamReaderKind::JsonArrayStream,
+        auth: api_key_header("x-api-key"),
+        quirks: {
+            unsupported_params: &["seed"],
+            tool_args_may_be_object: true,
+        }
+    });
+
+    #[test]
+    fn macro_generated_provider_exposes_expected_metadata() {
+        let provider = MacroTestProvider;
+
+        assert_eq!(provider.name(), "macro-test");
+        assert_eq!(provider.default_base_url(), "https://provider.example.com");
+        assert_eq!(
+            provider.chat_endpoint_path("ignored"),
+            Cow::Borrowed("/custom/chat")
+        );
+        assert_eq!(
+            provider.stream_reader_kind(),
+            StreamReaderKind::JsonArrayStream
+        );
+    }
+
+    #[test]
+    fn macro_generated_provider_builds_auth_headers_and_quirks() {
+        let provider = MacroTestProvider;
+        let headers = provider
+            .build_auth_headers(&ProviderAuth::ApiKey("secret-key".into()))
+            .unwrap();
+        let quirks = provider.default_quirks();
+
+        assert_eq!(headers["x-api-key"], "secret-key");
+        assert_eq!(quirks.unsupported_params, &["seed"]);
+        assert!(quirks.tool_args_may_be_object);
+    }
+
+    #[test]
+    fn macro_generated_provider_reports_provider_name_for_missing_api_key() {
+        let provider = MacroTestProvider;
+        let error = provider
+            .build_auth_headers(&ProviderAuth::None)
+            .unwrap_err();
+
+        assert!(matches!(
+            error,
+            crate::gateway::error::GatewayError::Validation(message)
+                if message.contains("macro-test")
+                    && message.contains("ProviderAuth::ApiKey")
+        ));
+    }
+}
diff --git a/src/gateway/providers/mod.rs b/src/gateway/providers/mod.rs
@@ -0,0 +1,29 @@
+pub mod deepseek;
+pub mod macros;
+pub mod openai;
+
+pub use deepseek::DeepSeek;
+pub use openai::OpenAIDef;
+
+use crate::gateway::{error::Result, provider_instance::ProviderRegistry};
+
+pub fn default_provider_registry() -> Result<ProviderRegistry> {
+    let builder = ProviderRegistry::builder()
+        .register(OpenAIDef)?
+        .register(DeepSeek)?;
+    Ok(builder.build())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::default_provider_registry;
+
+    #[test]
+    fn default_provider_registry_registers_builtin_providers() {
+        let registry = default_provider_registry().unwrap();
+
+        assert_eq!(registry.get("openai").unwrap().name(), "openai");
+        assert_eq!(registry.get("deepseek").unwrap().name(), "deepseek");
+        assert!(registry.get("missing").is_none());
+    }
+}
diff --git a/src/gateway/providers/openai.rs b/src/gateway/providers/openai.rs
