Explanation

Content Shield

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

samples/EphemeralWorkers in Trax.Samples is a content moderation API whose trains all run somewhere else: on a runner that is an AWS Lambda function in production and a local Kestrel server in development. The API holds no workers and writes no background_job rows. It POSTs each queued job to the runner and returns, and it POSTs each synchronous run and waits for the answer.

What it proves

FeatureWhere
Queued mutations dispatched over HTTP with UseRemoteWorkers; nothing reaches background_jobRemoteExecutionTests
Every synchronous run (run mutations and [TraxQuery] queries) sent to the runner with UseRemoteRunRemoteExecutionTests.Query_is_run_on_the_runner
A runner that is a TraxLambdaFunction, served locally by RunLocalAsyncRunner/Function.cs, Runner/Program.cs
A signing key shared by both sides; an unsigned request to the runner gets 401RunnerSigningKey.cs, AuthorizationTests
The runner's lifecycle events reaching a GraphQL subscriber on the API over RabbitMQ, on the sample's own contentshield.lifecycle exchangeCrossProcessEventTests
Testing a Lambda runner end to end without AWStests/Trax.Samples.ContentShield.E2E/Fixtures/TestRunner.cs

Run

From the Trax.Samples root:

docker compose up -d       # Postgres on 5432 (database trax_contentshield), RabbitMQ on 5672 (user trax, password trax123)
 
# Terminal 1: the runner on http://localhost:5205
dotnet run --project samples/EphemeralWorkers/Trax.Samples.ContentShield.Runner
 
# Terminal 2: the API on http://localhost:5204
dotnet run --project samples/EphemeralWorkers/Trax.Samples.ContentShield.Api

Both start in Development through Properties/launchSettings.json (ASPNETCORE_ENVIRONMENT for the API, DOTNET_ENVIRONMENT for the runner) and sign with a published demo key. Anywhere else, set Trax__RunnerSigningKey to the same value on both, the base64 of 32 or more random bytes (openssl rand -base64 32); without it the API refuses to start with Set Trax:RunnerSigningKey to the base64 of 32 or more random bytes ....

Try it

# Look up a moderation result (anonymous; the API waits while the runner runs it)
curl -s http://localhost:5204/trax/graphql -H "Content-Type: application/json" \
  -d '{"query":"{ discover { moderation { lookupModerationResult(input: {contentId: \"test-001\"}) { contentId moderationStatus classification threatScore } } } }"}'
 
# Queue a review (anonymous). It returns at once; the runner's console logs the review.
curl -s http://localhost:5204/trax/graphql -H "Content-Type: application/json" \
  -d '{"query":"mutation { dispatch { moderation { reviewContent(input: {contentId: \"test-002\", contentType: \"video\", contentBody: \"suspicious video content\"}) { externalId workQueueId } } } }"}'
 
# Run a report on the runner and wait for the output (Moderator key, Development only)
curl -s http://localhost:5204/trax/graphql -H "Content-Type: application/json" \
  -H "X-Api-Key: contentshield-moderator-key-do-not-use-in-production" \
  -d '{"query":"mutation { dispatch { reports { generateModerationReport(input: {reportPeriod: \"Daily\"}) { externalId output { totalReviewed totalFlagged topViolationTypes falsePositiveRate } } } } }"}'
 
# The runner refuses anything not signed with the key
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:5205/trax/execute \
  -H "Content-Type: application/json" -d '{}'

The report answers with its output, and the last command prints 401. The same report without the key answers Not authorized. with code TRAX_AUTHORIZATION.

How it works

Layout

samples/EphemeralWorkers/
├── Trax.Samples.ContentShield/          trains, roles, RunnerSigningKey, BroadcastSigningKey
├── Trax.Samples.ContentShield.Api/      GraphQL + dispatch + operations console (port 5204)
└── Trax.Samples.ContentShield.Runner/   Function : TraxLambdaFunction; Program.cs runs it locally (port 5205)

The API dispatches everything

From Trax.Samples/samples/EphemeralWorkers/Trax.Samples.ContentShield.Api/Program.cs

