AWS Lambda with Simple Queue Service

Source
NuGet Package NServiceBus.AwsLambda.SQS (0.x) | License
This is a Preview project.
Target NServiceBus Version: 7.x

Host NServiceBus endpoints with AWS Lambda using the Simple Queue Service as a trigger.

Basic usage

An NServiceBus endpoint is hosted in AWS Lambda by creating an AwsLambdaSQSEndpoint instance and calling the Process method from within an AWS Lambda definition.

AwsLambdaSQSEndpoint creation

The endpoint should be instantiated only once, when the lambda is first called, and assigned to a static field:

static readonly AwsLambdaSQSEndpoint endpoint = new AwsLambdaSQSEndpoint(context =>
{
    var endpointConfiguration = new AwsLambdaSQSEndpointConfiguration("AwsLambdaSQSTrigger");
    
    //customize configuration here

    return endpointConfiguration;
});

Since the cost of starting an AwsLambdaSQSEndpoint endpoint can be high, it is recommended to configure the lambda's concurrency to minimize cold starts.

Calling the Process method

The AwsLambdaSQSEndpoint.Process method is invoked inside the function handler:

public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context)
{
    var cancellationDelay = context.RemainingTime.Subtract(TimeSpan.FromSeconds(10));
    using (var cancellationTokenSource = new CancellationTokenSource(cancellationDelay))
    {
        await endpoint.Process(evnt, context, cancellationTokenSource.Token);
    }
}

Queue creation

Transport installers are not supported. The creation of the required queues may be scripted using the CLI.

Configuration

Routing

Specifying command routing for an AWS Lambda endpoint:

var transport = endpointConfiguration.Transport;
var routing = transport.Routing();
routing.RouteToEndpoint(typeof(ACommand), "<destination>");

Diagnostics

NServiceBus startup diagnostics are disabled by default when using AWS Lambda. Diagnostics may be enabled as follows:

var advanced = endpointConfiguration.AdvancedConfiguration;

advanced.CustomDiagnosticsWriter(diagnostics =>
{
    context.Logger.LogLine(diagnostics);
    return Task.CompletedTask;
});

Delayed Retries

Delayed retries are disabled by default when using AWS Lambdas. Delayed retries may be enabled as follows:

var recoverability = endpointConfiguration.AdvancedConfiguration.Recoverability();
recoverability.Delayed(customization =>
{
    customization.NumberOfRetries(5);
    customization.TimeIncrease(TimeSpan.FromSeconds(15));
});

If the accumulated time increase is expected to be greater than 15 minutes, UnrestrictedDurationDelayedDelivery must be enabled:

endpointConfiguration.Transport.UnrestrictedDurationDelayedDelivery();
Automatic creation of the required queues for unrestricted delayed delivery is not supported. The creation of the required queues may be scripted using the CLI.

Error queue

Messages which fail all retries are moved to the error queue, which must be defined as follows:

var advanced = endpointConfiguration.AdvancedConfiguration;

advanced.SendFailedMessagesTo("<error-queue>");

Alternatively, the endpoint may be configured to never move failing messages to the error queue as follows:

endpointConfiguration.DoNotSendMessagesToErrorQueue();

Serializer

There is no default serializer, so one must be configured. For example:

endpointConfiguration.UseSerialization<NewtonsoftSerializer>();

Licenses

License text may be specified using an environment variable, which may be updated during runtime.

var licenseText = Environment.GetEnvironmentVariable("NServiceBusLicenseText");

var advanced = endpointConfiguration.AdvancedConfiguration;

advanced.License(licenseText);

The environment variable may be updated by configuring environment variables for the lambda.

Supported features

The AwsLambdaSQSEndpoint class supports the full feature set of NServiceBus including:

  • Outbox
  • Sagas
  • Delayed Delivery
  • Recoverability
  • Publish / Subscribe

Persistence is required to use some of these features.

Transactions

As the AwsLambdaSQSEndpoint uses the SqsTransport, it only supports the Receive Only and Disabled transaction modes.

Samples


Last modified