Custom Plugin Development

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

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

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

pub struct ExamplePlugin {
    header_value: String,
}

impl ExamplePlugin {
    pub fn new(config: &Value) -> Result<Self, String> {
        Ok(Self {
            // Read config from the plugin's JSON config block:
            //   { "plugin_name": "example_plugin", "config": { "header_value": "my-gateway" } }
            header_value: config["header_value"]
                .as_str()
                .unwrap_or("ferrum-custom")
                .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 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)?)))
}

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

pub fn plugin_migrations() -> Vec<CustomPluginMigration> {
    vec![
        CustomPluginMigration {
            version: 1,
            name: "create_audit_log",
            checksum: "v1_create_audit_log_f8a3e1",
            // Default SQL (SQLite-compatible)
            sql: r#"
                CREATE TABLE IF NOT EXISTS audit_log (
                    id TEXT PRIMARY KEY,
                    timestamp TEXT NOT NULL,
                    client_ip TEXT NOT NULL,
                    http_method TEXT NOT NULL,
                    request_path TEXT NOT NULL,
                    response_status INTEGER NOT NULL,
                    latency_ms REAL NOT NULL,
                    consumer_username TEXT,
                    proxy_id TEXT
                );
                CREATE INDEX IF NOT EXISTS idx_audit_log_timestamp ON audit_log (timestamp)
            "#,
            // PostgreSQL override: use TIMESTAMPTZ and JSONB
            sql_postgres: Some(r#"
                CREATE TABLE IF NOT EXISTS audit_log (
                    id TEXT PRIMARY KEY,
                    timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
                    ...
                    request_headers JSONB
                );
                CREATE INDEX IF NOT EXISTS idx_audit_log_timestamp ON audit_log (timestamp)
            "#),
            // MySQL override: use DATETIME(3) and JSON
            sql_mysql: Some(r#"
                CREATE TABLE IF NOT EXISTS audit_log (
                    id VARCHAR(255) PRIMARY KEY,
                    timestamp DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
                    ...
                    request_headers JSON
                )
            "#),
        },
    ]
}

FERRUM_MODE=migrate FERRUM_MIGRATE_ACTION=up cargo run

FERRUM_CUSTOM_PLUGINS=my_plugin,audit_plugin cargo build --release