// Where the Runner listens. RunLocalAsync serves /trax/execute and /trax/run on it.
var runnerBaseUrl = builder.Configuration["Runner:BaseUrl"] ?? "http://localhost:5205";
var runnerKey = RunnerSigningKey.Resolve(
    builder.Configuration,
    builder.Environment.IsDevelopment()
);
// ...
builder.Services.AddTrax(trax =>
    trax.AddEffects(effects =>
            effects
                .UsePostgres(connectionString)
                .AddDataContextLogging()
                .UseBroadcaster(b =>
                    b.UseRabbitMq(
                        rabbitMqConnectionString,
                        o =>
                        {
                            o.ExchangeName = LifecycleEvents.ExchangeName;
                            // Signs each event, and drops one not signed with this key.
                            o.SigningKey = BroadcastSigningKey.Resolve(
                                builder.Configuration,
                                builder.Environment.IsDevelopment()
                            );
                        }
                    )
                )
        )
        .AddMediator(mediator =>
            mediator
                .ScanAssemblies(typeof(ReviewContentTrain).Assembly)
                .GlobalConcurrentRunLimit(25)
        )
        .AddScheduler(scheduler =>
            scheduler
                // ...
                .UseRemoteWorkers(
                    remote =>
                    {
                        remote.BaseUrl = $"{runnerBaseUrl}/trax/execute";
                        remote.SigningKey = runnerKey;
                    },
                    routing =>
                        routing
                            .ForTrain<IReviewContentTrain>()
                            .ForTrain<ISendViolationNoticeTrain>()
                            .ForTrain<IGenerateModerationReportTrain>()
                )
                // ── Remote run offloading ────────────────────────────────────────
                // UseRemoteRun replaces the in-process run executor. Every
                // synchronous run (a mutation in RUN mode, and every [TraxQuery]) is
                // POSTed to the Runner and waits until the train completes. Without
                // this, runs execute in-process on this API.
                .UseRemoteRun(remote =>
                {
                    remote.BaseUrl = $"{runnerBaseUrl}/trax/run";
                    remote.SigningKey = runnerKey;
                })
        )
);

UseRemoteWorkers routes the named trains' queued runs to the runner. A train it does not route still falls back to the local worker, which is why the API process still registers LocalWorkerService; every queueable ContentShield train is routed, so that worker never has a job.

UseRemoteRun replaces the in-process run executor for every synchronous run, which includes [TraxQuery] queries as well as mutations in RUN mode. So even lookupModerationResult travels to the runner. Leave UseRemoteRun out if queries should run on the API.

The runner is a Lambda function

From Trax.Samples/samples/EphemeralWorkers/Trax.Samples.ContentShield.Runner/Function.cs

using Amazon.Lambda.Core;
using Amazon.Lambda.Serialization.SystemTextJson;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Trax.Effect.Broadcaster.RabbitMQ.Extensions;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Runner.Lambda;
using Trax.Samples.ContentShield;
using Trax.Samples.ContentShield.Trains.ContentReview.ReviewContent;
using Trax.Scheduler.Configuration;
 
[assembly: LambdaSerializer(typeof(DefaultLambdaJsonSerializer))]
 
namespace Trax.Samples.ContentShield.Runner;
 
public class Function : TraxLambdaFunction
{
    protected override void ConfigureServices(
        IServiceCollection services,
        IConfiguration configuration
    )
    {
        var connectionString =
            configuration.GetConnectionString("TraxDatabase")
            ?? throw new InvalidOperationException("Connection string 'TraxDatabase' not found.");
 
        var rabbitMqConnectionString =
            configuration.GetConnectionString("RabbitMQ")
            ?? throw new InvalidOperationException("Connection string 'RabbitMQ' not found.");
 
        services.AddTrax(trax =>
            trax.AddEffects(effects =>
                    effects
                        .UsePostgres(connectionString)
                        .UseBroadcaster(b =>
                            b.UseRabbitMq(
                                rabbitMqConnectionString,
                                o =>
                                {
                                    o.ExchangeName = LifecycleEvents.ExchangeName;
                                    // Signs each event, and drops one not signed with this key.
                                    o.SigningKey = BroadcastSigningKey.Resolve(
                                        configuration,
                                        IsDevelopment(configuration)
                                    );
                                }
                            )
                        )
                )
                .AddMediator(typeof(ReviewContentTrain).Assembly)
        );
    }
 
    // A runner runs what it is sent as already authorized, so it refuses every request until it
    // knows who may send it work. Here: only a caller holding the key the API signs with.
    protected override void ConfigureRunner(
        TraxJobRunnerOptions runner,
        IConfiguration configuration
    ) => runner.SigningKey = RunnerSigningKey.Resolve(configuration, IsDevelopment(configuration));
 
    private static bool IsDevelopment(IConfiguration configuration) =>
        string.Equals(
            configuration["DOTNET_ENVIRONMENT"] ?? configuration["ASPNETCORE_ENVIRONMENT"],
            "Development",
            StringComparison.OrdinalIgnoreCase
        );
}

A runner runs what it is sent as already authorized, so it refuses every request until it knows who may send work. The signing key is that answer: the API signs each request body with it, and the runner checks the Trax-Signature header before reading the body. See Remote Execution: Authorization Posture.

