AddTraxGraphQL

Registers the Trax GraphQL schema and services using HotChocolate. This adds the query type, mutation type, and all type extensions needed to serve the Trax GraphQL API.

Signatures

AddTraxGraphQL

public static IServiceCollection AddTraxGraphQL(this IServiceCollection services)
public static IServiceCollection AddTraxGraphQL(
    this IServiceCollection services,
    Func<TraxGraphQLBuilder, TraxGraphQLBuilder> configure)

Returns: IServiceCollection for continued chaining.

The parameterless overload calls the builder overload with an identity function. Use the builder overload to configure the schema:

builder.Services.AddTraxGraphQL(graphql => graphql
    .AddDbContext<GameDbContext>()
    .AddFilterType<Player, PlayerFilterInputType>()
    .AddSortType<Player, PlayerSortInputType>()
    .ConfigureFiltering(filter => filter.AddCaseInsensitiveStringOperations())
    .AddTypeModule<RelationshipTypeModule>()
    .AddTypeExtension<PlayerStatsExtension>()
    .AddTypeExtensions(typeof(PlayerStatsExtension).Assembly)
    .ConfigureSchema(schema => schema
        .ModifyCostOptions(o => { o.MaxFieldCost = 50000; })
    )
);

Builder Methods

All builder methods return the builder for fluent chaining.

UseTraxGraphQL

public static WebApplication UseTraxGraphQL(
    this WebApplication app,
    string routePrefix = "/trax/graphql",
    Action<IEndpointConventionBuilder>? configure = null
)

Returns: WebApplication for continued chaining.

The schema download (GET ?sdl, /schema, /schema.graphql) and the GraphQL IDE on this endpoint follow the same per-request decision as introspection (see AllowIntrospection above): served in Development, 404 elsewhere unless your predicate allows the request. An allowed download is sent Cache-Control: private. A host that maps the schema itself with MapGraphQL(path, "trax") skips that per-request check; without a predicate, outside Development, the schema's server options switch both off anyway.

AddTraxGraphQL registers an IStartupFilter that prepends app.UseWebSockets() to the pipeline, so the WebSocket transport required for GraphQL subscriptions is always in place before endpoint execution. You do not need to call app.UseWebSockets() yourself, and the ordering of UseTraxGraphQL() relative to other endpoint middleware (such as UseTraxDashboard()) does not affect the upgrade.

The Trax schema accepts a WebSocket upgrade only from origins the host serves, whether UseTraxGraphQL() maps it or the host maps it with MapGraphQL(path, "trax"): no Origin header, the endpoint's own host, or an origin allowed by AllowSocketOrigins(...) (default: the CORS default policy). Others get 403. See Subscriptions.

What It Registers

AddTraxGraphQL calls AddTraxApi() internally (shared API services), then configures HotChocolate:

• Named GraphQL server via AddGraphQLServer("trax"), using a named schema so it coexists with your own HotChocolate schemas in the same application
• Query type: RootQuery with grouped sub-types:
  • operations (OperationsQueries): opt-in via ExposeOperationQueries(). Predefined operational queries: health status, registered trains discovery, manifests, manifest, manifestGroups, executions, execution, plus the nested operations.deadLetters namespace (deadLetters, deadLetter).
  • discover (DiscoverQueries): present when trains annotated with [TraxQuery] are registered, or when entities annotated with [TraxQueryModel] are discovered via AddDbContext<T>(). Contains auto-generated typed query fields for each query train, and paginated/filterable/sortable fields for each query model.
• Mutation type: RootMutation is registered only when at least one source of mutations exists: a [TraxMutation] train, or ExposeOperationMutations(). Sub-types:
  • operations (OperationsMutations): opt-in via ExposeOperationMutations(). triggerManifest, disableManifest, enableManifest, cancelManifest, triggerGroup, cancelGroup, triggerManifestDelayed, setEffectEnabled, plus the nested operations.deadLetters namespace (requeueDeadLetter, acknowledgeDeadLetter, batch and "all" variants).
  • dispatch (DispatchMutations): only present when trains annotated with [TraxMutation] are registered. Auto-generated typed mutations with strongly-typed input objects derived from each train's input record. Each train gets a single mutation field (e.g. banPlayer) with an optional mode: ExecutionMode parameter when both Run and Queue operations are enabled (the default).

