Router Runtime | Hive Gateway

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:

You can either run Hive Gateway with a truthy HIVE_ROUTER_RUNTIME environment variable:


HIVE_ROUTER_RUNTIME=true hive-gateway supergraph

or use the --hive-router-runtime flag:


hive-gateway supergraph --hive-router-runtime

or provide the Router Runtime in your config file:

gateway.config.ts


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

Compared to Default Runtime

Hive Gateway uses the Stitching Runtime by default, 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 Default 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
Rate limiting	✅	❌	Field-level and global rate limiting not supported
EDFS	✅	❌	Event-Driven Federation Subscriptions are not supported because it uses additional resolvers
Subscriptions	✅	⚠️ Limited support	Cannot populate fields from other subgraphs when resolving the subscription
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
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 Default 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 only the following two hooks:

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 measurements and performance testing, the Router Runtime demonstrates significant performance improvements over the Default Runtime with up to 3x faster query planning per core thanks to the Rust-powered query planner.