Compare commits

...

1 Commits

Author SHA1 Message Date
Yuval Kohavi
a0c197c4f2
feat: add extension points
Add extension points to agentgateway, so it can be extended for custom usecases.

This adds some extensions points and a framework for adding new extension points in the future
2026-02-12 09:34:01 -05:00
22 changed files with 2016 additions and 958 deletions

1
Cargo.lock generated
View File

@ -204,6 +204,7 @@ dependencies = [
"opentelemetry-proto",
"opentelemetry_sdk",
"parking_lot",
"paste",
"percent-encoding",
"phonenumber",
"pin-project-lite",

View File

@ -118,6 +118,7 @@ opentelemetry-otlp = { version = "0.31", features = ["grpc-tonic"] }
opentelemetry-proto = { version = "0.31", features = ["gen-tonic"] }
opentelemetry_sdk = { version = "0.31", features = ["rt-tokio"] }
parking_lot = "0.12"
paste = "1.0"
percent-encoding = "2.3"
phonenumber = "0.3"
pin-project-lite = "0.2"

File diff suppressed because it is too large Load Diff

View File

@ -17,6 +17,17 @@ func (this *Resource) UnmarshalJSON(b []byte) error {
return ResourceUnmarshaler.Unmarshal(bytes.NewReader(b), this)
}
// MarshalJSON is a custom marshaler for Extension
func (this *Extension) MarshalJSON() ([]byte, error) {
str, err := ResourceMarshaler.MarshalToString(this)
return []byte(str), err
}
// UnmarshalJSON is a custom unmarshaler for Extension
func (this *Extension) UnmarshalJSON(b []byte) error {
return ResourceUnmarshaler.Unmarshal(bytes.NewReader(b), this)
}
// MarshalJSON is a custom marshaler for Bind
func (this *Bind) MarshalJSON() ([]byte, error) {
str, err := ResourceMarshaler.MarshalToString(this)

View File

@ -0,0 +1,161 @@
// Originally derived from https://github.com/istio/ztunnel (Apache 2.0 licensed)
use std::path::PathBuf;
use std::sync::Arc;
use agent_core::{strng, telemetry, version};
use agentgateway::types::agent::ListenerTarget;
use agentgateway::{BackendConfig, Config, LoggingFormat, client, serdes};
use clap::Parser;
use tracing::info;
#[cfg(feature = "jemalloc")]
#[global_allocator]
static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
// Enable profiling, unless on musl due to https://github.com/tikv/jemallocator/issues/146
#[cfg(not(target_env = "musl"))]
#[cfg(feature = "jemalloc")]
#[allow(non_upper_case_globals)]
#[unsafe(export_name = "malloc_conf")]
pub static malloc_conf: &[u8] = b"prof:true,prof_active:true,lg_prof_sample:19\0";
lazy_static::lazy_static! {
// The memory is intentionally leaked here using Box::leak to achieve a 'static lifetime
// for the version string. This is necessary because the version string is used in a
// context that requires a 'static lifetime.
static ref LONG_VERSION: &'static str = Box::leak(version::BuildInfo::new().to_string().into_boxed_str());
static ref SHORT_VERSION: &'static str = version::BuildInfo::new().version;
}
#[derive(Parser, Debug)]
#[command(about, long_about = None)]
#[command(disable_version_flag = true)]
struct Args {
/// Use config from bytes
#[arg(short, long, value_name = "config")]
config: Option<String>,
/// Use config from file
#[arg(short, long, value_name = "file")]
file: Option<PathBuf>,
#[arg(long, value_name = "validate-only")]
validate_only: bool,
/// Print version (as a simple version string)
#[arg(short = 'V', value_name = "version")]
version_short: bool,
/// Print version (as JSON)
#[arg(long = "version")]
version_long: bool,
/// Copy our own binary to a destination.
#[arg(long = "copy-self", hide = true)]
copy_self: Option<PathBuf>,
}
pub fn run_app() -> anyhow::Result<()> {
let args = Args::parse();
let Args {
config,
file,
validate_only,
version_short,
version_long,
copy_self,
} = args;
if version_short {
println!("{}", version::BuildInfo::new().version);
return Ok(());
}
if version_long {
println!("{}", version::BuildInfo::new());
return Ok(());
}
if let Some(copy_self) = copy_self {
return copy_binary(copy_self);
}
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap()
.block_on(async move {
let (contents, filename) = match (config, file) {
(Some(_), Some(_)) => {
anyhow::bail!("only one of --config or --file")
},
(Some(config), None) => (config, None),
(None, Some(file)) => {
let contents = fs_err::read_to_string(&file)?;
(contents, Some(file))
},
(None, None) => ("{}".to_string(), None),
};
if validate_only {
return validate(contents, filename).await;
}
let mut config = agentgateway::config::parse_config(contents, filename)?;
// Capture the admin/runtime handle to ensure some background tasks (e.g., OTLP exporters created from dataplane
// policy initialization) run on the admin runtime rather than the dataplane runtime.
config.admin_runtime_handle = Some(tokio::runtime::Handle::current());
let _log_flush = telemetry::setup_logging(
&config.logging.level,
config.logging.format == LoggingFormat::Json,
);
proxy(Arc::new(config)).await
})
}
#[cfg(not(target_env = "musl"))]
fn copy_binary(_copy_self: PathBuf) -> anyhow::Result<()> {
// This is a pretty sketchy command, only allow it in environments will use it
anyhow::bail!("--copy-self is not supported in this build");
}
#[cfg(target_env = "musl")]
fn copy_binary(copy_self: PathBuf) -> anyhow::Result<()> {
let Some(our_binary) = std::env::args().next() else {
anyhow::bail!("no argv[0] set")
};
info!("copying our binary ({our_binary}) to {copy_self:?}");
if let Some(parent) = copy_self.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::copy(&our_binary, &copy_self)?;
return Ok(());
}
async fn validate(contents: String, filename: Option<PathBuf>) -> anyhow::Result<()> {
let config = agentgateway::config::parse_config(contents, filename)?;
let client = client::Client::new(&config.dns, None, BackendConfig::default(), None);
if let Some(cfg) = config.xds.local_config.as_ref() {
let cs = cfg.read_to_string().await?;
agentgateway::types::local::NormalizedLocalConfig::from(
&config,
client,
ListenerTarget {
gateway_name: strng::literal!("default"),
gateway_namespace: strng::literal!("default"),
listener_name: None,
},
cs.as_str(),
)
.await?;
} else {
println!("No local configuration");
}
println!("Configuration is valid!");
Ok(())
}
async fn proxy(cfg: Arc<Config>) -> anyhow::Result<()> {
info!("version: {}", version::BuildInfo::new());
info!(
"running with config: {}",
serdes::yamlviajson::to_string(&cfg)?
);
agentgateway::app::run(cfg).await?.wait_termination().await
}

View File

@ -1,161 +1,3 @@
// Originally derived from https://github.com/istio/ztunnel (Apache 2.0 licensed)
use std::path::PathBuf;
use std::sync::Arc;
use agent_core::{strng, telemetry, version};
use agentgateway::types::agent::ListenerTarget;
use agentgateway::{BackendConfig, Config, LoggingFormat, client, serdes};
use clap::Parser;
use tracing::info;
#[cfg(feature = "jemalloc")]
#[global_allocator]
static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
// Enable profiling, unless on musl due to https://github.com/tikv/jemallocator/issues/146
#[cfg(not(target_env = "musl"))]
#[cfg(feature = "jemalloc")]
#[allow(non_upper_case_globals)]
#[unsafe(export_name = "malloc_conf")]
pub static malloc_conf: &[u8] = b"prof:true,prof_active:true,lg_prof_sample:19\0";
lazy_static::lazy_static! {
// The memory is intentionally leaked here using Box::leak to achieve a 'static lifetime
// for the version string. This is necessary because the version string is used in a
// context that requires a 'static lifetime.
static ref LONG_VERSION: &'static str = Box::leak(version::BuildInfo::new().to_string().into_boxed_str());
static ref SHORT_VERSION: &'static str = version::BuildInfo::new().version;
}
#[derive(Parser, Debug)]
#[command(about, long_about = None)]
#[command(disable_version_flag = true)]
struct Args {
/// Use config from bytes
#[arg(short, long, value_name = "config")]
config: Option<String>,
/// Use config from file
#[arg(short, long, value_name = "file")]
file: Option<PathBuf>,
#[arg(long, value_name = "validate-only")]
validate_only: bool,
/// Print version (as a simple version string)
#[arg(short = 'V', value_name = "version")]
version_short: bool,
/// Print version (as JSON)
#[arg(long = "version")]
version_long: bool,
/// Copy our own binary to a destination.
#[arg(long = "copy-self", hide = true)]
copy_self: Option<PathBuf>,
}
fn main() -> anyhow::Result<()> {
let args = Args::parse();
let Args {
config,
file,
validate_only,
version_short,
version_long,
copy_self,
} = args;
if version_short {
println!("{}", version::BuildInfo::new().version);
return Ok(());
}
if version_long {
println!("{}", version::BuildInfo::new());
return Ok(());
}
if let Some(copy_self) = copy_self {
return copy_binary(copy_self);
}
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap()
.block_on(async move {
let (contents, filename) = match (config, file) {
(Some(_), Some(_)) => {
anyhow::bail!("only one of --config or --file")
},
(Some(config), None) => (config, None),
(None, Some(file)) => {
let contents = fs_err::read_to_string(&file)?;
(contents, Some(file))
},
(None, None) => ("{}".to_string(), None),
};
if validate_only {
return validate(contents, filename).await;
}
let mut config = agentgateway::config::parse_config(contents, filename)?;
// Capture the admin/runtime handle to ensure some background tasks (e.g., OTLP exporters created from dataplane
// policy initialization) run on the admin runtime rather than the dataplane runtime.
config.admin_runtime_handle = Some(tokio::runtime::Handle::current());
let _log_flush = telemetry::setup_logging(
&config.logging.level,
config.logging.format == LoggingFormat::Json,
);
proxy(Arc::new(config)).await
})
}
#[cfg(not(target_env = "musl"))]
fn copy_binary(_copy_self: PathBuf) -> anyhow::Result<()> {
// This is a pretty sketchy command, only allow it in environments will use it
anyhow::bail!("--copy-self is not supported in this build");
}
#[cfg(target_env = "musl")]
fn copy_binary(copy_self: PathBuf) -> anyhow::Result<()> {
let Some(our_binary) = std::env::args().next() else {
anyhow::bail!("no argv[0] set")
};
info!("copying our binary ({our_binary}) to {copy_self:?}");
if let Some(parent) = copy_self.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::copy(&our_binary, &copy_self)?;
return Ok(());
}
async fn validate(contents: String, filename: Option<PathBuf>) -> anyhow::Result<()> {
let config = agentgateway::config::parse_config(contents, filename)?;
let client = client::Client::new(&config.dns, None, BackendConfig::default(), None);
if let Some(cfg) = config.xds.local_config.as_ref() {
let cs = cfg.read_to_string().await?;
agentgateway::types::local::NormalizedLocalConfig::from(
&config,
client,
ListenerTarget {
gateway_name: strng::literal!("default"),
gateway_namespace: strng::literal!("default"),
listener_name: None,
},
cs.as_str(),
)
.await?;
} else {
println!("No local configuration");
}
println!("Configuration is valid!");
Ok(())
}
async fn proxy(cfg: Arc<Config>) -> anyhow::Result<()> {
info!("version: {}", version::BuildInfo::new());
info!(
"running with config: {}",
serdes::yamlviajson::to_string(&cfg)?
);
agentgateway::app::run(cfg).await?.wait_termination().await
agentgateway_app::run_app()
}

View File

@ -87,6 +87,7 @@ opentelemetry-http.workspace = true
opentelemetry.workspace = true
opentelemetry_sdk.workspace = true
parking_lot.workspace = true
paste.workspace = true
percent-encoding.workspace = true
phonenumber.workspace = true
pin-project-lite.workspace = true

View File

@ -34,9 +34,27 @@ fn main() -> Result<(), anyhow::Error> {
.build_server(true)
.compile_fds_with_config(fds, config)?;
// build test protos
let test_proto_files = ["proto/test.proto"]
.iter()
.map(|name| std::env::current_dir().unwrap().join(name))
.collect::<Vec<_>>();
let config = {
let mut c = prost_build::Config::new();
c.disable_comments(Some("."));
c.type_name_domain(["."], "type.googleapis.com");
c.enable_type_names();
c.type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]");
c
};
let fds = protox::compile(&test_proto_files, &include_dirs)?;
tonic_prost_build::configure()
.build_server(true)
.compile_fds_with_config(fds, config)?;
// This tells cargo to re-run this build script only when the proto files
// we're interested in change or the any of the proto directories were updated.
for path in [proto_files, include_dirs].concat() {
for path in [proto_files, test_proto_files, include_dirs].concat() {
println!("cargo:rerun-if-changed={}", path.to_str().unwrap());
}
Ok(())

View File

@ -4,6 +4,7 @@ package agentgateway.dev.resource;
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/any.proto";
import "workload.proto";
option go_package = "github.com/agentgateway/agentgateway/go/api;api";
@ -22,6 +23,12 @@ message Resource {
}
}
// Custom extensions
message Extension {
string name = 1;
google.protobuf.Any config = 2;
}
message Bind {
// Protocol defines the bind-level protocol to use. Individual listeners will have more details about this.
// For instance, a Bind protocol TLS may have TLS termination and TLS passthrough listeners.
@ -205,6 +212,7 @@ message BackendAuthPolicy {
Gcp gcp = 3;
Aws aws = 4;
Azure azure = 5;
Extension custom = 6;
}
}

View File

@ -0,0 +1,10 @@
syntax = "proto3";
package agentgateway.dev.test;
message TestExtension {
string value = 1;
}
message Test2Extension {
string value2 = 1;
}

View File

@ -1,3 +1,4 @@
use std::collections::HashMap;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::mpsc;
use std::thread;
@ -122,6 +123,7 @@ pub async fn run(config: Arc<Config>) -> anyhow::Result<Bound> {
ca,
mcp_state: mcp::App::new(stores.clone(), config.session_encoder.clone()),
config_extensions: handle_config_extensions(config.extensions.as_slice()).await?,
};
let gw = proxy::Gateway::new(Arc::new(pi), drain_rx.clone());
@ -243,3 +245,14 @@ fn new_data_plane_pool(
let handle = rx_handle.recv().unwrap();
(handle, tx)
}
async fn handle_config_extensions(
extensions: &[Arc<crate::LoadedConfigExtension>],
) -> anyhow::Result<HashMap<String, Arc<dyn std::any::Any + Send + Sync>>> {
let mut result = HashMap::new();
for ext in extensions {
let any = ext.handler.start().await?;
result.insert(ext.name.clone(), any.into());
}
Ok(result)
}

View File

@ -422,6 +422,12 @@ pub fn parse_config(contents: String, filename: Option<PathBuf>) -> anyhow::Resu
)
.unwrap_or(Duration::from_secs(60 * 5)),
}),
extensions: raw
.extensions
.unwrap_or_default()
.into_iter()
.map(Arc::new)
.collect(),
})
}

