Router Runtime

🚧

This feature is EXPERIMENTAL and is subject to extensive change in future releases. Some features might not work as expected or at all, and the API might change at any time. Please use with caution!

Introduction

Hive Gateway can now use parts of Hive Router’s runtime, like the Query Planner, introducing a new federation query planner in JavaScript that aims to optimize query execution performance by using Rust Hive Router’s advanced planning algorithms through native addons.

This integration allows Hive Gateway to leverage the high-performance capabilities of Hive Router’s runtime while still operating within the Node.js or Bun environment and offering the full suite of JavaScript’s ecosystem back to Hive Router.

Getting Started

Start by installing the necessary package:


npm install @graphql-hive/router-runtime


pnpm add @graphql-hive/router-runtime


yarn add @graphql-hive/router-runtime


bun add @graphql-hive/router-runtime

Then, configure your Hive Gateway to use the Hive Router Runtime by updating your gateway’s configuration:

gateway.config.ts


import { defineConfig } from '@graphql-hive/gateway'
import { unifiedGraphHandler } from '@graphql-hive/router-runtime'
 
export const gatewayConfig = defineConfig({
  unifiedGraphHandler
})

Compared to Stitching Runtime

By default, Hive Gateway uses the Stitching Runtime, which is a pure JavaScript implementation designed for flexibility and ease of use. The Stitching Runtime is well-suited for most applications, providing a robust and adaptable solution for GraphQL federation.

While Router Runtime provides superior performance for many workloads, it sacrifices some of the flexibility and extensibility of the Stitching Runtime.

The following table provides a comprehensive comparison between the two runtimes:

Feature	Stitching	Router	Notes
Additional resolvers	✅	❌	Additional type resolvers not supported
Schema transforms	✅	❌	Schema transformation pipeline not available in router runtime
Progressive Override	✅	❌	Apollo Federation’s `@override` directive not supported at the moment
Schema extensions	✅	⚠️ Limited support	Schema-level modifications may be limited because hive router does not use an executable schema
Custom plugins	✅	⚠️ No stitching hooks	All plugins, except those using stitching hooks, will work
Envelop plugins	✅	✅	All of envelop plugins will work
Yoga plugins	✅	✅	All of Yoga plugins will work
Gateway plugins	✅	✅	All gateway plugins will work
Transports	✅	✅	All transports that Hive Gateway supports work. HTTP, WS, SSE, gRPC, etc.
Federation Query Planning	✅	✅	Router runtime uses advanced Rust query planner for better performance
Response caching	✅	✅	In-memory and distributed caching (Redis, etc.)
Request batching	✅	✅	Automatic batching of requests to subgraphs
Parsing & validation caching	✅	✅	Document parsing and validation optimization
Query cost analysis	✅	✅	Query complexity and cost analysis
Prometheus metrics	✅	✅	Standard metrics collection and export
OpenTelemetry tracing	✅	✅	Distributed tracing and span creation
Custom spans	✅	✅	Custom instrumentation can be added
Request logging	✅	✅	Request/response logging and auditing
JWT authentication	✅	✅	JSON Web Token validation and propagation
Rate limiting	✅	✅	Field-level and global rate limiting
Depth limiting	✅	✅	Query depth and complexity analysis
Max tokens	✅	✅	Token-based request limiting
HMAC signing	✅	✅	Inter-service request signing and verification
Persisted documents	✅	✅	Operation allow-listing and security
Request plugins	✅	✅	Request-level processing and modification
Response plugins	✅	✅	Response-level processing and modification

No Stitching Runtime Plugin Hooks

All plugin hooks will work with Router Runtime except for those specific to stitching that will never work because the runtime is different (router runtime vs stitching runtime). Those hooks are:

Federation Specification Compliance

Hive Gateway with Router Runtime maintains 100% compatibility in the Federation-Compatibility Audit. This ensures that your federated GraphQL architecture remains standards-compliant and interoperable across different Federation implementations.

Benchmarks

🚀

Performance gains are achieved while maintaining full compatibility with Federation specification and providing better resource efficiency for production deployments.

Based on our internal measurements and performance testing, the Router Runtime demonstrates significant performance improvements over the Stitching Runtime with up to 3x faster query planning thanks to the Rust-powered query planner.