Reference

TraxLambdaFunction

Package Trax.Runner.LambdaNamespace Trax.Runner.LambdaSource TraxLambdaFunction.cs

The abstract base class for an AWS Lambda function that runs Trax trains sent by UseLambdaWorkers and UseLambdaRun. It builds and keeps the service provider, dispatches each LambdaEnvelope, derives cancellation from the time the function has left, and serves the same routes over HTTP for local runs.

Signature

public abstract class TraxLambdaFunction
{
    protected abstract void ConfigureServices(IServiceCollection services, IConfiguration configuration);
    protected virtual void ConfigureRunner(TraxJobRunnerOptions runner, IConfiguration configuration);
    protected virtual void ConfigureLogging(ILoggingBuilder logging);
    protected virtual IServiceProvider BuildServiceProvider();
    protected virtual TimeSpan TerminalWriteMargin { get; }
    protected virtual bool AllowUnsignedLocalDevelopmentRequests { get; }
 
    public Task<object?> FunctionHandler(LambdaEnvelope envelope, ILambdaContext context);
 
    public Task RunLocalAsync(string[] args);
    public Task RunLocalAsync(string[] args, CancellationToken cancellationToken);
}

Members

MemberDescription
ConfigureServices(IServiceCollection, IConfiguration)Abstract. Registers the function's Trax effects, mediator, data contexts and application services. The base class calls AddTraxJobRunner() itself, so this does not
ConfigureRunner(TraxJobRunnerOptions, IConfiguration)Sets the runner's posture: runner.SigningKey (shared with UseLambdaWorkers / UseLambdaRun), or runner.AllowUnsignedRequests(). The default sets nothing, so every invocation is refused
ConfigureLogging(ILoggingBuilder)Configures logging. Default: console at Information
TerminalWriteMarginHow much of ILambdaContext.RemainingTime is held back so a run cancelled by the function's timeout can still record its outcome. Default 5 seconds; at most half the time left is held back
AllowUnsignedLocalDevelopmentRequestsLets the local routes accept unsigned loopback requests outside the Development environment, on a runner with AllowUnsignedRequests(). Default false. It does not lift the loopback check and has no effect on FunctionHandler. New in the next Trax.Runner.Lambda release
BuildServiceProvider()Builds the whole service graph. The default builds IConfiguration, registers it and logging, calls ConfigureLogging and ConfigureServices, and finishes with AddTraxJobRunner(runner => ConfigureRunner(runner, configuration)). An override registers AddTraxJobRunner itself
FunctionHandler(LambdaEnvelope, ILambdaContext)The Lambda entry point. Dispatches the envelope by its Type and returns the handler's response
RunLocalAsync(string[])Serves the function as a local Kestrel server until it stops on Ctrl+C or process exit
RunLocalAsync(string[], CancellationToken)The same, also stopping when the token is cancelled; the task completes once the server has shut down. New in the next Trax.Runner.Lambda release

Behavior

Service provider

The provider is built on the first FunctionHandler call, not when Lambda creates the instance, and reused for every later call on that instance. Each call creates its own DI scope and resolves ITraxRequestHandler from it.

Configuration

IConfiguration is built from appsettings.json (optional, read from AppContext.BaseDirectory) and environment variables, passed to ConfigureServices and ConfigureRunner, and registered as IConfiguration. Command-line arguments are not part of it, even under RunLocalAsync, where they reach only the Kestrel server. There is no IHostEnvironment; a function reads DOTNET_ENVIRONMENT (or ASPNETCORE_ENVIRONMENT) from the configuration.

Envelope dispatching

TypeHandlerReturns
ExecuteITraxRequestHandler.ExecuteJobAsyncRemoteJobResponse
RunITraxRequestHandler.RunTrainAsyncRemoteRunResponse
anything elsenonethrows InvalidOperationException

LambdaEnvelope and LambdaRequestType are defined in Trax.Scheduler: public record LambdaEnvelope(LambdaRequestType Type, string PayloadJson) with an init-only string? Signature, and public enum LambdaRequestType { Execute, Run }.

