Writing native Rust plugins for the Apollo Router

Your federated graph might have specific requirements that aren't supported by the Apollo Router's built-in configuration options. For example, you might need to further customize the behavior of:

• Authentication/authorization
• Logging
• Operation tracing

In these cases, you can create custom plugins for the Apollo Router.

Planning a plugin

When designing a new plugin, you first want to determine which of the Apollo Router's services the plugin should hook into to achieve its use case.

For descriptions of these services, see How router plugins work.

Building a plugin

To demonstrate building a plugin, we'll walk through the hello world example plugin in the Router repo.

1. Add modules

Most plugins should start by including the following set of use declarations:

1
use apollo_router_core::plugin::Plugin;
2
use apollo_router_core::{
3
    register_plugin, ExecutionRequest, ExecutionResponse, QueryPlannerRequest,
4
    QueryPlannerResponse, RouterRequest, RouterResponse, SubgraphRequest, SubgraphResponse,
5
};
6
use schemars::JsonSchema;
7
use serde::Deserialize;
8
use tower::util::BoxService;
9
use tower::{BoxError, ServiceBuilder, ServiceExt};

When your plugin is complete, the compiler will provide helpful warnings if any of these modules aren't necessary. Your plugin can also use modules from other crates as needed.

2. Define your configuration

All plugins require an associated configuration. At a minimum, this configuration contains a boolean that indicates whether the plugin is enabled, but it can include anything that can be deserialized by serde.

Create your configuration struct like so:

1
#[derive(Debug, Default, Deserialize, JsonSchema)]
2
struct Conf {
3
    // Put your plugin confguration here. It's deserialzed from YAML automatically.
4
}

Then define the plugin itself and specify the configuration as an associated type:

1
#[async_trait::async_trait]
2
impl Plugin for HelloWorld {
3
    type Config = Conf;
4
}

3. Implement the Plugin trait

All router plugins must implement the Plugin trait. This trait defines lifecycle hooks that enable hooking into Apollo Router services.

The trait also provides a default implementations for each hook, which returns the associated service unmodified.

1
// This is a bare-bones plugin that you can duplicate when creating your own.
2
#[async_trait::async_trait]
3
impl Plugin for HelloWorld {
4
    type Config = Conf;
5

6
    // This is invoked once after the router starts and compiled-in
7
    // plugins are registered
8
    fn new(configuration: Self::Config) -> Result<Self, BoxError> {
9
        Ok(HelloWorld { configuration })
10
    }
11

12
    /// This is invoked after all plugins have been created and we're ready to go live.
13
    /// This method MUST not panic.
14
    fn activate(&mut self);
15

16
    // Only define the hooks you need to modify. Each default hook
17
    // implementation returns its associated service with no changes.
18
    fn router_service(
19
        &mut self,
20
        service: BoxService<RouterRequest, RouterResponse, BoxError>,
21
    ) -> BoxService<RouterRequest, RouterResponse, BoxError> {
22
        service
23
    }
24

25
    fn query_planning_service(
26
        &mut self,
27
        service: BoxService<QueryPlannerRequest, QueryPlannerResponse, BoxError>,
28
    ) -> BoxService<QueryPlannerRequest, QueryPlannerResponse, BoxError> {
29
        service
30
    }
31

32
    fn execution_service(
33
        &mut self,
34
        service: BoxService<ExecutionRequest, ExecutionResponse, BoxError>,
35
    ) -> BoxService<ExecutionRequest, ExecutionResponse, BoxError> {
36
        service
37
    }
38

39
    // Unlike other hooks, this hook also passes the name of the subgraph
40
    // being invoked. That's because this service might invoke *multiple*
41
    // subgraphs for a single request, and this is called once for each.
42
    fn subgraph_service(
43
        &mut self,
44
        name: &str,
45
        service: BoxService<SubgraphRequest, SubgraphResponse, BoxError>,
46
    ) -> BoxService<SubgraphRequest, SubgraphResponse, BoxError> {
47
        service
48
    }
49
}

4. Define individual hooks

To define custom logic for a service hook, you can use ServiceBuilder.

ServiceBuilder provides common building blocks that remove much of the complexity of writing a plugin. These building blocks are called layers.

1
// Replaces the default definition in the example above
2
use tower::ServiceBuilderExt;
3
use apollo_router_core::ServiceBuilderExt as ApolloServiceBuilderExt;
4