View File

@ -0,0 +1,759 @@
//! Extension points for agentgateway
//!
//! This module provides extension mechanisms that allow downstream code
//! to inject custom functionality without modifying the core library.
#[cfg(feature = "schema")]
use std::borrow::Cow;
use std::collections::HashMap;
use std::sync::Arc;
use anyhow::Context;
use parking_lot::RwLock;
use prost::Message;
use serde::{Deserialize, Serialize};
/// A dynamic protobuf message that can be serialized/deserialized as JSON.
///
/// This trait makes `prost::Message` work with serde for JSON serialization
/// while preserving the ability to work with protobuf bytes for XDS.
pub trait DynamicProtoMessage: Send + Sync + std::fmt::Debug {
/// Get the type URL for this message (e.g., "type.googleapis.com/mycompany.auth.Config")
fn type_url(&self) -> &str;
/// Serialize to JSON
fn to_json(&self) -> Result<serde_json::Value, anyhow::Error>;
/// Clone into a new box
fn clone_box(&self) -> Box<dyn DynamicProtoMessage>;
/// Get a reference to the inner message as `Any` for downcasting
fn as_any(&self) -> &dyn std::any::Any;
}
pub trait HasRegistry<T> {
fn registry() -> &'static Registry<T>;
}
/// Configuration as a dynamic protobuf message (can serialize to JSON)
pub struct Extension<T> {
pub name: String,
pub config: Box<dyn crate::extension::DynamicProtoMessage>,
/// The resolved handler instance (eagerly resolved during deserialization)
pub handler: T,
}
impl<T> Extension<T> {
pub fn new(name: &str, config: Box<dyn DynamicProtoMessage>, handler: T) -> Self {
Self {
name: name.to_string(),
config,
handler,
}
}
}
impl<T: 'static> Extension<T>
where
Extension<T>: HasRegistry<T>,
{
/// Resolve a custom auth handler from protobuf Any (for XDS)
pub fn resolve_extension(
ext: &crate::types::proto::agent::Extension,
) -> Result<Self, anyhow::Error> {
let config = ext
.config
.as_ref()
.ok_or_else(|| anyhow::anyhow!("Extension config is required"))?;
Self::resolve_any(ext.name.as_str(), config)
}
pub fn resolve_any(name: &str, any: &prost_types::Any) -> Result<Self, anyhow::Error> {
if name.is_empty() {
anyhow::bail!("Extension name is required");
}
let type_url = any.type_url.as_str();
let registry = <Self as HasRegistry<T>>::registry();
let reg = registry.get(type_url).ok_or_else(|| {
anyhow::anyhow!(
concat!("Unknown Extension for type '{}'. Make sure to register the handler before loading configuration."),
type_url
)
})?;
let (u, c) = reg.resolve_any(name, any)?;
Ok(Self::new(name, c, u))
}
pub fn register<C>(factory: impl Fn(&str, &C) -> Result<T, anyhow::Error> + Send + Sync + 'static)
where
C: prost::Message
+ Default
+ Clone
+ Send
+ Sync
+ std::fmt::Debug
+ serde::Serialize
+ for<'de> serde::Deserialize<'de>
+ prost::Name
+ 'static,
{
let registry = <Self as HasRegistry<T>>::registry();
registry.register::<C>(factory);
}
}
impl<T> std::fmt::Debug for Extension<T> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Extension")
.field("config", &self.config)
.finish()
}
}
#[cfg(feature = "schema")]
impl<T> schemars::JsonSchema for Extension<T> {
fn schema_name() -> Cow<'static, str> {
"Extension".into()
}
fn json_schema(_generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
schemars::json_schema!({
"type": ["object"],
"properties": {
"name": {
"type": "string"
},
"config": {
"type": "object"
}
},
"required": ["name", "config"]
})
}
}
// Manual Deserialize implementation to handle both standard and custom auth types
impl<'de, T: 'static> serde::Deserialize<'de> for Extension<T>
where
Extension<T>: HasRegistry<T>,
{
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
use serde::de::Error;
// First deserialize into a generic Value to inspect it
let value = serde_json::Value::deserialize(deserializer)?;
// get name and config
let name = value
.get("name")
.and_then(serde_json::Value::as_str)
.map(|s| s.trim())
.filter(|s| !s.is_empty())
.ok_or_else(|| Error::custom("`name` field is required and must be a non-empty string"))?
.to_string();
let config = value
.get("config")
.ok_or_else(|| Error::custom("`config` field is required"))?
.clone();
// Check if this is a custom auth with @type field (google.protobuf.Any format)
if let Some(obj) = config.as_object()
&& let Some(type_url) = obj.get("@type").and_then(serde_json::Value::as_str)
{
// This is a custom auth handler
// Remove the @type field and keep the rest as config
let mut config_obj = obj.clone();
config_obj.remove("@type");
let config_json = serde_json::Value::Object(config_obj);
// Use extension module to resolve handler and config
let registry = <Self as HasRegistry<T>>::registry();
let reg = registry.get(type_url).ok_or_else(|| {
Error::custom(format!(
"Failed to resolve custom auth handler for : {}",
type_url
))
})?;
let (handler, config) = reg
.resolve(name.as_str(), &config_json)
.map_err(|e| Error::custom(format!("Failed to resolve custom auth handler: {}", e)))?;
return Ok(Extension {
name,
config,
handler,
});
}
Err(Error::custom(format!(
"Invalid {} configuration. missing @type field.",
std::any::type_name::<T>()
)))
}
}
impl<T> serde::Serialize for Extension<T> {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
use serde::ser::SerializeMap;
// Use DynamicProtoMessage::to_json() to serialize the config
let mut json = self.config.to_json().map_err(serde::ser::Error::custom)?;
let mut obj = serde_json::Map::new();
obj.insert(
"name".to_string(),
serde_json::Value::String(self.name.clone()),
);
if let Some(o) = json.as_object_mut() {
o.insert(
"@type".to_string(),
serde_json::Value::String(self.config.type_url().into()),
);
}
obj.insert("config".to_string(), json);
let mut map = serializer.serialize_map(None)?;
// Merge in the config fields
for (key, value) in obj {
map.serialize_entry(&key, &value)?;
}
map.end()
}
}
impl Clone for Box<dyn DynamicProtoMessage> {
fn clone(&self) -> Self {
self.clone_box()
}
}
/// Concrete implementation of DynamicProtoMessage for any prost Message
struct ProtoMessageWrapper<T: Message + Clone + Send + Sync + std::fmt::Debug + 'static> {
type_url: String,
message: T,
}
impl<T> std::fmt::Debug for ProtoMessageWrapper<T>
where
T: Message + Clone + Send + Sync + std::fmt::Debug + 'static,
{
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ProtoMessageWrapper")
.field("type_url", &self.type_url)
.field("message", &self.message)
.finish()
}
}
impl<T> DynamicProtoMessage for ProtoMessageWrapper<T>
where
T: Message + Clone + Send + Sync + std::fmt::Debug + Serialize + 'static,
{
fn type_url(&self) -> &str {
&self.type_url
}
fn to_json(&self) -> Result<serde_json::Value, anyhow::Error> {
serde_json::to_value(&self.message).context("Failed to serialize message to JSON")
}
fn clone_box(&self) -> Box<dyn DynamicProtoMessage> {
Box::new(ProtoMessageWrapper {
type_url: self.type_url.clone(),
message: self.message.clone(),
})
}
fn as_any(&self) -> &dyn std::any::Any {
&self.message
}
}
// Factory type for creating handlers from config
type Factory<T> = Arc<dyn Fn(&str, &dyn std::any::Any) -> Result<T, anyhow::Error> + Send + Sync>;
type FromJsonFunc =
dyn Fn(&serde_json::Value) -> Result<Box<dyn DynamicProtoMessage>, anyhow::Error> + Send + Sync;
type FromSliceFunc =
dyn Fn(&[u8]) -> Result<Box<dyn DynamicProtoMessage>, anyhow::Error> + Send + Sync;
struct Registration<T> {
factory: Factory<T>,
from_json: Box<FromJsonFunc>,
from_slice: Box<FromSliceFunc>,
type_url: String,
}
impl<T> Registration<T> {
fn new<C>(factory: impl Fn(&str, &C) -> Result<T, anyhow::Error> + Send + Sync + 'static) -> Self
where
C: Message
+ Default
+ Clone
+ Send
+ Sync
+ std::fmt::Debug
+ Serialize
+ for<'de> Deserialize<'de>
+ prost::Name
+ 'static,
{
// Construct the type URL``
let type_url = format!("type.googleapis.com/{}.{}", C::PACKAGE, C::NAME);
// Wrap the factory to work with DynamicProtoMessage
let type_url_for_json = type_url.clone();
let type_url_for_slice = type_url.clone();
Registration {
type_url,
factory: Arc::new(move |name: &str, config: &dyn std::any::Any| {
// Deserialize from JSON (config is already a DynamicProtoMessage)
if let Some(cfg) = config.downcast_ref::<C>() {
return factory(name, cfg);
}
anyhow::bail!("Failed to downcast config to expected type {}", C::NAME);
}),
from_json: Box::new(move |json| {
Ok(Box::new(ProtoMessageWrapper {
type_url: type_url_for_json.clone(),
message: serde_json::from_value::<C>(json.clone())?,
}))
}),
from_slice: Box::new(move |bytes| {
Ok(Box::new(ProtoMessageWrapper {
type_url: type_url_for_slice.clone(),
message: C::decode(bytes)?,
}))
}),
}
}
pub(crate) fn resolve(
&self,
name: &str,
config_json: &serde_json::Value,
) -> Result<(T, Box<dyn DynamicProtoMessage>), anyhow::Error> {
self.resolve_dynamic(name, (self.from_json)(config_json)?)
}
pub(crate) fn resolve_any(
&self,
name: &str,
any: &prost_types::Any,
) -> Result<(T, Box<dyn DynamicProtoMessage>), anyhow::Error> {
self.resolve_dynamic(name, (self.from_slice)(&any.value)?)
}
fn resolve_dynamic(
&self,
name: &str,
config: Box<dyn DynamicProtoMessage>,
) -> Result<(T, Box<dyn DynamicProtoMessage>), anyhow::Error> {
// Create handler
let handler = (self.factory)(name, config.as_any())?;
Ok((handler, config))
}
}
pub struct Registry<T> {
registrations: RwLock<HashMap<String, Arc<Registration<T>>>>,
}
impl<T> Default for Registry<T> {
fn default() -> Self {
Self {
registrations: RwLock::new(HashMap::new()),
}
}
}
impl<T> Registry<T> {
fn insert(&self, type_url: String, registration: Registration<T>) {
self
.registrations
.write()
.insert(type_url, Arc::new(registration));
}
fn get(&self, type_url: &str) -> Option<Arc<Registration<T>>> {
self.registrations.read().get(type_url).cloned()
}
fn register<C>(
&self,
factory: impl Fn(&str, &C) -> Result<T, anyhow::Error> + Send + Sync + 'static,
) where
C: Message
+ Default
+ Clone
+ Send
+ Sync
+ std::fmt::Debug
+ Serialize
+ for<'de> Deserialize<'de>
+ prost::Name
+ 'static,
{
let reg = Registration::new::<C>(factory);
// Register with full type URL
self.insert(reg.type_url.clone(), reg);
}
}
/// Macro to generate extension boilerplate for a given handler trait.
///
/// This generates an Extension alias for the Extension<T>, a static registry,
/// and associates the registry with the trait.
///
/// # Example
///
/// ```ignore
/// define_extension_point!(
/// BackendAuth, // Name of the extension point
/// BackendAuthHandler, // Trait for the handler
/// );
/// ```
#[macro_export]
macro_rules! define_extension_point {
(
$name:ident,
$trait:ty
) => {
paste::paste! {
static [<$name:snake:upper _REGISTRY>]: once_cell::sync::Lazy<$crate::extension::Registry<Box<dyn $trait>>> = once_cell::sync::Lazy::new(Default::default);
pub type [<$name Extension>] = $crate::extension::Extension<Box<dyn $trait>>;
impl $crate::extension::HasRegistry<Box<dyn $trait>> for [<$name Extension>] {
fn registry() -> &'static $crate::extension::Registry<Box<dyn $trait>> {
&*[<$name:snake:upper _REGISTRY>]
}
}
}
};
}
#[cfg(test)]
mod tests {
use serde_json::json;
macro_rules! test_fixture {
() => {
// Define a test trait for extension testing
pub trait TestHandler: Send + Sync + std::fmt::Debug {
fn handle(&self) -> String;
}
// Define a dummy handler implementation
#[derive(Debug)]
#[allow(dead_code)] // In some tests, this is not used, as they test failures
struct DummyTestHandler {
config_value: String,
}
impl TestHandler for DummyTestHandler {
fn handle(&self) -> String {
format!("Handled: {}", self.config_value)
}
}
// Create an extension point for testing
define_extension_point!(Test, TestHandler);
};
}
#[test]
fn test_extension_json_round_trip() {
test_fixture!();
// Register handler for TestExtension
TestExtension::register(|name, config: &crate::types::proto::agent::TestExtension| {
assert_eq!(name, "my-extension");
Ok(Box::new(DummyTestHandler {
config_value: config.value.clone(),
}) as Box<dyn TestHandler>)
});
// Create a TestExtension with a name field
let test_config = crate::types::proto::agent::TestExtension {
value: "test-handler".to_string(),
};
let any = prost_types::Any::from_msg(&test_config).expect("Failed to create Any");
let proto_ext = crate::types::proto::agent::Extension {
name: "my-extension".to_string(),
config: Some(any),
};
let extension =
TestExtension::resolve_extension(&proto_ext).expect("Failed to resolve extension");
// Serialize to JSON
let json = serde_json::to_value(&extension).expect("Failed to serialize");
// Verify structure
let expected = json!({
"name": "my-extension",
"config": {
"@type": "type.googleapis.com/agentgateway.dev.test.TestExtension",
"value": "test-handler"
}
});
// Check for @type field
assert_eq!(json, expected);
// Deserialize back
let deserialized: TestExtension = serde_json::from_value(json).expect("Failed to deserialize");
// Verify handler works
assert_eq!(deserialized.name, "my-extension");
assert_eq!(deserialized.handler.handle(), "Handled: test-handler");
// Verify config is preserved
let config_any = deserialized.config.as_any();
let config_typed = config_any
.downcast_ref::<crate::types::proto::agent::TestExtension>()
.expect("Config should downcast to TestExtension");
assert_eq!(config_typed.value, "test-handler");
}
#[test]
fn test_extension_protobuf_any_deserialization() {
test_fixture!();
// Register handler for TestExtension
TestExtension::register(|name, config: &crate::types::proto::agent::TestExtension| {
assert_eq!(name, "proto-extension");
Ok(Box::new(DummyTestHandler {
config_value: config.value.clone(),
}) as Box<dyn TestHandler>)
});
// Create a TestExtension protobuf message
let test_config = crate::types::proto::agent::TestExtension {
value: "protobuf-test".to_string(),
};
// Create protobuf Any
let any = prost_types::Any::from_msg(&test_config).expect("Failed to create Any");
// Deserialize using resolve_any
let extension = TestExtension::resolve_any("proto-extension", &any)
.expect("Failed to resolve extension from Any");
// Verify extension
assert_eq!(extension.name, "proto-extension");
assert_eq!(extension.handler.handle(), "Handled: protobuf-test");
// Verify config is preserved
let config_any = extension.config.as_any();
let config_typed = config_any
.downcast_ref::<crate::types::proto::agent::TestExtension>()
.expect("Config should downcast to TestExtension");
assert_eq!(config_typed.value, "protobuf-test");
}
#[test]
fn test_extension_protobuf_any_via_proto_extension() {
test_fixture!();
// Register handler for TestExtension
TestExtension::register(|name, config: &crate::types::proto::agent::TestExtension| {
assert_eq!(name, "xds-extension");
Ok(Box::new(DummyTestHandler {
config_value: config.value.clone(),
}) as Box<dyn TestHandler>)
});
// Create a TestExtension protobuf message
let test_config = crate::types::proto::agent::TestExtension {
value: "xds-test".to_string(),
};
// Create the proto Extension wrapper
let proto_ext = crate::types::proto::agent::Extension {
name: "xds-extension".to_string(),
config: Some(prost_types::Any::from_msg(&test_config).expect("Failed to create Any")),
};
// Resolve using resolve_extension (simulates XDS path)
let extension =
TestExtension::resolve_extension(&proto_ext).expect("Failed to resolve extension");
// Verify extension
assert_eq!(extension.name, "xds-extension");
assert_eq!(extension.handler.handle(), "Handled: xds-test");
// Verify config is preserved
let config_any = extension.config.as_any();
let config_typed = config_any
.downcast_ref::<crate::types::proto::agent::TestExtension>()
.expect("Config should downcast to TestExtension");
assert_eq!(config_typed.value, "xds-test");
}
#[test]
fn test_extension_unregistered_type_error() {
test_fixture!();
TestExtension::register(
|_name, _config: &crate::types::proto::agent::TestExtension| {
panic!("Factory should not be called when type is not registered");
},
);
// Don't register any handler
// Create a fake Any with unregistered type URL
let any = prost_types::Any {
type_url: "type.googleapis.com/unknown.UnregisteredType".to_string(),
value: vec![],
};
// Try to resolve - should fail with clear error
let result = TestExtension::resolve_any("test", &any);
assert!(result.is_err(), "Should fail for unregistered type");
let err = result.unwrap_err().to_string();
assert!(
err.contains("Unknown Extension"),
"Error should mention unknown extension, got: {}",
err
);
assert!(
err.contains("unknown.UnregisteredType"),
"Error should mention the type URL, got: {}",
err
);
}
#[test]
fn test_extension_missing_name_error() {
test_fixture!();
// Register handler
TestExtension::register(
|_name, _config: &crate::types::proto::agent::TestExtension| {
panic!("Factory should not be called when name is missing");
},
);
let test_config = crate::types::proto::agent::TestExtension {
value: "test".to_string(),
};
let any = prost_types::Any::from_msg(&test_config).expect("Failed to create Any");
// Try to resolve with empty name - should fail
let result = TestExtension::resolve_any("", &any);
assert!(result.is_err(), "Should fail for empty name");
let err = result.unwrap_err().to_string();
assert!(
err.contains("Extension name is required"),
"Error should mention missing name, got: {}",
err
);
}
#[test]
fn test_extension_json_deserialization_missing_type() {
test_fixture!();
// Register handler
TestExtension::register(
|_name, _config: &crate::types::proto::agent::TestExtension| {
panic!("Factory should not be called when @type is missing");
},
);
// Create JSON without @type field
let json = json!({
"name": "test",
"config": {
"name": "test-config"
}
});
// Try to deserialize - should fail
let result = serde_json::from_value::<TestExtension>(json);
assert!(result.is_err(), "Should fail when @type field is missing");
}
#[test]
fn test_extension_multiple_types_no_cross_contamination() {
test_fixture!();
// Define a second test handler type
trait SecondTestHandler: Send + Sync + std::fmt::Debug {
fn process(&self) -> String;
}
#[derive(Debug)]
struct SecondDummyHandler {
value: String,
}
impl SecondTestHandler for SecondDummyHandler {
fn process(&self) -> String {
format!("Processed: {}", self.value)
}
}
// Create second extension point
define_extension_point!(SecondTest, SecondTestHandler);
// Register handlers for first type
TestExtension::register(
|_name, config: &crate::types::proto::agent::TestExtension| {
Ok(Box::new(DummyTestHandler {
config_value: config.value.clone(),
}) as Box<dyn TestHandler>)
},
);
// Same extension point, differnt proto
TestExtension::register(
|_name, config: &crate::types::proto::agent::Test2Extension| {
Ok(Box::new(DummyTestHandler {
config_value: config.value2.clone(),
}) as Box<dyn TestHandler>)
},
);
// Different extension point, same proto as first
SecondTestExtension::register(
|_name, config: &crate::types::proto::agent::TestExtension| {
Ok(Box::new(SecondDummyHandler {
value: config.value.clone(),
}) as Box<dyn SecondTestHandler>)
},
);
// Create extensions
let test_config = crate::types::proto::agent::TestExtension {
value: "shared-config".to_string(),
};
let test2_config = crate::types::proto::agent::Test2Extension {
value2: "shared2-config".to_string(),
};
let any = prost_types::Any::from_msg(&test_config).expect("Failed to create Any");
let any2 = prost_types::Any::from_msg(&test2_config).expect("Failed to create Any");
let first_ext =
TestExtension::resolve_any("first", &any).expect("Failed to resolve first extension");
let second_ext =
SecondTestExtension::resolve_any("second", &any).expect("Failed to resolve second extension");
let third_ext =
TestExtension::resolve_any("third", &any2).expect("Failed to resolve third extension");
// Verify each extension uses its own handler type correctly
assert_eq!(first_ext.handler.handle(), "Handled: shared-config");
assert_eq!(second_ext.handler.process(), "Processed: shared-config");
assert_eq!(third_ext.handler.handle(), "Handled: shared2-config");
// Verify they're independent - changes to one don't affect the other
assert_eq!(first_ext.name, "first");
assert_eq!(second_ext.name, "second");
assert_eq!(third_ext.name, "third");
}
}

