Go-live checklist

GraphPilot handles the parts of running a service you would expect. This is the short list of points that are easy to overlook and expensive to discover in production.

Secure the connection to your origin

Your origin is still reachable from the internet once GraphPilot is in front of it, and its address is not a secret.

Verify the signature

GraphPilot signs every request, so verifying the signature on your origin is what proves a request came through GraphPilot. Your origin needs the signing key. It is shown once, when the service is created: in the portal, in the dialog that follows creating the service there, and from the CLI, in the Signing key row gpilot service create prints. Neither shows it again. If you did not keep it, rotate it in the portal to get a new one. Reject anything that fails verification, and always compute the signature over the raw request body, before any framework parses or re-serializes it. Check your implementation against the published test vector.

GraphPilot speaks TLS to your origin when the origin URL is https://, and does not when it is http://. There is no separate switch. Without a port in the URL, GraphPilot connects to port 443 for https:// and port 80 for http://. See trust and transport.

Allowlist the edge at your firewall

Verifying the signature happens after the request has arrived. Refusing everything else at the network edge is the cheaper first line, and the current ranges are in the portal and on the GraphPilot API. The set changes, so read it again rather than trusting a copy: see the origin allowlist.

Keep your clock in sync

Run NTP on your origin. The signature is time-bound, so clock drift makes valid requests fail and widens the replay window. See replay protection.

Pin every JWT provider to your issuer and audience

A signature only proves which key signed a token. Set allowed_issuers and allowed_audiences on every JWT provider, to the iss and aud your identity provider puts in its tokens; otherwise a token another tenant of a shared identity platform minted verifies as one of your callers. A provider with jwks_url, public_key or an asymmetric algorithm does not deploy without allowed_issuers; a missing allowed_audiences draws an auth_provider warning on every deployment. A token without exp is refused unless the provider sets allow_missing_exp. See configuring a provider.

Serve GraphQL only on the configured path

GraphPilot reads a request as GraphQL on the paths in request.graphql_paths, on paths below them and in any letter case. Every other path is plain HTTP and skips the GraphQL checks. An operation sent there is refused with 404, but an upload or a subscription is not recognized there, so an origin that also answers GraphQL elsewhere can still be reached past the checks that way. Keep REST routes out from under the GraphQL path too: a body there that is not an operation is refused with 415.

Decide what happens to an unverifiable credential

By default a token that does not verify is refused at the edge and never reaches you. If you would rather it arrive as anonymous during a key rotation, that is a per-reason setting. See rejection.

Make sure it actually caches

Confirm a second identical request is a HIT

Not a smoke test, the whole point. Read gp-cache on both responses. A PASS means nothing was stored, and its gp-cache-reason names the rule that refused. See troubleshooting.

Stop setting cookies on read requests

A response carrying Set-Cookie is never stored. Frameworks that touch the session on every request do this by default, and it switches caching off for everything it touches. This is the single most common reason a first deployment shows no hits. See what refuses storing.

Say how long each response stays fresh

Nothing is cached unless your origin’s Cache-Control or, for a GraphQL API, your schema’s @cacheControl says so. A service that says neither caches nothing. See when a response is cached.

Deploy the schema before the origin

A query that selects a field your deployed schema does not declare is never cached (CACHE_SKIPPED_UNRESOLVED_SELECTION). Put the GraphPilot deploy ahead of your origin’s in the release, so new fields are known before clients ask for them. See deploy the schema before the origin.

Decide whether you need shielding

Each edge location keeps its own cache, so a HIT in one region says nothing about the next: the first request for an entry at every location still reaches your origin. If your callers are spread across many regions, or your origin is expensive to call, switch on shielding and name a shield location close to your origin. Every other location then asks the shield instead of your origin, and your origin sees about one miss per entry for the whole network. Shielding is available on paid plans. See the cache is per location.

Get personalization right before you go live

Decide who shares each answer

Ask of every cached answer: who else gets exactly the same one? Data that is the same for a whole organization, or for one organization and role, belongs in a named scope such as ORGANIZATION, backed by a [[cache.policy.vary]] entry. It stores one entry per group and keeps your hit rate, where a per-person entry misses for every member. For a plain HTTP origin, a vary rule on the organization claim partitions the whole service the same way. Data that is the same for everyone stays PUBLIC, which is also the default: @cacheControl(scope:) is PUBLIC unless you write a scope, even for a request with a credential, so give every type or field whose answer depends on the caller a scope (a field hint without one keeps its type’s scope). Only what really differs per person gets scope: PRIVATE (or Cache-Control: private from your origin), the last rung, which relies on the expression in the next card. See who shares an entry.

Read your private expression as if it were an access rule

cache.policy.private decides who shares a cache entry. auth:idp.sub and cookie:session_id identify one caller; an organization id, a customer id, a role or a plan name identify a group, and everyone in that group then shares one entry. A group belongs in a named scope or a vary rule instead. See private.

Decide how fast a revoked permission must take effect

A cache hit does not consult your origin, so a withdrawn permission is not reflected until the entry expires or is purged. If that window matters, shorten the lifetime for those responses or purge on revocation. See revocation.

Know what your writes invalidate

Return the affected objects from your mutations

Automatic invalidation follows what a mutation’s response actually contained. A mutation declared as returning Boolean! invalidates nothing at all. See automatic invalidation.

Plan for creates separately

A newly created object does not appear in a cached list that was not empty, because nothing cached contained it. Either return the parent whose key covers the list, or name a key on the mutation’s surrogate-key response header. See the three ways around it.

Name keys on your plain HTTP writes

A plain HTTP write purges only the keys its response names in Surrogate-Key, so tag your GET responses with keys and send the same keys on the POST, PUT, PATCH or DELETE that changes them. See the Surrogate-Key header.

Have a way to purge what changes outside GraphPilot

A nightly import, an admin tool or a direct database write never passes through the edge. Wire gpilot purge or the purge API into those paths before you need them at 3am. The API key they use needs the cache:purge permission.

Before you scale up

Check the origin timeout against your cold starts

On Glider (Free) the edge waits 5 seconds for the first byte, not 15. A container that scales to zero can take longer and the request fails with a 502 while it is still booting. See origin timeouts.

Size your origin for a cache-less window

A deployment does not clear the cache, but a purge-all does, and on Glider (Free) exceeding the quota withdraws caching entirely. In both cases every request reaches your origin. Glider is offered under fair use: traffic far beyond what it is meant for can have a Glider account’s services suspended until the start of the next month, or until it moves to a paid plan. See quotas.

Know how to go back to a previous version

In the portal, open Deployments, pick the deployment that was good and choose Redeploy: it rebuilds from that deployment’s stored schema and config. The CLI has no rollback command, so keep schema.graphql and gpilot.toml in version control anyway and deploy the previous versions from there when you work from the CLI. A gpilot.toml that holds a JWT provider’s shared secret is the exception: it is stored as written, so keep that file out of the repository or use a provider with a public key. See deployments.

Consider persisted queries before opening a public GraphQL API

They bound what can be executed, keep requests small enough for GET, and make your operation inventory answerable. See persisted queries.