Persisted Operations
samples/PersistedOperations is a GraphQL API that accepts only persisted operations: an app sends
an operation id and its variables, and the server runs the document it stores for that id. A console
client plays the app and the operator through three stories:
- A shipped app calls the API by id. The app sends
greet_v1and a name, never a query. An inline query is refused. - Fix it without shipping a new app. The stored
greet_v1asks forstyle: CASUALand answersHey Alice!. The operator re-uploads it withstyle: FORMAL; the same call now answersGood day, Alice.. - A fix that would break shipped apps is refused. An upload that renames the field the app
reads fails the shape-diff guardrail, and
greet_v1keeps answering as before.
What it proves
| Feature | Where |
|---|---|
RequirePersisted(true): every inline document refused with PERSISTED_OPERATION_REQUIRED | Program.cs, EnforcementTests, HotFixFlowTests |
SingleNode(): the declaration persisted operations refuse to start without | Program.cs |
The management mutations under persistedOperations, gated to one role with GateManagement | ProductionPostureTests, MutationFlowTests |
| An upload that keeps the response shape served on the next call by the same id; one that changes it refused | the Client, HotFixFlowTests |
| The demo key, the console and the page only in Development | Program.cs, ProductionPostureTests |
Run
From the Trax.Samples root:
docker compose up -d # Postgres on localhost:5432, database trax_persisted_operations
dotnet run --project samples/PersistedOperations/Trax.Samples.PersistedOperations.Api # Development, http://localhost:5240
# In a second terminal
dotnet run --project samples/PersistedOperations/Trax.Samples.PersistedOperations.ClientThe client prints:
Uploaded greet_v1
1. The app calls greet_v1 for Alice
greet_v1 answers: Hey Alice!
An inline query is refused: {"errors":[{"message":"Only persisted operations are accepted on this server.","extensions":{"code":"PERSISTED_OPERATION_REQUIRED"}}]}
2. The operator re-uploads greet_v1 with style FORMAL
greet_v1 answers: Good day, Alice.
3. Renaming greeting to message is refused: {"code":"SHAPE_DIFF_VIOLATION","message":"Persisted operation 'greet_v1' edit rejected: response shape changed (old fingerprint …, new …). Upload it again with bypassShapeDiff: true if the change is shape-safe."}
greet_v1 answers: Good day, Alice.Each step, as the client sends it:
- The app's call is
{ "id": "greet_v1", "variables": { "name": "Alice" } }with no credential. - The fix re-uploads
greet_v1as the operator (X-Api-Key: operator-key-do-not-use-in-production) withstyle: FORMALin place ofstyle: CASUAL. The response still has onegreetingstring at the same path, so the shape fingerprint does not change and the upload needs no bypass. - The refused edit is the same document with
{ message: greeting }: the app readsgreeting, which would no longer be in the response, so the fingerprint changes and the upload is refused. The stored document stays the FORMAL one.bypassShapeDiff: truewould force it through; the client does not.
The client exits non-zero if any answer differs from the one expected, or if the refused edit is
accepted. Its first step re-uploads the manifest, which puts greet_v1 back to CASUAL under the
same fingerprint, so it can run any number of times.
The API also serves a page at http://localhost:5240 that plays the same three stories: pick one and
press Play. It shows each request with its answer and how long it took, the greeting the app shows,
and what the server stores for greet_v1. Its operator uploads send the demo key, so the page is
served only in Development, like the key.
Try it
G=http://localhost:5240/trax/graphql/
# An inline document is refused
curl -s $G -H 'Content-Type: application/json' \
-d '{"query":"query { discover { greeting { greet(input: { name: \"Eve\", style: FORMAL }) { greeting } } } }"}'
# {"errors":[{"message":"Only persisted operations are accepted on this server.","extensions":{"code":"PERSISTED_OPERATION_REQUIRED"}}]}
# The same operation by id (after the client has uploaded the manifest)
curl -s $G -H 'Content-Type: application/json' \
-d '{"id":"greet_v1","variables":{"name":"Eve"}}'
# {"data":{"discover":{"greeting":{"greet":{"greeting":"Hey Eve!"}}}}}
# An upload without the operator key is refused
curl -s $G -H 'Content-Type: application/json' \
-d '{"query":"mutation Upload($input: UploadPersistedOperationInput!) { persistedOperations { uploadPersistedOperation(input: $input) { success } } }","variables":{"input":{"id":"x_v1","document":"{ __typename }"}}}'
# {"errors":[{"message":"Not authorized.","path":["persistedOperations"],"extensions":{"code":"TRAX_AUTHORIZATION"}}],"data":{"persistedOperations":null}}The operations console is at http://localhost:5240/trax/dashboard (paste the operator key), with the stored operations under API admin > Persisted operations.
How it works
Layout
samples/PersistedOperations/
├── Trax.Samples.PersistedOperations/ GreetTrain: a name and a style in, a greeting out
├── Trax.Samples.PersistedOperations.Api/ the host (Program.cs) and the page in wwwroot/
└── Trax.Samples.PersistedOperations.Client/ console client and manifest.json: the three storiesThe train behind every document takes a name and a GreetingStyle (Casual or Formal, CASUAL and
FORMAL in GraphQL) and returns a GreetOutput with one Greeting string:
public record GreetInput : IManifestProperties
{
public required string Name { get; init; }
public GreetingStyle Style { get; init; }
}public class ComposeGreetingJunction : Junction<GreetInput, GreetOutput>
{
public override Task<GreetOutput> Run(GreetInput input) =>
Task.FromResult(
new GreetOutput
{
Greeting = input.Style switch
{
GreetingStyle.Formal => $"Good day, {input.Name}.",
_ => $"Hey {input.Name}!",
},
}
);
}Client/manifest.json ships one operation. The style is fixed in the stored document, not sent by
the app, so changing it is the operator's job:
From Trax.Samples/samples/PersistedOperations/Trax.Samples.PersistedOperations.Client/manifest.json
{
"operations": [
{
"id": "greet_v1",
"document": "query Greet($name: String!) { discover { greeting { greet(input: { name: $name, style: CASUAL }) { greeting } } } }"
}
]
}The host
Program.cs, less its banner comment:
From Trax.Samples/samples/PersistedOperations/Trax.Samples.PersistedOperations.Api/Program.cs
using Trax.Api.Auth.ApiKey;
using Trax.Api.Dashboard.Extensions;
using Trax.Api.GraphQL.Extensions;
using Trax.Api.GraphQL.PersistedOperations.Extensions;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Samples.PersistedOperations;
using Trax.Samples.PersistedOperations.Api.Auth;
using Trax.Scheduler.Extensions;
var builder = WebApplication.CreateBuilder(args);
var connectionString =
builder.Configuration.GetConnectionString("TraxDatabase")
?? "Host=localhost;Port=5432;Database=trax_persisted_operations;Username=trax;Password=trax123";
var isDevelopment = builder.Environment.IsDevelopment();
// The demo operator key is published in this repository, so it is registered only in
// Development. Anywhere else no credential exists until you register a real scheme, so every
// upload is refused.
if (isDevelopment)
builder.Services.AddTraxApiKeyAuth(keys =>
keys.Add(DemoKeys.OperatorKey, id: "operator", DemoKeys.OperatorRole)
);
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();
// The stored documents live in Postgres. The console's pages need the scheduler services even
// though this sample queues no work.
builder.Services.AddTrax(trax =>
trax.AddEffects(effects => effects.UsePostgres(connectionString))
.AddMediator(typeof(GraphQLNamespaces).Assembly)
.AddScheduler(scheduler => scheduler)
);
builder.Services.AddTraxGraphQL(graphql =>
graphql
// The operations namespace is what the operations console reads and writes, gated to the
// operator. The console registers its own documents when the host starts, so it keeps
// working although this endpoint runs only stored documents.
.ExposeOperationQueries()
.ExposeOperationMutations()
.GateOperations(roles: DemoKeys.OperatorRole)
.UsePersistedOperations(opts =>
opts.RequirePersisted(true)
.LogNonPersistedRequests(true)
// One process serves this endpoint and writes the store, so an upload reaches
// every cached copy without a broadcast. A second node needs
// UseRabbitMqInvalidation(...) instead; the host refuses to start with neither.
.SingleNode()
// The upload mutations live under `persistedOperations`, behind their own gate.
// Gate them to the operator; greet stays reachable to the app.
.GateManagement(roles: DemoKeys.OperatorRole)
)
);
var app = builder.Build();
// The page at / (wwwroot) plays the three stories against this API. Its operator uploads send the
// demo key, so it is served only in Development, with the key.
if (isDevelopment)
{
app.UseDefaultFiles();
app.UseStaticFiles();
}
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseTraxGraphQL();
// The console shows the stored documents under API admin > Persisted operations. It refuses to
// start without a posture. This sample has no sign-in a browser carries, so the page is open
// (AllowAnonymousShell) and served only in Development; everything it reads or changes still needs
// the operator key. Anywhere else, gate it with RequirePolicy(...) or RequireRoles(...) on a cookie
// or OpenID Connect sign-in.
if (isDevelopment)
app.UseTraxApiDashboard(dashboard => dashboard.AllowAnonymousShell());
app.Run();
/// <summary>
/// Visible to <c>WebApplicationFactory<Program></c> for E2E tests.
/// </summary>
public partial class Program;DemoKeys (in Auth/DemoKeys.cs) holds two constants: OperatorKey = "operator-key-do-not-use-in-production" and OperatorRole = "Operator".
The host references Trax.Api, Trax.Api.Auth.ApiKey, Trax.Api.GraphQL,
Trax.Api.GraphQL.PersistedOperations, Trax.Api.Dashboard, Trax.Scheduler and
Trax.Effect.Provider.Json; Trax.Effect.Data.Postgres and Trax.Mediator come in through the
trains library.
What each piece is for:
SingleNode(). Each node caches the documents it serves, and an upload made on one node reaches another only if it is broadcast. WithoutSingleNode()orUseRabbitMqInvalidation(...)the host refuses to start with "Persisted operations need to know how a change reaches every node." This sample is one process that serves the endpoint and writes the store, soSingleNode()is true of it.- No enforcement middleware. Enforcement runs inside HotChocolate's execution pipeline, which
UsePersistedOperationssets up, so it covers HTTP and WebSocket alike.UsePersistedOperationsEnforcement()still compiles and adds nothing; earlier versions of this sample mapped it in aUseWhenbranch, which is no longer needed. GateManagement(roles: "Operator"). The management mutations live underpersistedOperationsat the root, and they are in the schema only once a gate is declared for them. The gate covers those fields only, sogreetstays reachable to the app, which carries no credential. The management mutations always bypass enforcement (they cannot be persisted by id), and the gate is what protects them.- The demo key. It is published in this repository, so
AddTraxApiKeyAuthregisters it only in Development. Anywhere else no credential exists until you register a real scheme, so every upload is refused. ExposeOperationQueries(),ExposeOperationMutations()andGateOperations(roles: "Operator"). The operations console reads and changes everything underoperations, which the gate keeps to the operator. The console registers its own documents when the host starts (undertrax_console_), so it keeps working on an endpoint that refuses document text.- The console.
UseTraxApiDashboardrefuses to start without a posture. The sample has no sign-in a browser carries, so it serves the page only in Development, opened withAllowAnonymousShell(), and the console asks for the operator key on every load. Anywhere else, gate it withRequirePolicy(...)orRequireRoles(...)on a cookie or OpenID Connect sign-in.
A JSON-array batch is refused by the endpoint with HC0009 before enforcement sees it, so an
inline document smuggled into a batch beside a persisted id runs nothing.
Tests
dotnet test tests/Trax.Samples.PersistedOperations.E2E # against PostgresThe suite runs against the persisted_operations_e2e_tests database on port 5432
(TRAX_TEST_PG_PORT moves the port), cleared of persisted operations before each test. It fails,
rather than skips, when the database is missing.
| Class | Proves |
|---|---|
HotFixFlowTests | the three stories: the call by id and the inline refusal, the FORMAL fix with no bypass, the refused rename with the old answer standing, and the manifest restoring CASUAL; with history, deactivate and restore |
EnforcementTests | inline documents refused, ids served, an unknown id reported |
MutationFlowTests | upload, schema-mismatch refusal, shape-diff refusal and bypass, deactivate, all through the GraphQL mutations |
ProductionPostureTests | in Production an inline document is refused and the console and the page are gone; an anonymous upload is refused in every environment; Development serves the console and the page, which shadows neither the console nor the endpoint |
AdditionalCoverageTests | variables, content types, batches, tenant scoping, the shape-diff guardrail |
SDK Reference
UsePersistedOperations | PersistedOperationsBuilder | Management mutations | AddTraxGraphQL | AddTraxApiKeyAuth | UseTraxApiDashboard