View File

@ -7,6 +7,33 @@ use crate::serdes::deser_key_from_file;
use crate::types::agent::{BackendTarget, Target};
use crate::*;
/// Trait for custom backend authentication handlers.
#[async_trait::async_trait]
pub trait BackendAuthHandler: Send + Sync + std::fmt::Debug {
/// Apply authentication to the request.
///
/// This is called before the request body is fully available.
/// For auth methods that need to sign the request body (like AWS SigV4),
/// use `apply_late_auth` instead.
async fn apply_auth(
&self,
backend_info: &BackendInfo,
req: &mut Request,
) -> Result<(), anyhow::Error>;
/// Apply late authentication (after body is available).
///
/// This is called after the request body is fully buffered and available.
/// Use this for authentication methods that need to sign the request body.
///
/// Default implementation does nothing.
async fn apply_late_auth(&self, _req: &mut Request) -> Result<(), anyhow::Error> {
Ok(())
}
}
define_extension_point!(BackendAuth, BackendAuthHandler);
#[apply(schema!)]
#[serde(untagged)]
pub enum AwsAuth {
@ -136,6 +163,11 @@ pub enum BackendAuth {
Aws(AwsAuth),
#[serde(rename = "azure")]
Azure(AzureAuth),
/// Custom authentication handler.
///
/// The handler must be registered via `BackendAuthExtension::register` before configuration is loaded.
#[cfg_attr(feature = "schema", schemars(skip))]
Custom(Arc<BackendAuthExtension>),
}
#[derive(Clone)]
@ -182,6 +214,13 @@ pub async fn apply_backend_auth(
.map_err(ProxyError::BackendAuthenticationFailed)?;
req.headers_mut().insert(http::header::AUTHORIZATION, token);
},
BackendAuth::Custom(extension) => {
extension
.handler
.apply_auth(backend_info, req)
.await
.map_err(ProxyError::BackendAuthenticationFailed)?;
},
}
Ok(())
}
@ -203,6 +242,13 @@ pub async fn apply_late_backend_auth(
.map_err(ProxyError::BackendAuthenticationFailed)?;
},
BackendAuth::Azure(_) => {},
BackendAuth::Custom(extension) => {
extension
.handler
.apply_late_auth(req)
.await
.map_err(ProxyError::BackendAuthenticationFailed)?;
},
};
Ok(())
}

