AWS Lambda with Simple Queue Service

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 IAwsLambdaSQSEndpoint.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

The configuration API exposes NServiceBus configuration options to allow customization; however, not all options will apply to execution within AWS Lambda.

Serializer

The default serializer is the XmlSerializer. A different serializer can be configured:

endpointConfiguration.UseSerialization<SystemJsonSerializer>();

Routing

Specifying command routing for an AWS Lambda endpoint:

var routing = endpointConfiguration.RoutingSettings;
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, token) =>
{
    context.Logger.LogLine(diagnostics);
    return Task.CompletedTask;
});

Delayed Retries

Delayed retries are disabled by default when using AWS Lambda. Delayed retries can be enabled as follows:

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

Error handling

Messages that fail all retries are moved to the error queue. Alternatively, to enable the use of AWS Lambda error handling, the endpoint can be configured to not move messages to the error queue:

endpointConfiguration.DoNotSendMessagesToErrorQueue();

Licenses

The license is provided via the NSERVICEBUS_LICENSE environment variable, which can be set via the Function settings in the Lambda console.

Native integration

It is sometimes useful to access the native Amazon SQS message from behaviors and handlers. In addition to SqsTransport's support for Amazon SQS Native Integration, AwsLambdaSQSEndpoint also provides access to an instance of the native Lambda message type SQSEvent.SQSMessage from the message processing context.

public class AccessToLambdaNativeMessageInHandler : IHandleMessages<TestMessage>
{
  public Task Handle(TestMessage message, IMessageHandlerContext context)
  {
    var nativeMessage = context.Extensions.Get<SQSEvent.SQSMessage>();

    return Task.CompletedTask;
  }
}

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.