docs(router): native plugin system API by ardatan · Pull Request #7387 · graphql-hive/console

ardatan · 2025-12-08T12:56:56Z

Documentation of graphql-hive/router#482

gemini-code-assist · 2025-12-08T12:57:09Z

Summary of Changes

Hello @ardatan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on enhancing the documentation for the Hive Router, specifically by adding a comprehensive guide on its native plugin system. The new guide empowers developers to extend the router's functionality using custom Rust plugins, covering everything from initial setup to advanced concepts like lifecycle hooks, context sharing, and configuration. This addition significantly improves the extensibility and customizability of the router for users.

Highlights

New Documentation for Native Plugin System: This pull request introduces extensive documentation for extending the Hive Router with native Rust plugins, detailing how to customize its behavior.
Detailed Plugin Lifecycle Hooks: The new guide provides in-depth explanations of various lifecycle hooks available for plugins, such as on_http_request, on_graphql_params, on_graphql_parse, on_graphql_validation, on_query_plan, on_execute, on_subgraph_execute, and on_subgraph_http_request.
Plugin Development Guidance: The documentation covers practical aspects of plugin development, including setting up a Rust project, designing plugins, handling short-circuit responses, overriding default behavior, sharing context data between hooks, configuring plugins via router.config.yaml, and registering them.
Dependency Updates: The Cargo.lock file has been updated to increment the versions of hive-apollo-router-plugin from 2.3.3 to 2.3.4 and hive-console-sdk from 0.2.0 to 0.2.1.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

github-actions · 2025-12-08T12:58:34Z

🚀 Snapshot Release (`alpha`)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
`hive`	`9.5.0-alpha-20260225090709-f7c919f785f3aac7a801ec4a9e0146768e4bef69`	npm ↗︎ unpkg ↗︎

github-actions · 2025-12-08T12:58:55Z

📚 Storybook Deployment

The latest changes are available as preview in: https://pr-7387.hive-storybook.pages.dev

gemini-code-assist

Code Review

This pull request introduces a new comprehensive documentation guide titled "Extending the Router," detailing how to create and configure custom Rust plugins for the Hive Router. The guide covers development setup, the router's plugin lifecycle hooks (e.g., on_http_request, on_graphql_params, on_execute, on_subgraph_execute), methods for short-circuiting responses, overriding default behavior, sharing context data between hooks, and configuring/registering plugins. Additionally, the PR includes minor version updates for hive-apollo-router-plugin and hive-console-sdk in Cargo.lock. Review comments primarily focus on enhancing the new documentation's quality by addressing inconsistent heading levels, correcting typos (e.g., an incorrect Rust version, "seperated"), fixing grammatical errors (e.g., "different the end," "different than"), rectifying comment syntax, and critically, recommending the replacement of unwrap() calls with graceful error handling in code examples to promote safer coding practices.

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+
+### Development Setup
+
+## Create a new Rust project


