Custom Plugin Development

Overview

Custom plugins are plain Rust files compiled directly into the gateway binary — no external SDK, no FFI, no dynamic loading. They implement the Plugin trait from crate::plugins and are registered automatically by a build script that scans the custom_plugins/ directory.

The file name (without .rs) becomes the plugin name used in gateway configuration. For example, my_rate_limiter.rs registers as plugin name "my_rate_limiter".

Quick Start

touch custom_plugins/my_plugin.rs

cargo build --release

{
  "plugin_name": "my_plugin",
  "scope": "global",
  "config": { "header_value": "ferrum-custom" }
}

Priority Bands

Priority is a u16. Lower values run earlier. Bands are spaced with gaps so future plugins can slot in without renumbering — pick a value in the band that matches where your plugin belongs.

The default priority is 5000 (the Custom band), which runs after all transforms but before logging — a safe default when your plugin has no strong ordering requirements. Add a named constant to the priority module in src/plugins/mod.rs for discoverability. Operators can also override any instance's priority per plugin-config via priority_override (0–10000).

Plugin Trait Hooks — HTTP/gRPC/WebSocket

All hooks have default no-op implementations — only override the ones your plugin needs. *on_ws_frame cannot return PluginResult::Reject. Instead, return Some(Message::Close(...)) to close the connection in both directions.

Plugin Trait Hooks — TCP/UDP Streams

For TCP+TLS proxies, on_stream_connect runs after the frontend TLS handshake, so client certificate data is available in StreamConnectionContext.

Capability Methods

These methods tell the gateway about your plugin's requirements. All have default implementations except name(). Custom plugins must explicitly declare response-body production before handling buffered responses.

Protocol Constants

Use these constants in supported_protocols() to declare which proxy protocols your plugin supports:

Factory Function

Every plugin file must export a create_plugin function. This is the only required entry point — the build script discovers it automatically. Config is passed in as a raw &serde_json::Value; returning Err rejects the config at admission time.

pub fn create_plugin(
    config: &Value,
    _http_client: PluginHttpClient,
) -> Result<Option<Arc<dyn Plugin>>, String> {
    Ok(Some(Arc::new(MyPlugin::new(config)?)))
}

Full Example: Header Injection Plugin

Adds a configurable X-Custom-Gateway header to every proxied request and echoes it back in the response. The repository’s complete example lives under custom_plugins/examples/; copy it to custom_plugins/ or select it with FERRUM_CUSTOM_PLUGINS=example_plugin. The abbreviated lifecycle table above is complemented by the full hook contract, including final-header and stream-termination hooks.

use async_trait::async_trait;
use http::HeaderValue;
use serde_json::Value;
use std::collections::HashMap;
use std::sync::Arc;

use crate::plugins::{Plugin, PluginHttpClient, PluginResult, RequestContext, ResponseBodyProduction, TransactionSummary};

pub struct ExamplePlugin {
    header_value: String,
}

impl ExamplePlugin {
    pub fn new(config: &Value) -> Result<Self, String> {
        let object = config.as_object().ok_or("config must be an object")?;
        if object.keys().any(|key| key != "header_value") {
            return Err("unknown configuration field".into());
        }
        let value = match object.get("header_value") {
            None => "ferrum-custom",
            Some(Value::String(value)) => value,
            Some(_) => return Err("header_value must be a string".into()),
        };
        if value.len() > 8192 {
            return Err("header_value exceeds 8192 bytes".into());
        }
        HeaderValue::from_str(value).map_err(|_| "invalid header value")?;
        Ok(Self { header_value: value.to_string() })
    }
}

#[async_trait]
impl Plugin for ExamplePlugin {
    fn name(&self) -> &str {
        "example_plugin"
    }

    fn priority(&self) -> u16 {
        // Default band — runs after transforms, before logging.
        super::super::plugins::priority::DEFAULT
    }

    fn response_body_production(&self) -> ResponseBodyProduction {
        ResponseBodyProduction::Never
    }

    fn modifies_request_headers(&self) -> bool {
        true
    }

    async fn on_request_received(&self, _ctx: &mut RequestContext) -> PluginResult {
        PluginResult::Continue
    }

    async fn before_proxy(
        &self,
        _ctx: &mut RequestContext,
        headers: &mut HashMap<String, String>,
    ) -> PluginResult {
        headers.insert("x-custom-gateway".to_string(), self.header_value.clone());
        PluginResult::Continue
    }

    async fn after_proxy(
        &self,
        _ctx: &mut RequestContext,
        _response_status: u16,
        response_headers: &mut HashMap<String, String>,
    ) -> PluginResult {
        response_headers.insert("x-custom-gateway".to_string(), self.header_value.clone());
        PluginResult::Continue
    }

    async fn log(&self, _summary: &TransactionSummary) {
        // Fire-and-forget: send to a logging endpoint, write to a file, etc.
    }
}

/// Factory function — called by the build-script-generated registry.
pub fn create_plugin(
    config: &Value,
    _http_client: PluginHttpClient,
) -> Result<Option<Arc<dyn Plugin>>, String> {
    Ok(Some(Arc::new(ExamplePlugin::new(config)?)))
}

Database Migrations

Plugins that need their own tables can declare migrations via plugin_migrations(). These are auto-discovered by the build script and run alongside core gateway migrations when FERRUM_MODE=migrate FERRUM_MIGRATE_ACTION=up is executed.

use crate::config::migrations::CustomPluginMigration;

pub fn plugin_migrations() -> Vec<CustomPluginMigration> {
    vec![CustomPluginMigration {
        version: 1,
        name: "create_audit_log",
        checksum: "v1_create_audit_log_example",
        sql: "CREATE TABLE audit_log (id VARCHAR(255) PRIMARY KEY, message TEXT NOT NULL)",
        sql_postgres: None,
        sql_mysql: None,
    }]
}

Running migrations

FERRUM_MODE=migrate FERRUM_MIGRATE_ACTION=up cargo run -- run

Build-time Filtering

Set FERRUM_CUSTOM_PLUGINS at build time to include only specific plugins. If unset, all .rs files in custom_plugins/ are compiled in.

FERRUM_CUSTOM_PLUGINS=my_plugin,audit_plugin cargo build --release

Best Practices