Docs
Launch GraphOS Studio

Writing native Rust plugins for the Apollo Router

Extend the Apollo Router with custom Rust code


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

  • Authentication/authorization
  • Logging
  • tracing

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

⚠️ Apollo doesn't recommend creating native plugins for the Apollo Router, for the following reasons:

  • Native plugins require familiarity with programming in Rust.
  • Native plugins require compiling a custom binary from source, which can introduce unexpected behavior in your router that's difficult to diagnose and support.

Instead, for most customizations, Apollo recommends creating either a Rhai script or an external coprocessor. Both of these customizations are supported by Apollo and provide strong separation of concerns and fault isolation.

If you must create a native plugin, please open a GitHub issue, and Apollo can investigate adding the custom capability to the stock binary.

NOTE

The source code and all its distributions are made available under the Elastic License v2.0 (ELv2) license.

Planning a plugin

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

For descriptions of these services, see Router request lifecycle.

Building a plugin

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

1. Add modules

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

hello_world.rs
use apollo_router::plugin::Plugin;
use apollo_router::register_plugin;
use apollo_router::services::*;
use schemars::JsonSchema;
use serde::Deserialize;
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:

hello_world.rs
#[derive(Debug, Default, Deserialize, JsonSchema)]
struct Conf {
// Put your plugin configuration here. It's deserialized from YAML automatically.
}

Note: You need to derive JsonSchema so that your configuration can participate in JSON schema generation.

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

hello_world.rs
#[async_trait::async_trait]
impl Plugin for HelloWorld {
type Config = Conf;
}

3. Implement the Plugin trait

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

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

hello_world.rs
// This is a bare-bones plugin that you can duplicate when creating your own.
use apollo_router::plugin::PluginInit;
use apollo_router::plugin::Plugin;
use apollo_router::services::*;
#[async_trait::async_trait]
impl Plugin for HelloWorld {
type Config = Conf;
// This is invoked once after the router starts and compiled-in
// plugins are registered
fn new(init: PluginInit<Self::Config>) -> Result<Self, BoxError> {
Ok(HelloWorld { configuration: init.config })
}
// Only define the hooks you need to modify. Each default hook
// implementation returns its associated service with no changes.
fn router_service(
&self,
service: router::BoxService,
) -> router::BoxService {
service
}
fn supergraph_service(
&self,
service: router::BoxService,
) -> router::BoxService {
service
}
fn execution_service(
&self,
service: execution::BoxService,
) -> execution::BoxService {
service
}
// Unlike other hooks, this hook also passes the name of the subgraph
// being invoked. That's because this service might invoke *multiple*
// subgraphs for a single request, and this is called once for each.
fn subgraph_service(
&self,
name: &str,
service: subgraph::BoxService,
) -> subgraph::BoxService {
service
}
}

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.

hello_world.rs
// Replaces the default definition in the example above
use tower::ServiceBuilderExt;
use apollo_router::ServiceBuilderExt as ApolloServiceBuilderExt;
fn supergraph_service(
&self,
service: router::BoxService,
) -> router::BoxService {
// Always use service builder to compose your plugins.
// It provides off-the-shelf building blocks for your plugin.
ServiceBuilder::new()
// Some example service builder methods:
// .map_request()
// .map_response()
// .rate_limit()
// .checkpoint()
// .timeout()
.service(service)
.boxed()
}

The tower-rs library (which the 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 required 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.
  • oneshot_checkpoint_async - Perform an async call to decide if the request should proceed or not. e.g. for Authentication. Does not require buffered and should be preferred to checkpoint_async for that reason.
  • instrument - Add a tracing span around a service.
  • map_request - 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 SupergraphService might be required by SubgraphServices.
  • Cache control headers from SubgraphServices might be aggregated and returned to the client by the SupergraphService.

Whenever the 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

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.

If multiple threads might write a value to the same context key, use upsert instead.

get

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

Fetches a value from the context object.

upsert

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 multithreaded, 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 to discover your plugin, you need to register the plugin.

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

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

For example:

hello_world.rs
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 need to add configuration for it to your YAML configuration file in the plugins: section:

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

Add custom metrics

NOTE

Make sure to enable prometheus metrics in your configuration if you want to have metrics generated by the .

Using macros

To create your custom metrics in Prometheus you can use the tracing macros to generate an event. If you observe a specific naming pattern for your event you'll be able to generate your own custom metrics directly in Prometheus.

To publish a new metric, use tracing macros to generate an event that contains one of the following prefixes:

monotonic_counter. (non-negative numbers): Used when the metric will only ever increase. counter.: For when the metric may increase or decrease over time. value.: For discrete data points (i.e., when taking the sum of values does not make semantic sense) histogram.: For building histograms (takes f64)

Examples:

use tracing::info;
let loading_time = std::time::Instant::now();
info!(monotonic_counter.foo = 1, my_custom_label = "bar"); // Will increment the monotonic counter foo by 1
// Generated metric for the example above in prometheus
// foo{my_custom_label="bar"} 1
info!(monotonic_counter.bar = 1.1);
info!(counter.baz = 1, name = "baz"); // Will increment the counter baz by 1
info!(counter.baz = -1); // Will decrement the counter baz by 1
info!(counter.xyz = 1.1);
info!(value.qux = 1);
info!(value.abc = -1);
info!(value.def = 1.1);
let caller = "router";
tracing::info!(
histogram.loading_time = loading_time.elapsed().as_secs_f64(),
kind = %caller, // Custom attribute for the metrics
);

Plugin Lifecycle

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

Creation

When the starts or reloads, it calls new to create instances of plugins that have configuration in the plugins: section of the YAML configuration file. If any of these calls fail, the 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.

Request and response lifecycle

Within a given service (, , etc.), a request is handled in the following order:

The corresponding response is handled in the opposite order. This ordering is relevant for communicating through the context object.

When a single request involves multiple requests, the handling of each subgraph request and response is ordered as above but different subgraph requests may be handled in parallel, making their relative ordering non-deterministic.

Router lifecycle notes

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

Before switching to an updated configuration, the 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 .

After the new configuration is deemed valid, the 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.

NOTE

If you need a unique identifier for your request, use the functionality provided in the apollo_router::tracer module.

Previous
External coprocessing
Next
Custom router binary
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company