HyperRoute

Federation

HyperRoute implements GraphQL federation — the pattern of composing multiple independent GraphQL services (subgraphs) into a single unified API. Composition happens at build time, not runtime, which is the key to HyperRoute's performance.

Federation Directives

HyperRoute supports the standard federation directives:

DirectivePurposeExample
@keyDefine entity lookup fields@key(fields: "id")
@externalMark field as owned by another subgraph@external on User.name
@requiresDeclare fields needed from other subgraphs@requires(fields: "price currency")
@providesDeclare fields this subgraph can provide@provides(fields: "name")
@shareableAllow multiple subgraphs to resolve a field@shareable on shared types
@overrideTake ownership of a field from another subgraph@override(from: "legacy")

Example: Users Subgraph

type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

Example: Orders Subgraph

type User @key(fields: "id") {
  id: ID! @external
  orders: [Order!]!
}

type Order @key(fields: "id") {
  id: ID!
  total: Float!
  status: OrderStatus!
  user: User!
}

When a client queries user { name orders { total } }, HyperRoute's query planner automatically:

  1. Fetches User.name from the Users subgraph
  2. Fetches User.orders from the Orders subgraph
  3. Merges results into a single response

Entity Batching

When resolving entities across subgraphs, HyperRoute batches _entities calls to reduce network round-trips:

federation:
  entity_batching:
    enabled: true
    max_batch_size: 100
    batch_window_ms: 5
OptionDefaultDescription
max_batch_size100Maximum entities per batch call
batch_window_ms5Wait window to collect entities before sending

Before batching: 50 product lookups → 50 individual _entities calls After batching: 50 product lookups → 1 batched _entities call

Supergraph Bundles

Supergraph bundles are the composition artifact that HyperRoute uses to understand your federated schema. A bundle contains:

  • The composed supergraph SDL
  • Individual subgraph schemas
  • Routing metadata

Creating Bundles

Use the DevKit CLI to compose subgraphs:

hyperroute compose \
  --subgraph users=http://users:4001/graphql \
  --subgraph orders=http://orders:4002/graphql \
  --output supergraph.graphql

Hot Reloading

HyperRoute watches for schema changes and applies them without downtime:

# Trigger a manual reload
curl -X POST http://localhost:4000/__hyperroute/reload

# Check reload status
curl http://localhost:4000/__hyperroute/reload/status

# Rollback to previous bundle
curl -X POST http://localhost:4000/__hyperroute/rollback

# List available versions
curl http://localhost:4000/__hyperroute/versions

Snapshot-Driven Federation

For larger deployments, HyperRoute supports a snapshot-driven workflow with a control-plane API. Push new supergraph snapshots without restarting the router:

Control Plane API

# Push a new supergraph snapshot
curl -X POST http://localhost:4000/control-plane/snapshots \
  -H "Content-Type: application/json" \
  -d '{"sdl": "...", "metadata": {"version": "v2.1"}}'

# List all snapshots
curl http://localhost:4000/control-plane/snapshots

# Activate a specific snapshot
curl -X POST http://localhost:4000/control-plane/activate \
  -d '{"snapshot_id": "abc-123"}'

# Rollback to previous snapshot
curl -X POST http://localhost:4000/control-plane/rollback

Push-Based Deployment (Control Plane v1)

For CI/CD pipelines, use the bundle upload API:

# Upload a new bundle
curl -X POST http://localhost:4000/control/v1/bundles \
  -F "bundle=@supergraph.graphql"

# List all bundles
curl http://localhost:4000/control/v1/bundles

# Activate a specific bundle
curl -X POST http://localhost:4000/control/v1/activate/bundle-id-here

N+1 Query Prevention

HyperRoute automatically detects and batches N+1 patterns at the federation query planning layer:

n_plus_one_prevention:
  enabled: true
  max_batch_size: 100
  batch_window_ms: 5
  deduplication_enabled: true

When a query like products { reviews { rating } } is executed:

  • Before: 50 products → 50 individual review queries to the Reviews subgraph
  • After: 50 products → 1 batched review query

Combined with in-flight deduplication, duplicate entity lookups are collapsed into a single upstream call.

Multi-Tenant Federation

HyperRoute supports multi-tenant federation natively — no enterprise license required:

multi_tenant:
  enabled: true
  header: "X-Tenant-Id"
  isolation: strict

Each tenant's requests are isolated, with separate rate limits, subscription caps, and observability tags. See the Configuration reference for the full multi-tenant options.

Next Steps