Request Deduplication

The Cosmo Router includes two layers of request deduplication to avoid redundant work when multiple concurrent requests resolve to identical subgraph fetches.

Layer 1: Subgraph Request Deduplication

Deduplicates identical fetches to the same subgraph across concurrent operations. The deduplication key is:

xxhash64(DataSourceID + ":" + requestBody + preComputedHeaderHash)

DataSourceID: identifies the target subgraph
requestBody: the complete JSON payload (query + variables)
preComputedHeaderHash: xxhash64 of all headers that will be forwarded to this subgraph, as determined by your header forwarding rules

Only Query operations are eligible. Mutations and subscriptions are never deduplicated.

Layer 2: Inbound Request Deduplication

Deduplicates identical client requests before the engine even starts resolving. The key is:

xxhash64(normalizedOperationHash + variablesHash + combinedSubgraphHeadersHash)

If two concurrent clients send the same query with the same variables and the same forwarded headers, only one resolution is performed and the result is shared.

How Header Hashes Are Computed

The header hashes for both layers are computed by SubgraphHeadersBuilder, which:

Iterates over every subgraph involved in the execution plan
Applies all configured header forwarding rules (global + per-subgraph) against the current inbound request headers
Produces a deterministic uint64 hash per subgraph
Combines all per-subgraph hashes into a single allHash

This happens after RouterOnRequestHandler and RouterMiddlewareHandler hooks run, but before EnginePreOriginHandler.OnOriginRequest hooks run.

Request Pipeline and Hook Ordering

Incoming HTTP Request
    │
    ├── [1] RouterOnRequestHandler hooks          ← can set headers here
    │       (before auth, before request parsing)
    │
    ├── [2] graphqlPreHandler                     ← parses, authenticates, validates, plans
    │
    ├── [3] RouterMiddlewareHandler hooks          ← can set headers here
    │       (after parse/auth, ctx.Operation() available)
    │
    ├── [4] graphqlHandler.ServeHTTP
    │   ├── SubgraphHeadersBuilder()              ← HEADER HASHES COMPUTED HERE
    │   │   (reads current request headers, applies forwarding rules, hashes result)
    │   │
    │   └── Engine Resolver
    │       ├── Inbound Request Deduplication      (uses allHash from step [4])
    │       └── Per-subgraph fetches:
    │           ├── Subgraph Request Deduplication  (uses per-subgraph hash from step [4])
    │           ├── ────────────────────────────
    │           ├── EnginePreOriginHandler hooks    ← TOO LATE for dedup key
    │           ├── ────────────────────────────
    │           ├── HTTP transport (circuit breaker, retry, actual fetch)
    │           └── EnginePostOriginHandler hooks
    │
    └── Response to client

Configuration Reference

engine:
  # Enable subgraph request deduplication (default: true)
  # Deduplicates identical fetches to the same subgraph across concurrent operations
  enable_single_flight: true

  # Force-enable subgraph dedup even when EnginePreOriginHandler is registered (default: false)
  # Only use this if your OnOriginRequest hook does NOT set identity-affecting headers
  force_enable_single_flight: false

  # Enable inbound request deduplication (default: true)
  # Deduplicates identical client requests before the engine starts resolving
  enable_inbound_request_deduplication: true

  # Force-enable inbound dedup even when EnginePreOriginHandler is registered (default: false)
  force_enable_inbound_request_deduplication: false

Environment variable equivalents:

ENGINE_ENABLE_SINGLE_FLIGHT
ENGINE_FORCE_ENABLE_SINGLE_FLIGHT
ENGINE_ENABLE_INBOUND_REQUEST_DEDUPLICATION
ENGINE_FORCE_ENABLE_INBOUND_REQUEST_DEDUPLICATION

Getting Started

Concepts

Cosmo Connect

Cosmo ConnectRPC

Router

Studio

Control Plane

GraphQL / Federation

Deployments and Hosting

Request Deduplication

Layer 1: Subgraph Request Deduplication

Layer 2: Inbound Request Deduplication

How Header Hashes Are Computed

Request Pipeline and Hook Ordering

Configuration Reference

​Layer 1: Subgraph Request Deduplication

​Layer 2: Inbound Request Deduplication

​How Header Hashes Are Computed

​Request Pipeline and Hook Ordering

​Configuration Reference

Layer 1: Subgraph Request Deduplication

Layer 2: Inbound Request Deduplication

How Header Hashes Are Computed

Request Pipeline and Hook Ordering

Configuration Reference