diff --git a/packages/web/docs/src/content/gateway/other-features/_meta.ts b/packages/web/docs/src/content/gateway/other-features/_meta.ts index 578305e99c9..ac580dddd96 100644 --- a/packages/web/docs/src/content/gateway/other-features/_meta.ts +++ b/packages/web/docs/src/content/gateway/other-features/_meta.ts @@ -1,5 +1,6 @@ export default { index: 'Overview', + 'router-runtime': 'Router Runtime', 'upstream-reliability': 'Upstream Reliability', performance: 'Performance & Cache', security: 'Security', diff --git a/packages/web/docs/src/content/gateway/other-features/router-runtime.mdx b/packages/web/docs/src/content/gateway/other-features/router-runtime.mdx new file mode 100644 index 00000000000..a01a0d5cf36 --- /dev/null +++ b/packages/web/docs/src/content/gateway/other-features/router-runtime.mdx @@ -0,0 +1,139 @@ +import { Callout, Tabs } from '@theguild/components' + +## Introduction + +Hive Gateway can now use parts of [Hive Router's](/docs/router) 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: + +```sh npm2yarn +npm install @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: + +```sh +HIVE_ROUTER_RUNTIME=true hive-gateway supergraph +``` + +or use the `--hive-router-runtime` flag: + +```sh +hive-gateway supergraph --hive-router-runtime +``` + +or provide the Router Runtime in your config file: + +```ts filename="gateway.config.ts" +import { defineConfig } from '@graphql-hive/gateway' +import { unifiedGraphHandler } from '@graphql-hive/router-runtime' + +export const gatewayConfig = defineConfig({ + unifiedGraphHandler +}) +``` + + + + + +```ts filename="index.ts" +import { createGatewayRuntime } from '@graphql-hive/gateway-runtime' +import { unifiedGraphHandler } from '@graphql-hive/router-runtime' + +export const gateway = createGatewayRuntime({ + unifiedGraphHandler +}) +``` + + + + + +## Compared to Default Runtime + +Hive Gateway uses the [Stitching Runtime](https://the-guild.dev/graphql/stitching) 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](#no-default-runtime-plugin-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: + +- [`onDelegationPlan`](/docs/gateway/other-features/custom-plugins#ondelegationplan) +- [`onDelegationStageExecute`](/docs/gateway/other-features/custom-plugins#ondelegationstageexecute) + +## Federation Specification Compliance + +Hive Gateway with Router Runtime maintains 100% compatibility in the +[Federation-Compatibility Audit](https://the-guild.dev/graphql/hive/federation-gateway-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.