View File

@ -228,3 +228,50 @@ async fn test_aws_sign_request_implicit_with_extension() {
result.expect("signing failed");
}
#[derive(Debug)]
struct DummyHandler;
#[async_trait::async_trait]
impl crate::http::auth::BackendAuthHandler for DummyHandler {
async fn apply_auth(
&self,
_backend_info: &http::auth::BackendInfo,
_req: &mut crate::http::Request,
) -> Result<(), anyhow::Error> {
Ok(())
}
async fn apply_late_auth(&self, _req: &mut crate::http::Request) -> Result<(), anyhow::Error> {
Ok(())
}
}
#[test]
fn test_extension() {
BackendAuthExtension::register(|_, _config: &crate::types::proto::agent::TestExtension| {
// In a real implementation, you'd parse the config and return an appropriate handler
Ok(Box::new(DummyHandler))
});
let mut config = crate::types::proto::agent::BackendAuthPolicy::default();
let test_ext = crate::types::proto::agent::TestExtension::default();
config.kind = Some(
crate::types::proto::agent::backend_auth_policy::Kind::Custom(
crate::types::proto::agent::Extension {
name: "test_extension".to_string(),
config: Some(prost_types::Any::from_msg(&test_ext).unwrap()),
},
),
);
let ba = BackendAuth::try_from(config);
assert!(
ba.is_ok(),
"Custom backend auth policy should be parsed successfully {}",
ba.err().unwrap()
);
assert!(
matches!(ba.unwrap(), BackendAuth::Custom(_)),
"Parsed policy should be of Custom variant"
);
}