The function reads its configuration from appsettings.json next to the binary and from environment variables (ConnectionStrings__TraxDatabase, Trax__RunnerSigningKey, Trax__BroadcastSigningKey, DOTNET_ENVIRONMENT). It does not see command-line arguments, and it has no IHostEnvironment, which is why its own IsDevelopment helper reads DOTNET_ENVIRONMENT (or ASPNETCORE_ENVIRONMENT) from configuration.

Locally, Program.cs serves the function over HTTP:

From Trax.Samples/samples/EphemeralWorkers/Trax.Samples.ContentShield.Runner/Program.cs

using Trax.Samples.ContentShield.Runner;
 
await new Function().RunLocalAsync([$"--contentRoot={AppContext.BaseDirectory}", .. args]);

The Kestrel server RunLocalAsync starts reads appsettings.json from its content root, and the function reads the copy next to the binary. RunLocalAsync uses the binary's directory as the content root unless an argument names another, so both read the same file and the runner listens on the 5205 that appsettings.json names wherever dotnet run starts. The sample passes --contentRoot explicitly anyway: older Trax.Runner.Lambda releases defaulted to the current directory, and a runner started from the repository root found no endpoint and listened on 5000.

For production, swap UseRemoteWorkers and UseRemoteRun for UseLambdaWorkers and UseLambdaRun (package Trax.Scheduler.Lambda), which invoke the function through the AWS SDK with no public endpoint, with the same SigningKey. See Lambda Workers.

Who may do what

Anyone may submit content (reviewContent) and look up a result. sendViolationNotice and generateModerationReport carry [TraxAuthorize(Roles = "Moderator")]; the only key with that role is a demo key registered in Development. The runner needs no authorization service for them: it treats the train a remote run names as already authorized, because the API checked the caller; any other train that run starts is checked as usual. The operations namespace is exposed for the operations console and gated to a separate Operator role, held by a second demo key (contentshield-operator-key-do-not-use-in-production). It is not the Moderator role, because a subscriber the operations gate admits receives every train's events, the anonymous review's included. The console's page is served only in Development, with AllowAnonymousShell(), and asks for the operator key on every load.

Only the Moderator trains, sendViolationNotice and generateModerationReport, are [TraxBroadcast]. A broadcast train's events reach every subscriber the train admits, so the anonymous review and lookup are not broadcast, and a subscriber on the API sees only the Moderator trains. Their events carry no output unless the host opts the train in: the API calls AllowOutputForBroadcastSubscribers<ISendViolationNoticeTrain>(), since a notice's id is meant for every moderator, and leaves the report out.

From Trax.Samples/samples/EphemeralWorkers/Trax.Samples.ContentShield.Api/Program.cs

builder.Services.AddTraxGraphQL(graphql =>
    graphql
        .ExposeOperationQueries()
        .ExposeOperationMutations()
        .GateOperations(roles: ContentShieldRoles.Operator)
        .AllowOutputForBroadcastSubscribers<ISendViolationNoticeTrain>()
);

The API and the runner both publish on contentshield.lifecycle (LifecycleEvents.ExchangeName), an exchange of their own, so another Trax application on the same broker does not receive their events. Each signs what it publishes with the key BroadcastSigningKey resolves (Trax:BroadcastSigningKey, or a published demo key in Development) and drops an event that is not signed with it; outside Development a host without the key does not start. See UseRabbitMq: Signing and transport.

Subscriptions need a credential even for anonymous trains. Once an API-key scheme is registered, every WebSocket must carry a key in its connection_init payload, and a socket without one is refused; see Subscriptions: Authentication.

Tests

TRAX_TEST_PG_PORT=5432 dotnet test tests/Trax.Samples.ContentShield.E2E

No AWS is involved. The suite starts the real Function through RunLocalAsync on a free port, from a subclass that overrides BuildServiceProvider only to supply the test database and broker and to count the requests the runner handles, and points the API's Runner:BaseUrl at it. Both use the contentshield_e2e_tests database.

Test classProves
RemoteExecutionTestsA query and a run mutation reach /trax/run, a queued review reaches /trax/execute, and no background_job row is written
AuthorizationTestsReports and notices refuse an anonymous caller; the runner refuses unsigned requests on both routes
CrossProcessEventTestsA violation notice the runner sends reaches an onTrainCompleted subscriber on the API; an anonymous review's result is not broadcast
DocumentedExamplesTestsEvery curl command in the API's header works as written

SDK Reference

UseRemoteWorkers | UseRemoteRun | TraxLambdaFunction | UseLambdaWorkers | UseBroadcaster | AddTraxApiKeyAuth