Skip to content

Event processing

Install MinimalLambda.EventProcessing to process items from one Lambda event with separate DI scopes. Core-only applications do not expose these APIs or register processing services.

dotnet add package MinimalLambda.EventProcessing
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using MinimalLambda;
using MinimalLambda.Builder;
using MinimalLambda.EventProcessing;

var builder = LambdaApplication.CreateBuilder();
builder.Services.AddScoped<DocumentImporter>();
await using var lambda = builder.Build();
lambda.MapEventHandler(
    split: (ImportBatch batch, ILambdaInvocationContext _) => batch.Items,
    handle: (ImportDocument item, DocumentImporter importer, CancellationToken token) =>
        importer.ImportAsync(item.Event, token));

await lambda.RunAsync();

This registration uses ImportBatch, ImportDocument, and DocumentImporter from the example project.

No AddEventProcessing call or processor registration is required. The package supports the same .NET target frameworks as core. Its matching core dependency supplies the source generator; the optional package does not ship another analyzer.

Callback families

The splitter runs once and returns IEnumerable<TItem>. The processor materializes it before any handler starts. Null enumerable results and enumeration failures fail the invocation.

Handler Error mapper Successful contribution Response
Task absent absent absent
Task synchronous action absent absent
Task absent source item required
Task TFailure absent required
Task<TResult> absent result required
Task<TResult> TResult result required

For handlers without a response, onError can be a synchronous action:

lambda.MapEventHandler(
    split: (ImportBatch batch, ILambdaInvocationContext _) => batch.Items,
    handle: (ImportDocument item, DocumentImporter importer, CancellationToken token) =>
        importer.ImportAsync(item.Event, token),
    onError: (item, exception, processing) =>
    {
        // Log or recover. Return normally to handle the error, or throw to fail the invocation.
    });

The action handles dependency-resolution and handler errors while the item scope remains alive. It may call StopProcessing() or CancelProcessing(). It produces no value or response. Async actions, including async void, are unsupported; put asynchronous recovery in the handler.

For handlers with a response, onError is synchronous (item, exception, processing) => value. It maps errors from service resolution and handler execution. A mapper that throws fails the invocation. Without a mapper, item errors fail the invocation. Nullable response types may return null for normal core serialization. A null returned handler task is an item error eligible for mapping. Async mappers, nested awaitable handler results, and awaitable responses receive a generator diagnostic. Put asynchronous recovery inside the item handler.

Complete outcomes

Every response callback receives IReadOnlyList<EventItemOutcome<TItem, TValue>> plus the invocation context. There is one immutable outcome per source position, in source order, regardless of completion order. Duplicate items remain separate. Empty input calls the builder once with an empty list.

Property Meaning
Index Zero-based source position
Item Original source item, including null where the source type allows it
Status Succeeded, MappedError, Skipped, or Cancelled
HasValue A contribution exists, even if its value is null
Value Handler, source-item, or mapped contribution
Exception Original error for MappedError, otherwise null

A handler-returned domain failure still has Succeeded status. The framework does not interpret application result types. Skipped means the item never started; Cancelled means processing cancellation interrupted admitted work. A successfully completed handler retains its result.

Applications own acknowledgement and retry. For example, this SQS response includes both mapped failures and items that never completed. Add MinimalLambda.Envelopes.Sqs and use the example project's MyEvent, ImportItemResult, Retry, and DocumentImporter types:

using Amazon.Lambda.SQSEvents;
using MinimalLambda.Envelopes.Sqs;

lambda.MapEventHandler(
    split: (SqsEnvelope<MyEvent> batch, ILambdaInvocationContext _) => batch.Records,
    handle: async Task<ImportItemResult> (
        SqsEnvelope<MyEvent>.SqsMessageEnvelope item,
        DocumentImporter importer,
        CancellationToken token) => item.BodyContent is null
            ? new Retry(item.MessageId)
            : await importer.ImportResultAsync(item.BodyContent, token),
    onError: (item, error, processing) => new Retry(item.MessageId),
    createResponse: (outcomes, _) => new SQSBatchResponse(
        outcomes
            .Where(outcome => outcome.Status != EventItemStatus.Succeeded || outcome.Value is Retry)
            .Select(outcome => new SQSBatchResponse.BatchItemFailure
            {
                ItemIdentifier = outcome.Item.MessageId,
            })
            .ToList()));