The heading level is inconsistent with the document structure. This heading is h2 (##), but it's a subsection of ### Development Setup (h3). It should be h3 (###) to maintain the correct hierarchy. This also applies to the other sub-headings in this section on lines 56, 80, and 88.

### Create a new Rust project

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+## Create a new Rust project
+
+First, ensure you have the necessary development environment set up for
+[Rust 1.91.1 or later](https://rust-lang.org/tools/install/). Then, you need to create a new Rust


There seems to be a typo in the required Rust version. 1.91.1 is a future version of Rust. Please verify and correct the required version number.

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+    /// This is where you can register your custom plugins
+    let plugin_registry = PluginRegistry::new();
+    /// Start the Hive Router with the plugin registry


In Rust, /// is used for documentation comments that are part of the public API documentation. Inside a function body, regular comments // are more appropriate.

// This is where you can register your custom plugins let plugin_registry = PluginRegistry::new(); // Start the Hive Router with the plugin registry

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+parameters body expected by GraphQL-over-HTTP spec. But we still need to parse the operation into
+AST.
+
+On the start of this hooks, you can do the following things for example;


Typo: hooks should be singular hook.

On the start of this hook, you can do the following things for example;

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+
+On the end of this hook, you can do the following things for example;
+
+- Prevent certain operations from being executed by checked the HTTP headers or other request


Grammar: checked should be checking.

- Prevent certain operations from being executed by checking the HTTP headers or other request

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+ready along with the coerced variables. So you can block the operation, manipulate the result,
+variables, etc.
+
+This is different the end of `on_query_plan` hook because we don't have all the parameters ready


Grammar: different the end should be different from the end.

This is different from the end of `on_query_plan` hook because we don't have all the parameters ready

gemini-code-assist · 2025-12-08T13:00:25Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+variables, etc.
+
+This is different the end of `on_query_plan` hook because we don't have all the parameters ready
+like coerced variables, filling the introspection fields that are seperated from the actual planning


Typo: seperated should be separated.

like coerced variables, filling the introspection fields that are separated from the actual planning

gemini-code-assist · 2025-12-08T13:00:26Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+But we still don't have the actual "HTTP" request that would be sent to the subgraph. So this is
+different than `on_subgraph_http_request` hook. So this is before the serialization to HTTP request.


Grammar: different than should be different from.

different from `on_subgraph_http_request` hook. So this is before the serialization to HTTP request.

gemini-code-assist · 2025-12-08T13:00:26Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+            let new_header_value = format!("Hello {}", context_data_entry.incoming_data);
+            payload.execution_request.headers.insert(
+                "x-hello",
+                http::HeaderValue::from_str(&new_header_value).unwrap(),


Using .unwrap() in documentation can be risky as it might encourage unsafe practices. It's better to show robust error handling, especially in a plugin context where panics should be avoided. Consider using if let Ok(header_value) = ... to handle the potential error gracefully.

github-actions · 2025-12-08T13:03:00Z

💻 Website Preview

The latest changes are available as preview in: https://pr-7387.hive-landing-page.pages.dev

github-actions · 2025-12-08T13:04:19Z

🐋 This PR was built and pushed to the following Docker images:

Targets: build

Platforms: linux/amd64

Image Tag: f7c919f785f3aac7a801ec4a9e0146768e4bef69

github-actions · 2025-12-08T13:20:16Z

🐋 This PR was built and pushed to the following Docker images:

Targets: apollo-router-hive-build

Platforms: linux/amd64

Image Tag: 25d5c6db2a644cf7f6e97939f2b45b258da13f87

dotansimha · 2026-01-28T07:06:11Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+### Create a new Rust project
+
+First, ensure you have the necessary development environment set up for
+[Rust 1.91.1 or later](https://rust-lang.org/tools/install/). Then, you need to create a new Rust


How did we decide 1.91.1, I mean, we don't have an official MSRV defined for the Crate (maybe we should?)

dotansimha · 2026-01-28T07:08:07Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+
+```toml
+[dependencies]
+hive-router = "0.17"


ntex dependency is missing here, and it needs to be added because we don't expose it. The main example below assumes that you have ntex and then it fails.

Should be ntex = "2"

dotansimha · 2026-01-28T07:08:38Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+You can use our example supergraph as a starting point;
+
+```bash
+curl -sSL https://federation-demo.theguild.workers.dev/supergraph.graphql > supergraph.graphql


What about subgraphs here? Are they already running somewhere? add a note please

dotansimha · 2026-01-28T07:09:11Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+curl -sSL https://federation-demo.theguild.workers.dev/supergraph.graphql > supergraph.graphql
+```
+
+Then point to that supergraph in your `router.config.yaml`:


Create a test/development config file to help you to easily run the router, call it router.config.yaml and place it in the root of the project:

dotansimha · 2026-01-28T07:10:00Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+  path: ./supergraph.graphql
+```
+
+Or you can use other ways to provide the supergraph, see


I think this is not really needed here, if someone already landed in the custom plugin system, they already know the docs and the fact they can use different sources.

dotansimha · 2026-01-28T07:10:29Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+use hive_router::{PluginRegistry, router_entrypoint, BoxError};
+
+#[ntex::main]
+async fn main() -> Result<(), BoxError> {


BoxError -> RouterInitError

Also missing import for RouterInitError

dotansimha · 2026-01-28T07:11:17Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+```rust
+use hive_router::{PluginRegistry, router_entrypoint, BoxError};
+
+#[ntex::main]


In Hive Router, we are using a custom allocator, and users needs to know that and use it as well, otherwise it might cause unexpected runtime issues.

dotansimha · 2026-01-28T07:15:03Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+Install `hive-router` as a dependency by adding it to your `Cargo.toml` file:
+
+```toml
+[dependencies]


I'm wondering about what needs to be exported from hive-router crate in order to make it easy for users.

We already know that users needs 2 crucial things at the entry point, in order to be able to just create the first main.rs:

ntex (v2)

mimalloc

Should we export from hive-router some defaults in order to make it easier for users? I mean, it can be #[hive_router::main] that wraps ntex::main.

And it can be hive_router::Allocator to be used with #[global_allocator] for the sake of simplicty, or if we'll update this at some point in our codebase.

I can imagine that users who are using a custom build won't deal with custom allocator/http server that's used by Hive-Router, and they will not want to deal with changing/upgrading those depedencies.

dotansimha · 2026-01-28T09:11:08Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+cargo run
+```
+
+### Configure your plugins in `router.config.yaml`


Before this section, we need a dead simple example of creating struct MyPlugin and then implementing the trait for it.

Then, an example snippet on how to register a plugin in the registry.

Then, an example on how to add configuration to the plugin.

And only then, an example on how to configure the plugin the config file.

Having a custom plugin involved 3 different parts and it should be very clear for the user that they need all 3:

Create the plugin (actual implementation)

Register the plugin (to make it available for the router to load)

Enable the plugin and configure it

dotansimha · 2026-01-28T09:11:35Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+    header: 'x-client-id'
+```
+
+## Registration of Plugins


Also, we need to clearly mention that registering a plugin doesn't mean it's activated.

Consider the following case: a plugin is registered but doesn't have configuration. How will it be enabled in the config file?

dotansimha · 2026-01-28T09:21:06Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+specific operation name. So basically this plugin rejects anonymous operations. See the highlighted
+code below;
+
+```rust filename="src/forbid_anon_ops.rs" {33}


While this example is great, it should be simpler. I would try to avoid copying a full plugin code here, and minimize the snippet so it will focus on the end_with_response call and how/when to use it.

dotansimha · 2026-01-28T09:33:03Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+
+#[ntex::main]
+async fn main() -> Result<(), BoxError> {
+    /// This is where you can register your custom plugins


missing init_rustls_crypto_provider
it fails with

Call CryptoProvider::install_default() before this point to select a provider manually, or make sure exactly one of the 'aws-lc-rs' and 'ring' features is enabled.

dotansimha · 2026-01-28T11:31:51Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+- `get_mut<T>(&mut self) -> Option<&mut T>` - Retrieves a mutable reference to the data of type `T`
+  from the context.
+
+## Refresh State on Supergraph Reload


This section needs to be written differently in my opinion:
First, it needs to explain the lifecycle and the fact that a supergraph can change in background.
Then, show the hook and how to respond to it if needed.

And then a seperate section called Depending on Supergraph in your plugin state that explains the usage of ArcSwap and how it can help to avoid these syncing issues

dotansimha · 2026-01-28T11:34:11Z

packages/web/docs/src/content/router/guides/extending-the-router/index.mdx

+
+```toml
+[dependencies]
+hive-router = "0.17"


Also, after a very short while, users need serde and Deserializable for the config. It's not mentioned anywhere on how to install it.

Actually Kamil and I discussed about it before, we will probably re-export things to avoid users to add extra dependencies

Yes, exactly

And it's not only to reduce the amount of dependencies, it's also to make it simpler for users to build plugins without maintaining the dependencies, or even knowing most of them.

Avoiding extra dependencies is part of making it simpler

Documentation > graphql-hive/console#7387 Preview of the docs -> https://pr-7387.hive-landing-page.pages.dev/docs/router/guides/extending-the-router Example plugins -> https://github.com/graphql-hive/router/tree/plugin-system/plugin_examples TODO: - Document why API is implemented in this way and that way (payload.initialize_plugins, OnPluginInitResult type e.g.) - Documentation updates

ardatan added the waiting-on:router-release Do not merge: waiting for Router release that includes this feature. label Dec 8, 2025

github-actions bot deployed to preview December 8, 2025 12:58 View deployment

gemini-code-assist bot reviewed Dec 8, 2025

View reviewed changes

github-actions bot deployed to preview December 8, 2025 13:02 View deployment

github-actions bot deployed to preview December 8, 2025 13:23 View deployment

github-actions bot deployed to preview December 8, 2025 13:27 View deployment

github-actions bot deployed to preview December 8, 2025 14:53 View deployment

github-actions bot deployed to preview December 8, 2025 14:57 View deployment

github-actions bot deployed to preview December 8, 2025 15:27 View deployment

github-actions bot deployed to preview December 8, 2025 15:31 View deployment

github-actions bot deployed to preview January 7, 2026 14:30 View deployment

github-actions bot deployed to preview January 7, 2026 14:34 View deployment

github-actions bot deployed to preview January 7, 2026 15:19 View deployment

github-actions bot deployed to preview January 7, 2026 15:23 View deployment

github-actions bot deployed to preview January 7, 2026 17:29 View deployment

github-actions bot deployed to preview January 7, 2026 17:33 View deployment

ardatan mentioned this pull request Jan 14, 2026

feat(router): plugin system graphql-hive/router#628

Merged

github-actions bot deployed to preview January 15, 2026 14:57 View deployment

github-actions bot deployed to preview January 15, 2026 15:02 View deployment

dotansimha reviewed Jan 28, 2026

View reviewed changes

ardatan force-pushed the plugin-system-doc branch from 0172d0d to 2abb3f5 Compare February 17, 2026 11:19

github-actions bot deployed to preview February 17, 2026 11:25 View deployment

github-actions bot deployed to preview February 17, 2026 12:13 View deployment

github-actions bot deployed to preview February 17, 2026 14:49 View deployment

github-actions bot deployed to preview February 17, 2026 15:06 View deployment

github-actions bot deployed to preview February 17, 2026 17:43 View deployment

ardatan added 19 commits February 25, 2026 04:06

docs(router): native plugin system API

8c83cd3

Go

4bc6bf9

Better

ea92745

Lets go

8f889b2

..

30f93a5

Update docs

0b7fa8e

Correct

ee71354

Go

a04eec8

Correct

3accc4b

Update

6dabb87

Lets go

d472f53

Lets go

2a3a4c3

Fix context var

dfd18f8

Update docs

9447119

..

1f27d3b

Update

46eef8d

No need for highlighting

2695d92

Simplify

edb622f

Simplify

f7c919f

ardatan force-pushed the plugin-system-doc branch from 22ea8ca to f7c919f Compare February 25, 2026 09:06

github-actions bot deployed to preview February 25, 2026 09:12 View deployment


		On the end of this hook, you can do the following things for example;

		- Prevent certain operations from being executed by checked the HTTP headers or other request

		But we still don't have the actual "HTTP" request that would be sent to the subgraph. So this is
		different than `on_subgraph_http_request` hook. So this is before the serialization to HTTP request.

Conversation

ardatan commented Dec 8, 2025

Uh oh!

gemini-code-assist bot commented Dec 8, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Snapshot Release (alpha)

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Storybook Deployment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💻 Website Preview

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 8, 2025 •

edited

Loading

🚀 Snapshot Release (`alpha`)

github-actions bot commented Dec 8, 2025 •

edited

Loading

github-actions bot commented Dec 8, 2025 •

edited

Loading

github-actions bot commented Dec 8, 2025 •

edited

Loading

github-actions bot commented Dec 8, 2025 •

edited

Loading