How do I register operations?

Run `wgc operations push` in your CI/CD pipeline, pointing at the file containing your operation manifests. The CLI sends them to the Cosmo control plane, which stores and replicates them to the CDN.

Can I use persisted operations without blocking unregistered ones?

Yes. Set `log_unknown: true` to log unregistered operations without rejecting them. This lets you observe traffic before enforcing. Safelist mode allows operations whose body matches a registered one, without requiring the hash.

How is the operation hash computed?

Each operation is identified by its SHA-256 hash. `wgc operations push` detects the manifest format and registers the hash; clients then send that hash. Apollo persisted-query manifests and Relay query maps are both supported.

Can different clients use different operation sets?

Yes. Include the `graphql-client-name` header in client requests to namespace operations per application. Each client can register and be restricted to its own set.

What happens when a client sends an unregistered hash in blocking mode?

The router rejects the request and returns an error. The client must register the operation before it can execute it. This prevents arbitrary query execution in production.

Can I migrate incrementally without breaking existing clients?

Yes. Start with log-only mode to identify unregistered operations. Enable safelist mode next, which allows operations matching registered bodies. Enable full blocking only after all clients send registered hashes.

Persisted Operations for Federated GraphQL | Cosmo by WunderGraph

The problem

Production GraphQL without an operation registry

Any valid operation can run. Clients send full query bodies every time. There is no record of what was executed or by whom.

Full query bodies waste bandwidth

Every request carries the complete operation text. A complex query can run several kilobytes per call, multiplied across every client and every request.

Any valid GraphQL operation can execute

Without a registration mechanism, clients can run arbitrary operations against your graph—including expensive or malicious ones you never intended to expose.

No audit trail for client operations

You cannot track which operations each client application sends, what changed between releases, or who registered what. Compliance and debugging both suffer.

Our solution

Register once, hash forever

Operations are registered in CI/CD and stored on the Cosmo CDN. Routers fetch them from the CDN at runtime. Clients send only the hash—never the full body again after the first registration.

How it works end to end

Operations are pushed to the control plane with `wgc operations push` during CI/CD. Each operation is identified by its SHA-256 hash.
The control plane stores operations and replicates them to the Cosmo CDN.
Routers fetch registered operations from the CDN at runtime—per request by default, or all at once into memory at startup when the PQL manifest is enabled. No database connection required.
Clients send a hash identifier instead of the full operation body. The router validates the hash and executes the stored operation.
Enforcement is configurable: log unknown operations, allow operations matching a registered body (safelist), or block all unregistered hashes.
Client-specific namespacing is available via the `graphql-client-name` header, enabling per-app operation sets.

One CLI command in CI. CDN-backed at runtime.

Persisted Operations

Before & After

Before Cosmo	With Cosmo
Full query body sent with every request	SHA-256 hash transmitted after initial registration
Any arbitrary operation can execute in production	Only registered operations allowed when blocking is enabled
No record of which operations clients use	Audit trail of registered operations per client application
No way to block unauthorized queries at the edge	Router rejects unregistered hashes with a clear error

Enforcement

Three modes for incremental rollout

Log-only

Log unknown operations without blocking. Observe traffic before enforcing.

Safelist

Allow operations whose body matches a registered one, even without the hash.

Full blocking

Reject all requests that do not carry a registered hash. Set `security.block_non_persisted_operations.enabled: true`.

How Persisted Operations work in Cosmo

01

CI/CD integration.

Register

Run `wgc operations push` in your CI/CD pipeline. The CLI sends operations to the control plane, which assigns each one a SHA-256 hash and stores it.

02

CDN-backed. Fast at runtime.

Replicate

The control plane replicates operations to the Cosmo CDN. Routers fetch operations from the CDN—per request by default, or all at once at startup with the PQL manifest enabled. No runtime database calls.

03

Hash check on every request.

Validate

The router checks each incoming hash against registered operations. If the hash is found, the stored operation executes. If not, the response depends on the enforcement mode.

04

Incremental rollout supported.

Enforce

Three modes: log-only (track unknown operations without blocking), safelist (allow operations whose body matches a registered one), or full blocking (reject all unregistered hashes).

Capabilities

Registration, enforcement, and audit

One registry for all clients. Three enforcement modes. Full audit trail.

CDN-backed operation storage

Registered operations are stored on the Cosmo CDN. Runtime validation requires no database call. Enable the PQL manifest to load all operations into memory at startup and drop per-request CDN fetches.

Client namespacing

Associate operations with specific client applications using the `graphql-client-name` request header. Each client can have its own operation set.

Three enforcement modes

Start with log-only to observe traffic, move to safelist to allow matching bodies, then enable full blocking once all clients are migrated.

CI/CD integration

Push operations during your release pipeline with `wgc operations push`. JSON output is available for custom tooling. Works with GitHub Actions, GitLab CI, and any other pipeline.

Lock down your production graph

Push operations from CI/CD. Clients send hashes. Block everything else with one config flag.

Start Free Read the Docs

Send a hash. Block everything else.