Hive Router Plugin System

TL;DR: Hive Router v0.0.40 ships a native plugin system. Write custom Rust plugins that hook into any stage of the request lifecycle, from the HTTP layer all the way to subgraph execution.

Hive Router v0.0.40 introduces a plugin system that lets you extend and customize the router’s behavior using native Rust code. Plugins can add authentication, observability, caching, error masking, or any other custom logic you need!

How it works

The plugin system is built around the RouterPlugin trait, exposed through the hive-router crate. Implement the trait on your struct, attach hooks for the lifecycle stages you care about, and register your plugin at startup.

1. Add the dependency

Cargo.toml

[dependencies]
hive-router = "0.0.40"

2. Implement a plugin

src/plugin.rs

use hive_router::plugins::plugin_trait::RouterPlugin;

// Declare and implement a simple plugin with no configuration and no hooks.
struct MyPlugin;

#[async_trait]
impl RouterPlugin for MyPlugin {
    // You can override this and add a custom config to your plugin
    type Config = ();

    fn plugin_name() -> &'static str {
        "my_plugin"
    }

    // Your hooks implementation goes here...
}

3. Register the plugin

src/main.rs

use hive_router::{
    configure_global_allocator, error::RouterInitError, init_rustls_crypto_provider,
    router_entrypoint, PluginRegistry, RouterGlobalAllocator,
};

configure_global_allocator!();

// This is the main entrypoint of the Router
#[hive_router::main]
async fn main() -> Result<(), RouterInitError> {
    // Configure Hive Router to use the OS's default certificate store
    init_rustls_crypto_provider();

    // Start and run the router entrypoint with your plugin
    router_entrypoint(
        PluginRegistry::new().register::<MyPlugin>(),
    )
    .await
}

4. Enable in configuration

router.config.yaml

plugins:
  my_plugin:
    enabled: true

Available hooks

Plugins can intercept any stage of the request and router lifecycle:

Hook	When it fires
`on_plugin_init`	Router startup: initialize state, register background tasks
`on_http_request`	Incoming HTTP request: auth, header inspection
`on_graphql_params`	GraphQL params extracted: modify query/variables
`on_graphql_parse`	Before AST parsing
`on_graphql_validation`	Schema validation: add custom rules
`on_query_plan`	Federation query planning
`on_execute`	Query execution: caching, result inspection
`on_subgraph_execute`	Subgraph request preparation
`on_subgraph_http_request`	HTTP call to a subgraph: modify headers, track responses
`on_graphql_error`	Per-error hook before sending to client: error masking/transformation
`on_supergraph_load`	Supergraph load/reload: cache invalidation, schema inspection
`on_shutdown`	Router shutdown: cleanup, flush data