Configure the SQS event source mapping to report partial batch failures. For FIFO ordering, use sequential processing and stop when the application decides later records must wait. Include the failed and unstarted records in the response. For stream sources, construct the source-specific checkpoint from the complete outcomes. The package never chooses acknowledgements or retries.

Binding and scopes

The item is the handler's first argument. Up to ten further parameters bind as follows:

  • ILambdaInvocationContext or ILambdaContext receives the invocation context.
  • IEventProcessingContext receives shared per-invocation processing controls.
  • CancellationToken receives the processing token.
  • Other arguments resolve from a fresh asynchronous item scope, including required, nullable, [FromServices], and [FromKeyedServices] arguments.

A declared optional default applies when the service is missing. A registered zero or empty string is retained. Each framework argument may appear once and cannot have service/event attributes. The full incoming event type comes from the splitter, not [FromEvent] on a handler argument.

The scope remains alive through argument resolution, execution, and error mapping. Scope creation or disposal failure fails the invocation. The processor stops admission and drains admitted handlers, cancellation callbacks, and scope cleanup before returning. Return DTOs that remain usable after scope disposal.

Item scopes are separate from the invocation scope. A scoped service resolved by middleware is not the same instance injected into an item handler.

Typed delegates supply the parameter types used for binding. Attributes on the underlying handler method still apply when its parameters accept broader types.

Method groups cannot infer dependency types for these overloads. Use a typed lambda, a typed delegate local, or explicit generic arguments. A Task<TResult> handler cannot be passed to a no-result family.

Options and cancellation

Defaults enable concurrency with at most ten active items per invocation. Scope disposal counts against that limit. This is item concurrency inside one invocation.

builder.Services.Configure<EventHandlerOptions>(options =>
{
    options.EnableConcurrency = false;
    options.MaxConcurrentExecutions = 1;
});

Options are captured and validated when mapping, after Build(). The maximum must be positive even when concurrency is disabled. Configuration and options-validation exceptions propagate before any callback runs.

StopProcessing() stops new admissions and lets admitted items finish. CancelProcessing() also cancels the processing token. Both allow a response built from complete outcomes. Repeated calls are safe. Pass the processing token into cancellable item work.

Invocation cancellation is separate and fails the invocation. It remains effective through cleanup. The processor checks it immediately before response construction and before storing the response, so cancellation during a synchronous response builder also suppresses its response. Invocation cancellation takes precedence over concurrent item errors. Once the response is stored, core owns serialization.

Registration and middleware

MapEventHandler consumes the same terminal-handler slot as MapHandler. A second mapping throws before replacing provider properties. Existing custom providers retain precedence.

The generated interceptor creates one HandleItem(item, itemServices, processing) wrapper, calls EventHandlerFactory.Create(application.Services, ...), registers its terminal through Handle, and emits normal event/final-response provider setup. Scheduling and error/cancellation state remain internal package code. Core middleware, envelope extraction/packing, deserialization, and serialization use their existing pipeline. Intermediate result types are not registered as response types.

Serialization and Native AOT

For Native AOT, register a source-generated JSON serializer for the full event and final response. With SqsEnvelope<MyEvent>, include SqsEnvelope<MyEvent>, MyEvent, and SQSBatchResponse in the JSON context, and set ConfigureEnvelopeOptions to use that context's resolver for message bodies. Item results such as ImportItemResult need no serializer metadata unless the final response contains them. Register the serializer and envelope resolver before Build():

builder.Services.AddLambdaSerializerWithContext<EventProcessorJsonContext>();
builder.Services.ConfigureEnvelopeOptions(options =>
    options.JsonOptions.TypeInfoResolver = EventProcessorJsonContext.Default);

Declare the context after the top-level statements:

[System.Text.Json.Serialization.JsonSerializable(typeof(SqsEnvelope<MyEvent>))]
[System.Text.Json.Serialization.JsonSerializable(typeof(MyEvent))]
[System.Text.Json.Serialization.JsonSerializable(typeof(SQSBatchResponse))]
internal partial class EventProcessorJsonContext
    : System.Text.Json.Serialization.JsonSerializerContext;

See the example project for response and no-response examples.