klod68/interceptor-pipeline

name: interceptor-pipeline description: "Use when cross-cutting concerns (logging, metrics, validation, authorization) are tangled into command handlers or service methods, when building database command pipelines with reorderable concerns, or when HTTP client pipelines or message handlers need composable, independently-replaceable processing stages. Covers ICommandInterceptor interface, InterceptorPipeline with reverse-chain construction, zero-cost Empty sentinel to skip overhead when no interceptors are registered, and ConfigureAwait(false) discipline for library code. Domain: Architecture, Cross-Cutting Concerns. Level: Intermediate. Tags: interceptor, pipeline, middleware, decorator, cross-cutting-concerns."

Interceptor Pipeline

Problem

Cross-cutting concerns (logging, metrics, validation, authorization) get tangled into core business logic, making methods long and responsibilities unclear. Each concern is copy-pasted into every command handler.

Solution: Composable Interceptor Chain

Wrap command execution with a pipeline of interceptors. Each interceptor handles one concern and delegates to the next. When no interceptors are registered, a zero-cost Empty sentinel skips the chain entirely.

Core Interface

public interface ICommandInterceptor
{
    Task<T> InterceptAsync<T>(CommandContext context, Func<Task<T>> next);
}

Pipeline Implementation

public sealed class InterceptorPipeline
{
    public static readonly InterceptorPipeline Empty = new([]);

    private readonly IReadOnlyList<ICommandInterceptor> _interceptors;

    public InterceptorPipeline(IReadOnlyList<ICommandInterceptor> interceptors)
    {
        _interceptors = interceptors;
    }

    public bool HasInterceptors => _interceptors.Count > 0;

    public async Task<T> ExecuteAsync<T>(CommandContext context, Func<Task<T>> operation)
    {
        if (_interceptors.Count == 0)
            return await operation().ConfigureAwait(false);

        // Build the chain from innermost (last) to outermost (first)
        Func<Task<T>> chain = operation;
        for (int i = _interceptors.Count - 1; i >= 0; i--)
        {
            var interceptor = _interceptors[i];
            var next = chain;
            chain = () => interceptor.InterceptAsync(context, next);
        }

        return await chain().ConfigureAwait(false);
    }
}

Example Interceptors

public sealed class LoggingInterceptor : ICommandInterceptor
{
    private readonly ILogger _logger;

    public LoggingInterceptor(ILogger logger) => _logger = logger;

    public async Task<T> InterceptAsync<T>(CommandContext context, Func<Task<T>> next)
    {
        _logger.LogInformation("Executing {Command}", context.CommandName);
        var sw = Stopwatch.StartNew();
        try
        {
            var result = await next().ConfigureAwait(false);
            _logger.LogInformation("Completed {Command} in {Elapsed}ms",
                context.CommandName, sw.ElapsedMilliseconds);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed {Command} after {Elapsed}ms",
                context.CommandName, sw.ElapsedMilliseconds);
            throw;
        }
    }
}

public sealed class MetricsInterceptor : ICommandInterceptor
{
    public async Task<T> InterceptAsync<T>(CommandContext context, Func<Task<T>> next)
    {
        using var activity = ActivitySource.StartActivity(context.CommandName);
        return await next().ConfigureAwait(false);
    }
}

When to Use

• Database command execution with cross-cutting logging/metrics
• HTTP client pipelines requiring auth token injection, retry, logging
• Message handlers where validation, deduplication, and logging are separate concerns
• Any pipeline where concerns need to be composed and reordered independently

When NOT to Use

• Simple CRUD with no cross-cutting needs — direct execution is simpler
• Single-concern wrappers — a plain decorator is sufficient
• Request/response middleware in ASP.NET Core — use the built-in middleware pipeline instead

Gotchas

1. Order matters: outermost interceptor runs first. Place logging outside metrics, metrics outside retry.
2. Empty sentinel avoids null checks and has zero overhead — it skips the chain entirely.
3. Each interceptor must call next() exactly once — failing to call it silently drops the operation.
4. Use ConfigureAwait(false) throughout the chain for library code.
5. Don't capture mutable state between interceptors — each should be stateless or scoped.

Related Skills

• Guard Clause Validation (validation interceptor checks preconditions)
• Distributed Logging Correlation (logging interceptor propagates correlation IDs)
• Retry with Exponential Backoff (retry interceptor wraps transient operations)