View File

@ -25,6 +25,7 @@ pub mod cel;
pub mod client;
pub mod config;
pub mod control;
pub mod extension;
pub mod http;
pub mod json;
pub mod llm;
@ -51,7 +52,7 @@ use crate::control::{AuthSource, RootCert};
use crate::telemetry::trc::Protocol;
use crate::types::agent::{ListenerTarget, PolicyTargetRef};
#[derive(serde::Deserialize, Clone, Debug)]
#[derive(serde::Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
/// NestedRawConfig represents a subset of the config that can be passed in. This is split out from static
/// and dynamic config
@ -59,7 +60,7 @@ pub struct NestedRawConfig {
config: Option<RawConfig>,
}
#[derive(serde::Deserialize, Default, Clone, Debug)]
#[derive(serde::Deserialize, Default, Debug)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "schema", derive(JsonSchema))]
// RawConfig represents the inputs a user can pass in. Config represents the internal representation of this.
@ -116,6 +117,7 @@ pub struct RawConfig {
_listener: serdes::RenamedField,
hbone: Option<RawHBONE>,
extensions: Option<Vec<LoadedConfigExtension>>,
}
mod removed {
@ -367,6 +369,12 @@ impl schemars::JsonSchema for StringBoolFloat {
}
}
#[async_trait::async_trait]
pub trait LoadedConfigExtensionHandler: Debug + Send + Sync {
async fn start(&self) -> anyhow::Result<Box<dyn std::any::Any + Send + Sync>>;
}
define_extension_point!(LoadedConfig, LoadedConfigExtensionHandler);
#[derive(serde::Serialize, Clone, Debug)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Config {
@ -398,6 +406,8 @@ pub struct Config {
pub admin_runtime_handle: Option<tokio::runtime::Handle>,
pub backend: BackendConfig,
pub extensions: Vec<Arc<LoadedConfigExtension>>,
}
impl Config {
@ -484,6 +494,8 @@ pub struct ProxyInputs {
mcp_state: mcp::App,
ca: Option<Arc<CaClient>>,
pub config_extensions: HashMap<String, Arc<dyn std::any::Any + Send + Sync>>,
}
#[derive(Debug, Clone, Copy, serde::Serialize)]

View File

@ -46,6 +46,7 @@ async fn setup() -> (MockServer, Handler) {
ca: None,
mcp_state: mcp::router::App::new(stores.clone(), encoder),
config_extensions: Default::default(),
});
let client = PolicyClient { inputs: pi.clone() };