The Trax operational surface is off by default. The scheduler-control mutations (triggerManifest, cancelGroup, dead-letter requeue, etc.) call ITraxScheduler directly, and an unauthenticated caller could disrupt scheduled work. The read queries (health, manifests, executions, trains) reveal deployment topology. Both surfaces have to be opted in explicitly via ExposeOperationQueries() and ExposeOperationMutations(). Exposing either surface without a gate fails at startup, and there are three ways to answer:

Answer	What it does
GateOperations(policy, roles)	Gates the operations namespace alone. The rest of the endpoint stays open, so public trains and query models keep working. A policy or roles is required; GateOperationsToAuthenticatedUsers() is the explicit form for "any signed-in caller".
RequireAuthorization(policy)	Gates the whole endpoint, operations included.
AllowAnonymousOperations()	Acknowledges a deliberately public control plane.

The read queries carry the same requirement as the mutations. operations.hosts returns internal hostnames, environment and per-instance execution counts; operations.config returns the scheduler's configuration. That is an infrastructure disclosure whether or not the mutations beside it are gated.

Exposing the operations surface changes two behaviours automatically:

• Startup guard. The operations resolvers call IOperationsService (and, for the mutations, ITraxScheduler). If you expose them without registering those services, the schema still builds and every operation fails at request time with a masked error. To catch this at boot instead, AddTraxGraphQL() registers a hosted-service guard that throws InvalidOperationException at startup when the surface is exposed but the backing services are missing, including ITrainExecutionService (registered by AddMediator(...)), which the operations enqueue needs, and, when the mutations are exposed, an IJobSubmitter, which runTrain hands its run to. A collocated host gets them from AddScheduler(...); an API-only host that talks to a remote scheduler needs AddTraxJobRunner() plus services.AddScoped<IOperationsService, OperationsService>(), and AddMediator(...) registering its trains, because OperationsService enqueues queueTrain and requeueExecution through ITrainExecutionService. AddTraxJobRunner() registers no job submitter, so an API-only host that exposes the mutations also registers the one its workers read from, services.AddScoped<IJobSubmitter, PostgresJobSubmitter>() when they poll PostgreSQL (the scheduler's local workers, or AddTraxWorker()); without one the host refuses to start. On such a host a scheduler settings change (operations.config.updateScheduler) writes only the fields it names and reaches the running scheduler within seconds, but the first one, which creates the stored settings, must be made on the scheduler host: the API host does not know the scheduler's values for the rest.
• Stream every train. Exposing operations marks the host as an administrative/observability surface, so the lifecycle subscriptions emit events for all trains, not just those decorated with [TraxBroadcast]. Without the operations surface, only [TraxBroadcast] trains emit (the user-facing default).

If you call AddTraxGraphQL with no [TraxQuery] trains, no [TraxQueryModel] entities, and ExposeOperationQueries() not set, the call throws InvalidOperationException because the resulting RootQuery would have no fields and HotChocolate would refuse to build the schema.

• Subscription type: LifecycleSubscriptions, providing real-time lifecycle events via WebSocket (onTrainStarted, onTrainCompleted, onTrainFailed, onTrainCancelled)
• In-memory subscription transport: HotChocolate's built-in pub/sub for delivering events to WebSocket clients
• Error filter: TraxErrorFilter, which curates exception messages for train-related errors. Exposed types: a TrainException message a train author wrote passes through (TRAX_TRAIN_ERROR), and so does the carried message of a TrainException a remote worker or nested train reported; a TrainException carrying any other exception type (the TrainExceptionData JSON a remote worker's failure comes home as), or wrapping a remote endpoint's reply, returns "The train failed." (TRAX_TRAIN_ERROR) and the detail stays in the metadata row; TrainAuthorizationException always returns the generic "Not authorized." (TRAX_AUTHORIZATION); TrainNotFoundException returns "The requested train was not found." (TRAX_TRAIN_NOT_FOUND); AmbiguousTrainNameException surfaces candidate FullNames (TRAX_AMBIGUOUS_TRAIN); TrainInputValidationException returns "The train input failed validation." (TRAX_INVALID_INPUT); the mediator's NoTrainForInputException, thrown when no registered train takes the input, returns "The train could not be run." (TRAX_HOST_CONFIGURATION) even with HotChocolate's exception details switched on, and the full exception, naming the input type and the assemblies the host scanned, is logged on the server at Error, since the fix is in how the host is built. All other exception types (including InvalidOperationException) retain HotChocolate's default masked message.
• Hardening defaults: max execution depth of 15, cost-analyzer budget MaxFieldCost = 1000, introspection allowed in Development only (decided per request, see AllowIntrospection), and a 50-operation per-request cap. Override each via the builder methods above.
• Subscription auth interceptor: Trax registers TraxCompositeSocketInterceptor so WebSocket subscriptions authenticate from the connection_init payload. It serves API-key auth (authToken/apiKey), JWT auth (authToken/bearer, including Authority/JWKS schemes) and the JWT dispatcher, together or alone, and accepts every connection when none is registered. Supply your own via ConfigureSchema(b => b.AddSocketSessionInterceptor<T>()) to replace it. See Subscriptions.
• Lifecycle hook: GraphQLSubscriptionHook, automatically registered to publish train state transitions to the subscription transport

Prerequisites

AddTraxGraphQL depends on services registered by AddMediator() (provides ITrainDiscoveryService and ITrainExecutionService) and a configured data context (provides IDataContextProviderFactory). These are normally set up through AddTrax.

AddTraxGraphQL performs a runtime check that AddTrax() was called first. If the TraxMarker singleton is not found in the DI container, AddTraxGraphQL throws InvalidOperationException:

InvalidOperationException: AddTrax() must be called before AddTraxGraphQL().
Call services.AddTrax(...) in your service configuration before calling AddTraxGraphQL().

This makes sure the required Trax services are available before the GraphQL schema is built.

Example

var builder = WebApplication.CreateBuilder(args);
 
builder.Services
    .AddTrax(trax => trax
        .AddEffects(effects => effects
            .UsePostgres(builder.Configuration.GetConnectionString("TraxDatabase")!)
        )
        .AddMediator(ServiceLifetime.Scoped, typeof(Program).Assembly)
    )
    .AddTraxGraphQL();
 
var app = builder.Build();
 
app.UseTraxGraphQL(); // serves at /trax/graphql
 
app.Run();

To serve the endpoint at a different path:

app.UseTraxGraphQL(routePrefix: "/api/graphql");

Endpoint-level authorization (gates everything on the route, including the BCP tool page):

app.UseTraxGraphQL(configure: endpoint => endpoint
    .RequireAuthorization("AdminPolicy"));

Execution-only authorization (the IDE shell stays loadable where AllowIntrospection allows it, queries and mutations require a key):

builder.Services.AddTraxGraphQL(graphql => graphql.RequireAuthorization());

The two are independent. Use the builder method when you want developers to load the IDE without credentials and only enforce auth on actual GraphQL operations; use the endpoint method when even the IDE shell should be gated.

Registration order

AddTraxGraphQL() needs AddTrax() to have run first, and every [TraxQuery], [TraxMutation] or [TraxBroadcast] train registered before it. A train registered afterwards refuses the host at startup, naming the train:

builder.Services.AddTrax(trax => trax.AddEffects(...).AddMediator(...));
builder.Services.AddTraxJwtAuth(...);        // either side of AddTraxGraphQL
builder.Services.AddTraxGraphQL(graphql => graphql.AddDbContext<AppDbContext>());

Authentication may come before or after it. The subscription interceptor reads the registered schemes once the container is complete, so earlier versions' failure, where an auth call after AddTraxGraphQL() left subscriptions accepting every connection_init while HTTP stayed gated, cannot happen.

The startup checks AddTraxGraphQL() registers (an exposed surface missing its services, a posture contradiction, a train registered after it) run in the hosted-service StartingAsync step, which the host finishes for every service before it starts any. A refused host never binds Kestrel or starts a worker, even with HostOptions.ServicesStartConcurrently.

Everything else is order-independent too. @authorize is attached to the schema, so query and mutation gating works whichever way round the host is composed, and services the GraphQL components depend on are resolved on first use rather than when AddTraxGraphQL() runs.

Package

dotnet add package Trax.Api.GraphQL