5
fn router_service(
6
    &mut self,
7
    service: BoxService<RouterRequest, RouterResponse, BoxError>,
8
) -> BoxService<RouterRequest, RouterResponse, BoxError> {
9
    // Always use service builder to compose your plugins.
10
    // It provides off-the-shelf building blocks for your plugin.
11
    ServiceBuilder::new()
12
        // Some example service builder methods:
13
        // .map_request()
14
        // .map_response()
15
        // .rate_limit()
16
        // .checkpoint()
17
        // .timeout()
18
        .service(service)
19
        .boxed()
20
}

The tower-rs library (which the Apollo Router is built on) comes with many "off-the-shelf" layers. In addition, Apollo provides layers that cover common functionality and integration with third-party products.

Some notable layers are:

• buffered - Make a service Clone. Typically requred for any async layers.
• checkpoint - Perform a sync call to decide if a request should proceed or not. Useful for validation.
• checkpoint_async - Perform an async call to decide if the request should proceed or not. e.g. for Authentication. Requires buffered.
• instrument - Add a tracing span around a service.
• map_reqeust - Transform the request before proceeding. e.g. for header manipulation.
• map_response - Transform the response before proceeding. e.g. for header manipulation.

Before implementing a layer yourself, always check whether an existing layer implementation might fit your needs. Reusing layers is significantly faster than implementing layers from scratch.

5. Define necessary context

Sometimes you might need to pass custom information between services. For example:

• Authentication information obtained by the RouterService might be required by SubgraphServices.
• Cache control headers from SubgraphServices might be aggregated and returned to the client by the RouterService.

Whenever the Apollo Router receives a request, it creates a corresponding context object and passes it along to each service. This object can store anything that's Serde-compatible (e.g., all simple types or a custom type).

All of your plugin's hooks can interact with the context object using the following functions:

insert

1
context.insert("key1", 1)?;

Adds a value to the context object. Serialization and deserialization happen automatically. You might sometimes need to specify the type in cases where the Rust compiler can't figure it out by itself.

get

1
let value : u32 = context.get("key1")?;

Fetches a value from the context object.

upsert

1
context.upsert("key1", |v: u32| v + 1)?;

Use upsert if you might need to resolve multiple simultaneous writes to a single context key (this is most likely for the subgraph_service hook, because it might be called by multiple threads in parallel). Rust is multi-threaded, and you will get unexpected results if multiple threads write to context at the same time. This function prevents issues by guaranteeing that modifications happen serially.

Note: upsert requires v to implement Default.

6. Register your plugin

To enable the Apollo Router to discover your plugin, you need to register the plugin.

To do so, use the register_plugin!() macro provided by apollo-router-core. This takes 3 arguments:

• A group name
• A plugin name
• A struct implementing the Plugin trait

For example:

1
register_plugin!("example", "hello_world", HelloWorld);

Choose a group name that represents your organization and a name that represents your plugin's functionality.

7. Configure your plugin

After you register your plugin, you can add custom configuration for it to your YAML configuration file in the plugins: section:

1
plugins:
2
  example.hello_world:
3
    # Any values here are passed to the plugin as part of your configuration

Plugin Lifecycle

Like individual requests, plugins follow their own strict lifecycle that helps provide structure to the Apollo Router's execution.

Creation

When the router starts, all plugins included in the executable are registered. At this time, the router calls the new method of all plugins. If any of these methods fail, the router terminates with helpful error messages.

There is no sequencing for plugin registration, and registrations might even execute in parallel. A plugin should never rely on the existence of another plugin during initialization.

Activate

When the router is ready to start serving requests, it calls each plugin's activate method. Plugins are started in the same order they're declared in your YAML configuration file.

Note that if a plugin is registered but is not listed in the configuration file, the router does not call startup on it. If any plugin fails to start, the router terminates with helpful error messages.

Lifecycle notes

If a router is listening for dynamic changes to its configuration, it also triggers lifecycle events when those changes occur.

Before switching to an updated configuration, the router ensures that the new configuration is valid. This process includes starting up replacement plugins for the new configuration. This means that a plugin should not assume that it's the only executing instance of that plugin in a single router.

After the new configuration is deemed valid, the router shifts to it. The previous configuration is dropped and its corresponding plugins are shut down. Errors during the shutdown of these plugins are logged and do not affect router execution.

Testing plugins

Unit testing of a plugin is typically most helpful and there are extensive examples of plugin testing in the examples and plugins directories.