Before dispatching, the function checks its posture and, with a SigningKey, the envelope's Signature over the UTF-8 bytes of PayloadJson. A Run must also be fresh and not repeated; its nonce goes to the runner's nonce store, the Trax database by default, so concurrent instances refuse a repeat too. A function with a SigningKey and no UsePostgres or UseSqlite calls runner.UseInMemoryNonceStore() in ConfigureRunner, or registers an INonceStore, or it refuses to start. An Execute is checked for its signature only, because Lambda retries an asynchronous invocation with the same payload; the job's Pending metadata row stops a second run. A refused envelope throws, so the invocation fails and Lambda's retry and dead-letter settings apply.

Timeouts

Cancellation is derived from RemainingTime less the margin actually used, the smaller of TerminalWriteMargin and RemainingTime / 2. A function whose timeout is at or below the margin (AWS's default is three seconds) still runs its jobs, and the first time an instance has no more time left than the margin it logs a warning. An Execute whose time runs out before its job starts does not start it: the run is recorded Cancelled (only while it is still Pending, written on CancellationToken.None) rather than left for the stale-pending reaper to fail.

Errors

For Execute, exceptions are logged and returned as a RemoteJobResponse with IsError, ErrorMessage and ExceptionType. ErrorMessage is a TrainException's message or fixed text, and no stack trace is returned. Errors inside the train are also persisted to the Metadata table by ServiceTrain.Run; errors before the train starts (such as a payload that does not deserialize) appear only in the log. The payload is read case-insensitively, and one that repeats a property is refused with a JsonException before any handler runs. The Lambda job submitter does not read the response.

For Run, exceptions are logged and rethrown. RunTrainAsync returns a RemoteRunResponse that may carry error fields, from which the Lambda run executor rebuilds a TrainException.

Local server

RunLocalAsync builds a WebApplication from args, maps POST /trax/execute and POST /trax/run, wraps each request body in a LambdaEnvelope, and runs it through the same handler as FunctionHandler. The local routes are for development only; a deployed function is invoked through FunctionHandler. The server reads appsettings.json, its Kestrel endpoints included, from its content root: from the next Trax.Runner.Lambda release AppContext.BaseDirectory, and in released versions the current directory. A --contentRoot argument, or DOTNET_CONTENTROOT / ASPNETCORE_CONTENTROOT, sets it.

Runner postureWhat the local routes accept
SigningKeyRequests with a valid, fresh Trax-Signature header, from any address. The header is checked before the body is read (401), and a body over MaxRequestBodyBytes gets 413. A /trax/run answer carries a Trax-Response-Signature bound to the request, as UseTraxRunEndpoint's does
AllowUnsignedRequests()Unsigned requests from this machine's loopback address only, whatever address the server listens on, and only when the host's environment is Development or the function overrides AllowUnsignedLocalDevelopmentRequests to return true; any other request gets 401. New in the next Trax.Runner.Lambda release: before it, the environment was not checked

The routes are mapped by an internal ConfigureRoutes(IEndpointRouteBuilder), visible to the Trax test assemblies only.

Example

using Amazon.Lambda.Core;
using Amazon.Lambda.Serialization.SystemTextJson;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Effect.JunctionProvider.Progress.Extensions;
using Trax.Mediator.Extensions;
using Trax.Runner.Lambda;
using Trax.Scheduler.Configuration;
 
[assembly: LambdaSerializer(typeof(DefaultLambdaJsonSerializer))]
 
public class Function : TraxLambdaFunction
{
    protected override void ConfigureServices(IServiceCollection services, IConfiguration configuration) =>
        services.AddTrax(trax => trax
            .AddEffects(effects => effects
                .UsePostgres(configuration.GetConnectionString("TraxDatabase")!)
                .AddJunctionProgress())
            .AddMediator(typeof(Function).Assembly));
 
    // The same key as UseLambdaWorkers and UseLambdaRun on the scheduler.
    protected override void ConfigureRunner(TraxJobRunnerOptions runner, IConfiguration configuration) =>
        runner.SigningKey = Convert.FromBase64String(configuration["Trax:RunnerSigningKey"]!);
}

See also