Skip to content

Commit 2ea6db6

Browse files
enisdenjoenisdenjo
authored
Hive Router Runtime in Gateway (#7247)
1 parent a606559 commit 2ea6db6

File tree

2 files changed

+140
-0
lines changed

2 files changed

+140
-0
lines changed

‎packages/web/docs/src/content/gateway/other-features/_meta.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
export default {
22
index: 'Overview',
3+
'router-runtime': 'Router Runtime',
34
'upstream-reliability': 'Upstream Reliability',
45
performance: 'Performance & Cache',
56
security: 'Security',

‎packages/web/docs/src/content/gateway/other-features/router-runtime.mdx‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
import { Callout, Tabs } from '@theguild/components'
2+
3+
## Introduction
4+
5+
Hive Gateway can now use parts of [Hive Router's](/docs/router) runtime, like the Query Planner,
6+
introducing a new federation query planner in JavaScript that aims to optimize query execution
7+
performance by using Rust Hive Router's advanced planning algorithms through native addons.
8+
9+
This integration allows Hive Gateway to leverage the high-performance capabilities of Hive Router's
10+
runtime while still operating within the Node.js or Bun environment and offering the full suite of
11+
JavaScript's ecosystem back to Hive Router.
12+
13+
## Getting Started
14+
15+
Start by installing the necessary package:
16+
17+
```sh npm2yarn
18+
npm install @graphql-hive/router-runtime
19+
```
20+
21+
Then, configure your Hive Gateway to use the Hive Router Runtime by updating your gateway's
22+
configuration:
23+
24+
<Tabs items={['CLI', "Programmatic Usage"]}>
25+
26+
<Tabs.Tab>
27+
28+
You can either run Hive Gateway with a truthy `HIVE_ROUTER_RUNTIME` environment variable:
29+
30+
```sh
31+
HIVE_ROUTER_RUNTIME=true hive-gateway supergraph
32+
```
33+
34+
or use the `--hive-router-runtime` flag:
35+
36+
```sh
37+
hive-gateway supergraph --hive-router-runtime
38+
```
39+
40+
or provide the Router Runtime in your config file:
41+
42+
```ts filename="gateway.config.ts"
43+
import { defineConfig } from '@graphql-hive/gateway'
44+
import { unifiedGraphHandler } from '@graphql-hive/router-runtime'
45+
46+
export const gatewayConfig = defineConfig({
47+
unifiedGraphHandler
48+
})
49+
```
50+
51+
</Tabs.Tab>
52+
53+
<Tabs.Tab>
54+
55+
```ts filename="index.ts"
56+
import { createGatewayRuntime } from '@graphql-hive/gateway-runtime'
57+
import { unifiedGraphHandler } from '@graphql-hive/router-runtime'
58+
59+
export const gateway = createGatewayRuntime({
60+
unifiedGraphHandler
61+
})
62+
```
63+
64+
</Tabs.Tab>
65+
66+
</Tabs>
67+
68+
## Compared to Default Runtime
69+
70+
Hive Gateway uses the [Stitching Runtime](https://the-guild.dev/graphql/stitching) by default, which
71+
is a pure JavaScript implementation designed for flexibility and ease of use. The Stitching Runtime
72+
is well-suited for most applications, providing a robust and adaptable solution for GraphQL
73+
federation.
74+
75+
While Router Runtime provides superior performance for many workloads, it sacrifices some of the
76+
flexibility and extensibility of the Default Runtime.
77+
78+
The following table provides a comprehensive comparison between the two runtimes:
79+
80+
| Feature | Stitching | Router | Notes |
81+
| ---------------------------- | --------- | --------------------- | ----------------------------------------------------------------------------------------------- |
82+
| Additional resolvers | ✅ | ❌ | Additional type resolvers not supported |
83+
| Schema transforms | ✅ | ❌ | Schema transformation pipeline not available in router runtime |
84+
| Progressive Override | ✅ | ❌ | Apollo Federation's `@override` directive not supported at the moment |
85+
| Rate limiting | ✅ | ❌ | Field-level and global rate limiting not supported |
86+
| EDFS | ✅ | ❌ | Event-Driven Federation Subscriptions are not supported because it uses additional resolvers |
87+
| Subscriptions | ✅ | ⚠️ Limited support | Cannot populate fields from other subgraphs when resolving the subscription |
88+
| Schema extensions | ✅ | ⚠️ Limited support | Schema-level modifications may be limited because hive router does not use an executable schema |
89+
| Custom plugins | ✅ | ⚠️ No stitching hooks | All plugins, except those using [stitching hooks](#no-default-runtime-plugin-hooks), will work |
90+
| Envelop plugins | ✅ | ✅ | All of envelop plugins will work |
91+
| Yoga plugins | ✅ | ✅ | All of Yoga plugins will work |
92+
| Gateway plugins | ✅ | ✅ | All gateway plugins will work |
93+
| Transports | ✅ | ✅ | All transports that Hive Gateway supports work. HTTP, WS, SSE, gRPC, etc. |
94+
| Federation Query Planning | ✅ | ✅ | Router runtime uses advanced Rust query planner for better performance |
95+
| Response caching | ✅ | ✅ | In-memory and distributed caching (Redis, etc.) |
96+
| Request batching | ✅ | ✅ | Automatic batching of requests to subgraphs |
97+
| Parsing & validation caching | ✅ | ✅ | Document parsing and validation optimization |
98+
| Query cost analysis | ✅ | ✅ | Query complexity and cost analysis |
99+
| Prometheus metrics | ✅ | ✅ | Standard metrics collection and export |
100+
| OpenTelemetry tracing | ✅ | ✅ | Distributed tracing and span creation |
101+
| Custom spans | ✅ | ✅ | Custom instrumentation can be added |
102+
| Request logging | ✅ | ✅ | Request/response logging and auditing |
103+
| JWT authentication | ✅ | ✅ | JSON Web Token validation and propagation |
104+
| Depth limiting | ✅ | ✅ | Query depth and complexity analysis |
105+
| Max tokens | ✅ | ✅ | Token-based request limiting |
106+
| HMAC signing | ✅ | ✅ | Inter-service request signing and verification |
107+
| Persisted documents | ✅ | ✅ | Operation allow-listing and security |
108+
| Request plugins | ✅ | ✅ | Request-level processing and modification |
109+
| Response plugins | ✅ | ✅ | Response-level processing and modification |
110+
111+
## No Default Runtime Plugin Hooks
112+
113+
All plugin hooks will work with Router Runtime except for those specific to stitching that will
114+
never work because the runtime is different (router runtime vs. stitching runtime).
115+
116+
Those hooks are only the following two hooks:
117+
118+
- [`onDelegationPlan`](/docs/gateway/other-features/custom-plugins#ondelegationplan)
119+
- [`onDelegationStageExecute`](/docs/gateway/other-features/custom-plugins#ondelegationstageexecute)
120+
121+
## Federation Specification Compliance
122+
123+
Hive Gateway with Router Runtime maintains 100% compatibility in the
124+
[Federation-Compatibility Audit](https://the-guild.dev/graphql/hive/federation-gateway-audit). This
125+
ensures that your federated GraphQL architecture remains standards-compliant and interoperable
126+
across different Federation implementations.
127+
128+
## Benchmarks
129+
130+
<Callout type="info" emoji="🚀">
131+
132+
Performance gains are achieved while maintaining full compatibility with Federation specification
133+
and providing better resource efficiency for production deployments.
134+
135+
</Callout>
136+
137+
Based on our measurements and performance testing, the Router Runtime demonstrates significant
138+
performance improvements over the Default Runtime with **up to 3x faster query planning per core**
139+
thanks to the Rust-powered query planner.

0 commit comments

Comments
 (0)