View File

@ -617,6 +617,7 @@ pub fn setup_proxy_test(cfg: &str) -> anyhow::Result<TestBind> {
ca: None,
mcp_state: mcp::App::new(stores.clone(), encoder),
config_extensions: Default::default(),
});
Ok(TestBind {
pi,

View File

@ -9,7 +9,7 @@ use itertools::Itertools;
use llm::{AIBackend, AIProvider, NamedAIProvider};
use super::agent::*;
use crate::http::auth::{AwsAuth, BackendAuth, GcpAuth};
use crate::http::auth::{AwsAuth, BackendAuth, BackendAuthExtension, GcpAuth};
use crate::http::transformation_cel::{LocalTransform, LocalTransformationConfig, Transformation};
use crate::http::{HeaderOrPseudo, Scheme, auth, authorization};
use crate::mcp::McpAuthorization;
@ -514,6 +514,18 @@ impl TryFrom<proto::agent::BackendAuthPolicy> for BackendAuth {
};
BackendAuth::Azure(azure_auth)
},
Some(proto::agent::backend_auth_policy::Kind::Custom(c)) => {
// Get the google.protobuf.Any config
let any_config = c.config.ok_or(ProtoError::MissingRequiredField)?;
// Use extension module to resolve handler and config from protobuf Any
let extension =
BackendAuthExtension::resolve_any(c.name.as_str(), &any_config).map_err(|e| {
ProtoError::EnumParse(format!("Failed to resolve custom auth handler: {}", e))
})?;
BackendAuth::Custom(Arc::from(extension))
},
None => return Err(ProtoError::MissingRequiredField),
})
}

View File

@ -28,6 +28,9 @@ pub mod agentgateway1 {
}
pub mod agent {
pub use super::agentgateway1::agentgateway2::agentgateway3::*;
#[cfg(test)]
tonic::include_proto!("agentgateway.dev.test");
}
#[allow(clippy::enum_variant_names)]

View File

@ -429,6 +429,29 @@
}
},
"additionalProperties": false
},
"extensions": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object"
],
"properties": {
"name": {
"type": "string"
},
"config": {
"type": "object"
}
},
"required": [
"name",
"config"
]
}
}
},
"additionalProperties": false,

View File

@ -59,6 +59,9 @@
|`config.hbone.frameSize`||
|`config.hbone.poolMaxStreamsPerConn`||
|`config.hbone.poolUnusedReleaseTimeout`||
|`config.extensions`||
|`config.extensions[].name`||
|`config.extensions[].config`||
|`binds`||
|`binds[].port`||
|`binds[].listeners`||