DEV Community: Adrián Bailador

Uber-like System in .NET: Driver Matching, Surge Pricing and the Complete Request Flow

Adrián Bailador — Mon, 25 May 2026 06:15:28 +0000

A rider opens the app and taps "Request". In the next two seconds, the system has to find which of the hundreds of nearby drivers to offer the trip to, calculate a price that reflects current demand, and send the offer — all before the rider's patience runs out.

Most of what makes that hard isn't the individual pieces. It's connecting them. The location pipeline doesn't know about trips. The trip state machine doesn't know about drivers. Surge pricing doesn't know about either. Making them work together, under load, without races or stale data — that's the engineering problem.

This is Part 3 of the Uber-like System Design in .NET series. In Part 1 we built real-time location tracking with Redis GEO and SignalR. In Part 2 we modelled the trip lifecycle with state machines and EF Core. Here we build driver matching, surge pricing, and trace the full request flow end to end.

The Full Architecture

Before the code, the picture:

The request flow at a high level:

Rider requests a trip → fare estimate with surge applied
System queries Redis GEO for nearby available drivers
Drivers are scored and ranked; top candidate receives the offer
Driver accepts → trip transitions through its state machine
Trip completes → payment fires, driver releases back to the pool

Each step is independent enough to test and deploy separately. The state machine from Part 2 is the spine — everything else connects to it through domain events or direct calls.

Step 1: Driver Availability State

The location pipeline from Part 1 knows where drivers are. Driver matching needs to know which drivers are available. These are separate concerns that share Redis.

public enum DriverStatus
{
    Offline,
    Available,
    OnTrip,
    Busy
}

public class DriverAvailabilityService
{
    private readonly IDatabase _redis;
    private const string StatusKeyPrefix = "driver:status:";
    private const string AvailableSet = "drivers:available";

    public DriverAvailabilityService(IConnectionMultiplexer redis)
        => _redis = redis.GetDatabase();

    public async Task SetAvailableAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "Available");
        await _redis.SetAddAsync(AvailableSet, driverId);
    }

    public async Task SetOnTripAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "OnTrip");
        await _redis.SetRemoveAsync(AvailableSet, driverId);
    }

    public async Task SetOfflineAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "Offline");
        await _redis.SetRemoveAsync(AvailableSet, driverId);
    }

    public async Task<bool> IsAvailableAsync(string driverId)
    {
        var status = await _redis.StringGetAsync($"{StatusKeyPrefix}{driverId}");
        return status == "Available";
    }
}

drivers:available is a Redis Set of driver IDs. When a driver goes online, their ID is added; when they accept a trip or go offline, it's removed. The availability check is O(1). The set intersection with the GEO query result is the core of matching.

Step 2: Finding Nearby Available Drivers

Redis GEO stores driver positions. GEOSEARCH returns drivers within a radius ordered by distance. The matching query intersects that result with the availability set:

public class DriverMatchingService
{
    private readonly IDatabase _redis;
    private readonly DriverAvailabilityService _availability;
    private const string GeoKey = "drivers:geo";

    public DriverMatchingService(
        IConnectionMultiplexer redis,
        DriverAvailabilityService availability)
    {
        _redis = redis.GetDatabase();
        _availability = availability;
    }

    public async Task<IReadOnlyList<DriverCandidate>> FindNearbyAsync(
        double pickupLat,
        double pickupLon,
        double radiusKm,
        int maxResults = 10)
    {
        var geoResults = await _redis.GeoSearchAsync(
            GeoKey,
            new GeoSearchCircle(pickupLon, pickupLat, radiusKm, GeoUnit.Kilometers),
            order: Order.Ascending,
            count: maxResults * 3); // fetch more than needed to account for unavailable ones

        var candidates = new List<DriverCandidate>();

        foreach (var result in geoResults)
        {
            var driverId = result.Member.ToString();

            if (!await _availability.IsAvailableAsync(driverId))
                continue;

            candidates.Add(new DriverCandidate(
                DriverId: driverId,
                DistanceKm: result.Distance ?? double.MaxValue));

            if (candidates.Count >= maxResults)
                break;
        }

        return candidates;
    }
}

public record DriverCandidate(string DriverId, double DistanceKm);

Fetching maxResults * 3 from Redis and filtering client-side avoids a round-trip per driver for the availability check. The trade-off: if most nearby drivers are unavailable (surge scenario), you might miss candidates at the edge of the radius. For a production system, you'd expand the search radius dynamically rather than fetching a fixed multiplier.

Production note — back-off radius: The * 3 multiplier is fragile under peak demand. On a Friday night after a concert, 95% of nearby drivers may be OnTrip. Redis returns 30 results, all unavailable, and the method returns an empty list even though free drivers exist 6 km out. The production fix is an expanding search loop: if the first query returns fewer candidates than needed, widen the radius and query again — stopping when you have enough candidates or reach a maximum radius threshold.

Step 3: Scoring and Ranking Drivers

Distance alone is a poor signal. A driver 500 metres away with a 3.2 rating is a worse match than a driver 800 metres away with a 4.8. The scoring function weights the factors that matter:

public class DriverScoringService
{
    public IReadOnlyList<ScoredDriver> Rank(
        IReadOnlyList<DriverCandidate> candidates,
        IReadOnlyDictionary<string, DriverProfile> profiles)
    {
        return candidates
            .Where(c => profiles.ContainsKey(c.DriverId))
            .Select(c =>
            {
                var profile = profiles[c.DriverId];
                var score = CalculateScore(c.DistanceKm, profile);
                return new ScoredDriver(c.DriverId, c.DistanceKm, profile.Rating, score);
            })
            .OrderByDescending(d => d.Score)
            .ToList();
    }

    private static double CalculateScore(double distanceKm, DriverProfile profile)
    {
        // Distance: closer is better, capped at 5 km; diminishing penalty past that
        var distanceFactor = Math.Max(0, 1 - (distanceKm / 5.0));

        // Rating: normalised 0–1 from 1–5 scale
        var ratingFactor = (profile.Rating - 1.0) / 4.0;

        // Acceptance rate: drivers who decline frequently get penalised
        var acceptanceFactor = profile.AcceptanceRate;

        // Weighted sum — adjust weights per product requirements
        return (distanceFactor * 0.5) + (ratingFactor * 0.35) + (acceptanceFactor * 0.15);
    }
}

public record ScoredDriver(string DriverId, double DistanceKm, double Rating, double Score);

public record DriverProfile(string DriverId, double Rating, double AcceptanceRate);

The weights are tunable. In a real system they'd be configured per city and time of day. During morning commutes, distance weight goes up — riders want the fastest pickup. Late at night, rating weight goes up — safety matters more than speed.

Step 4: Surge Pricing

Surge pricing is a supply/demand signal. When many riders are requesting and few drivers are available, the price rises to attract more drivers and reduce demand.

The simplest model uses a ratio:

public class SurgePricingService
{
    private readonly IDatabase _redis;
    private const string DemandKeyPrefix = "surge:demand:";
    private const string SupplyKeyPrefix = "surge:supply:";
    private static readonly TimeSpan Window = TimeSpan.FromMinutes(5);

    public SurgePricingService(IConnectionMultiplexer redis)
        => _redis = redis.GetDatabase();

    public async Task RecordRequestAsync(string gridCell)
    {
        var key = $"{DemandKeyPrefix}{gridCell}";
        var pipe = _redis.CreateBatch();
        _ = pipe.StringIncrementAsync(key);
        _ = pipe.KeyExpireAsync(key, Window);
        pipe.Execute();
    }

    public async Task RecordDriverAvailableAsync(string gridCell)
    {
        var key = $"{SupplyKeyPrefix}{gridCell}";
        var pipe = _redis.CreateBatch();
        _ = pipe.StringIncrementAsync(key);
        _ = pipe.KeyExpireAsync(key, Window);
        pipe.Execute();
    }

    public async Task<decimal> GetSurgeMultiplierAsync(string gridCell)
    {
        var demandTask = _redis.StringGetAsync($"{DemandKeyPrefix}{gridCell}");
        var supplyTask = _redis.StringGetAsync($"{SupplyKeyPrefix}{gridCell}");

        await Task.WhenAll(demandTask, supplyTask);

        var demand = (double)(long)(demandTask.Result.IsNullOrEmpty ? 1 : demandTask.Result);
        var supply = (double)(long)(supplyTask.Result.IsNullOrEmpty ? 1 : supplyTask.Result);

        if (supply == 0) return 3.0m; // no drivers → maximum surge

        var ratio = demand / supply;

        return ratio switch
        {
            <= 1.0 => 1.0m,
            <= 1.5 => 1.2m,
            <= 2.0 => 1.5m,
            <= 3.0 => 2.0m,
            <= 4.0 => 2.5m,
            _ => 3.0m  // cap at 3x
        };
    }
}

gridCell is an H3 or geohash cell identifier — a string that encodes a geographic area. You derive it from the rider's pickup coordinates. All riders and drivers in the same cell share the same demand/supply counters.

The 5-minute rolling window keeps surge responsive. Counters expire naturally; there's no cleanup job needed. The cap at 3x is a business decision — uncapped surge generates bad press and rider churn faster than it attracts drivers.

Step 5: Fare Estimation

Before confirming the request, the rider sees an estimated fare. The estimate uses the surge multiplier from Step 4 and a simple per-km/per-minute rate:

public class FareEstimationService
{
    private const decimal BaseRate = 1.50m;
    private const decimal PerKm = 1.20m;
    private const decimal PerMinute = 0.20m;

    public async Task<FareEstimate> EstimateAsync(
        double pickupLat, double pickupLon,
        double dropoffLat, double dropoffLon,
        string gridCell,
        SurgePricingService surge)
    {
        var distanceKm = HaversineDistance(pickupLat, pickupLon, dropoffLat, dropoffLon);
        var estimatedMinutes = distanceKm / 0.5; // rough 30 km/h average
        var surgeMultiplier = await surge.GetSurgeMultiplierAsync(gridCell);

        var baseFare = BaseRate + (PerKm * (decimal)distanceKm) + (PerMinute * (decimal)estimatedMinutes);
        var totalFare = Math.Round(baseFare * surgeMultiplier, 2);

        return new FareEstimate(totalFare, surgeMultiplier, distanceKm);
    }

    private static double HaversineDistance(
        double lat1, double lon1, double lat2, double lon2)
    {
        const double R = 6371;
        var dLat = ToRad(lat2 - lat1);
        var dLon = ToRad(lon2 - lon1);
        var a = Math.Sin(dLat / 2) * Math.Sin(dLat / 2)
              + Math.Cos(ToRad(lat1)) * Math.Cos(ToRad(lat2))
              * Math.Sin(dLon / 2) * Math.Sin(dLon / 2);
        return R * 2 * Math.Atan2(Math.Sqrt(a), Math.Sqrt(1 - a));
    }

    private static double ToRad(double deg) => deg * Math.PI / 180;
}

public record FareEstimate(decimal Total, decimal SurgeMultiplier, double DistanceKm);

The estimate is a range, not a commitment. The actual fare is calculated on trip completion based on real distance and time. What matters at request time is that the rider understands they're in a surge zone.

Step 6: The Trip Request Coordinator

This is where the pieces connect. The coordinator runs when a rider taps "Request". It's a service, not a controller — it orchestrates the other services and has no HTTP knowledge:

public class TripRequestCoordinator
{
    private readonly AppDbContext _db;
    private readonly DriverMatchingService _matching;
    private readonly DriverAvailabilityService _availability;
    private readonly SurgePricingService _surge;
    private readonly FareEstimationService _fares;
    private readonly IEventBus _events;
    private readonly ILogger<TripRequestCoordinator> _logger;

    public TripRequestCoordinator(
        AppDbContext db,
        DriverMatchingService matching,
        DriverAvailabilityService availability,
        SurgePricingService surge,
        FareEstimationService fares,
        IEventBus events,
        ILogger<TripRequestCoordinator> logger)
    {
        _db = db;
        _matching = matching;
        _availability = availability;
        _surge = surge;
        _fares = fares;
        _events = events;
        _logger = logger;
    }

    public async Task<TripRequestResult> RequestTripAsync(
        RequestTripCommand command,
        CancellationToken ct = default)
    {
        var gridCell = GeohashEncoder.Encode(command.PickupLat, command.PickupLon, precision: 5);

        // Estimate fare with surge before creating the trip
        var fareEstimate = await _fares.EstimateAsync(
            command.PickupLat, command.PickupLon,
            command.DropoffLat, command.DropoffLon,
            gridCell, _surge);

        // Find available drivers
        var candidates = await _matching.FindNearbyAsync(
            command.PickupLat, command.PickupLon,
            radiusKm: 5);

        if (candidates.Count == 0)
        {
            _logger.LogInformation("No drivers available near {Lat},{Lon}", 
                command.PickupLat, command.PickupLon);
            return TripRequestResult.NoDriversAvailable(fareEstimate);
        }

        // Create the trip in Requested state
        var trip = Trip.Create(command.RiderId);
        _db.Trips.Add(trip);
        await _db.SaveChangesAsync(ct);

        // Record demand for surge calculation
        await _surge.RecordRequestAsync(gridCell);

        // Offer to the best candidate
        var best = candidates[0];
        await _events.PublishAsync(new DriverOfferSent(trip.Id, best.DriverId, fareEstimate), ct);

        return TripRequestResult.Offered(trip.Id, fareEstimate, best.DriverId);
    }
}

public record RequestTripCommand(
    Guid RiderId,
    double PickupLat, double PickupLon,
    double DropoffLat, double DropoffLon);

public abstract record TripRequestResult
{
    public static TripRequestResult Offered(Guid tripId, FareEstimate fare, string driverId)
        => new TripOffered(tripId, fare, driverId);

    public static TripRequestResult NoDriversAvailable(FareEstimate fare)
        => new NoDrivers(fare);
}

public record TripOffered(Guid TripId, FareEstimate FareEstimate, string DriverId) : TripRequestResult;
public record NoDrivers(FareEstimate FareEstimate) : TripRequestResult;

The coordinator doesn't call AssignDriver directly — it publishes a DriverOfferSent event. The driver receives a push notification, taps "Accept", and that triggers AssignDriver through the TripService from Part 2. This matters: the driver might decline, the offer might time out, or the driver might go offline before responding. The trip stays in Requested until the driver actively accepts.

Step 7: The Driver Acceptance Flow

When the driver taps "Accept", we need to atomically check they're still available and assign the trip:

public class DriverAcceptanceService
{
    private readonly TripService _trips;
    private readonly DriverAvailabilityService _availability;

    public DriverAcceptanceService(TripService trips, DriverAvailabilityService availability)
    {
        _trips = trips;
        _availability = availability;
    }

    public async Task<Result> AcceptTripAsync(
        Guid tripId,
        string driverId,
        CancellationToken ct = default)
    {
        // Check availability before committing to the assignment
        if (!await _availability.IsAvailableAsync(driverId))
            return Result.Fail("Driver is no longer available.");

        // AssignDriver handles the concurrency case: if two drivers
        // somehow both try to accept the same trip, the second will
        // get DbUpdateConcurrencyException and fail cleanly.
        var result = await _trips.AssignDriverAsync(tripId, driverId, ct);

        if (result.Success)
            await _availability.SetOnTripAsync(driverId);

        return result;
    }
}

The TripService.AssignDriverAsync from Part 2 uses optimistic concurrency. Even if two drivers somehow both tap "Accept" at the same millisecond, only one write succeeds. The second gets a DbUpdateConcurrencyException, retries, finds the trip is already DriverAssigned, and fails cleanly with a meaningful error.

Step 8: The Complete Request Flow in Minimal API

Wiring the full flow into endpoints:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddStackExchangeRedisCache(o =>
    o.Configuration = builder.Configuration["Redis:ConnectionString"]);
builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect(builder.Configuration["Redis:ConnectionString"]!));
builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));

builder.Services.AddScoped<TripRequestCoordinator>();
builder.Services.AddScoped<TripService>();
builder.Services.AddScoped<DriverAcceptanceService>();
builder.Services.AddScoped<DriverAvailabilityService>();
builder.Services.AddScoped<DriverMatchingService>();
builder.Services.AddScoped<SurgePricingService>();
builder.Services.AddScoped<FareEstimationService>();
builder.Services.AddHostedService<TripTimeoutService>();

var app = builder.Build();

// 1. Rider requests a trip
app.MapPost("/trips/request", async (
    RequestTripCommand command,
    TripRequestCoordinator coordinator,
    CancellationToken ct) =>
{
    var result = await coordinator.RequestTripAsync(command, ct);

    return result switch
    {
        TripOffered offered => Results.Accepted($"/trips/{offered.TripId}", offered),
        NoDrivers noDrivers => Results.Ok(new { message = "No drivers nearby", fare = noDrivers.FareEstimate }),
        _ => Results.Problem("Unexpected state")
    };
});

// 2. Driver accepts the trip
app.MapPost("/trips/{tripId:guid}/accept", async (
    Guid tripId,
    AcceptTripDto dto,
    DriverAcceptanceService acceptance,
    CancellationToken ct) =>
{
    var result = await acceptance.AcceptTripAsync(tripId, dto.DriverId, ct);
    return result.Success ? Results.Ok() : Results.Conflict(new { error = result.Error });
});

// 3. Driver en route to pickup
app.MapPost("/trips/{tripId:guid}/en-route", async (
    Guid tripId,
    AppDbContext db,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try { trip.DriverEnRoute(); await db.SaveChangesAsync(ct); return Results.Ok(); }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 4. Trip starts (driver and rider both at pickup)
app.MapPost("/trips/{tripId:guid}/start", async (
    Guid tripId,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try
    {
        trip.Start();
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events) await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 5. Trip completes
app.MapPost("/trips/{tripId:guid}/complete", async (
    Guid tripId,
    CompleteTripDto dto,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try
    {
        trip.Complete(dto.FareAmount);
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events) await events.PublishAsync(evt, ct);
        // Driver release happens in the TripCompleted event handler — not inline.
        // This keeps cancels and completes consistent: both paths release the driver
        // through the same event subscriber, never through the API layer.
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 6. Get surge multiplier for an area (shown to rider before confirming)
app.MapGet("/surge", async (
    double lat,
    double lon,
    SurgePricingService surge) =>
{
    var gridCell = GeohashEncoder.Encode(lat, lon, precision: 5);
    var multiplier = await surge.GetSurgeMultiplierAsync(gridCell);
    return Results.Ok(new { multiplier });
});

// 7. Driver goes online
app.MapPost("/drivers/{driverId}/online", async (
    string driverId,
    DriverAvailabilityService availability,
    SurgePricingService surge,
    GoOnlineDto dto) =>
{
    await availability.SetAvailableAsync(driverId);
    var gridCell = GeohashEncoder.Encode(dto.Lat, dto.Lon, precision: 5);
    await surge.RecordDriverAvailableAsync(gridCell);
    return Results.Ok();
});

app.Run();

Step 9: The Offer Timeout

When we send a DriverOfferSent event, the driver has a limited window to accept. If they don't respond, we need to offer the trip to the next candidate. This is the same background pattern as trip timeouts, but at the offer level:

public class DriverOfferTimeoutService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private static readonly TimeSpan OfferTimeout = TimeSpan.FromSeconds(15);
    private static readonly TimeSpan CheckInterval = TimeSpan.FromSeconds(5);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(CheckInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var matching = scope.ServiceProvider.GetRequiredService<DriverMatchingService>();
            var events = scope.ServiceProvider.GetRequiredService<IEventBus>();

            var cutoff = DateTimeOffset.UtcNow - OfferTimeout;

            // Find trips still Requested (offer not accepted) past the timeout
            var stalled = await db.Trips
                .Where(t => t.Status == TripStatus.Requested && t.RequestedAt < cutoff)
                .ToListAsync(stoppingToken);

            foreach (var trip in stalled)
            {
                // Re-run matching — the original candidate may have gone offline
                var nextCandidates = await matching.FindNearbyAsync(
                    trip.PickupLat, trip.PickupLon, radiusKm: 7); // slightly wider radius

                if (nextCandidates.Count == 0)
                {
                    // Cancel trip — no drivers available
                    try
                    {
                        trip.Cancel("No drivers available after timeout.", "system");
                        await db.SaveChangesAsync(stoppingToken);
                    }
                    catch (Exception) { /* Already transitioned */ }
                    continue;
                }

                var next = nextCandidates[0];
                await events.PublishAsync(new DriverOfferSent(trip.Id, next.DriverId, null), stoppingToken);
            }
        }
    }
}

Each retry widens the search radius slightly. After a configurable number of retries with no acceptance, the trip cancels. The TripTimeoutService from Part 2 acts as the final backstop if this service somehow misses a trip.

What Uber Actually Does

The architecture here is the right shape, but Uber's implementation at scale differs in important ways.

Driver matching uses their own geospatial index, not stock Redis GEO. Redis GEO uses a geohash-based sorted set — fast, but the precision is fixed. Uber uses H3, Uber's own hexagonal geospatial indexing system, which allows dynamic resolution changes and makes aggregations (like surge pricing per cell) much cleaner.

Offer dispatch in this article publishes one offer at a time. Uber uses parallel dispatch — the trip is offered to several candidates simultaneously, and the first to accept wins. This significantly reduces the time-to-assignment at the cost of occasionally "wasting" an offer when multiple drivers accept and all but one have to be rejected.

Surge pricing in production is a learned model, not a ratio table. Demand predictions are based on historical patterns, current events, and weather. The surge multiplier is calculated at fine-grained H3 cells and interpolated at boundaries to avoid the "why is 10 metres away cheaper?" problem.

Trip assignment uses a saga pattern, not the direct state machine calls here. The assignment orchestrator in Cadence/Temporal handles driver acceptance, timeouts, fallback sequences, and cancellation compensation as a durable workflow — if the service restarts mid-assignment, the workflow resumes from where it left off.

None of that changes the concepts: find drivers, score them, present a price, enforce valid transitions, handle failure cases. The scale changes the implementation, not the model.

Common Mistakes

Mistake 1: Querying the database for driver locations

// ❌ SQL can't do this efficiently at volume
var nearbyDrivers = await db.Drivers
    .Where(d => d.Status == "Available"
             && HaversineDistance(d.Lat, d.Lon, pickupLat, pickupLon) < 5)
    .ToListAsync();

PostGIS makes this feasible, but you're still doing a disk read for every request. At high volume, Redis GEO handles millions of position updates per second and returns nearby entries in single-digit milliseconds.

Mistake 2: Surge pricing with a global counter

// ❌ One counter for the whole city
await _redis.StringIncrementAsync("total:requests");

Surge pricing is hyper-local. A city-wide surplus of drivers doesn't help a rider in a neighbourhood where every driver is on a trip. Granular grid cells (geohash or H3) are the primitive, not city-level aggregates.

Mistake 3: Assigning a driver without checking availability in the same operation

// ❌ Gap between availability check and state change
if (await _availability.IsAvailableAsync(driverId))
{
    // Another request comes in here and assigns this driver elsewhere
    await _trips.AssignDriverAsync(tripId, driverId);
}

The optimistic concurrency on the trip assignment (Part 2) protects against two trips racing for one driver only if the AssignDriver call is atomic with the database write. The Redis availability check is a separate system — there's always a gap. Handle it: the TripService retry loop will surface the stale state and fail cleanly.

Mistake 4: Not handling the "no drivers" case in the UI

The no-drivers scenario is not an error. It's an expected outcome that should show the rider a useful message, the current surge level, and an estimated wait time if they want to retry. Returning a 500 or leaving the rider on a spinner for 30 seconds is a product failure, not just a technical one.

Mistake 5: Forgetting to release the driver on cancellation

// ❌ Driver is stuck OnTrip in Redis even after cancel
trip.Cancel("Rider cancelled.", "rider");
await db.SaveChangesAsync(ct);
// Driver never goes back to Available

Every Cancel — whether by the rider, the system timeout, or payment failure — must release the driver back to Available. Wire it through the TripCancelled domain event handler, not inline, so it happens consistently regardless of which code path triggers the cancel.

Conclusion

Three articles, three layers. The location pipeline in Part 1 knows where drivers are. The state machine in Part 2 knows what a trip is. The matching and pricing logic in this article knows how to connect a rider to a driver with a price that reflects current supply and demand.

The pieces stay independent by design. Driver availability is Redis state, not a database flag. Surge pricing reads the same Redis cells without knowing about trips. The trip state machine doesn't know about Redis. Each service can be replaced or scaled independently.

What holds it together is the event bus. DriverOfferSent, TripStarted, TripCompleted, TripCancelled — these are the contracts between parts of the system. When a trip completes, the state machine doesn't call the payment service. It publishes TripCompleted, and every system that cares — payment, notifications, availability release, surge adjustment — responds independently.

That separation is what makes this architecture maintainable at scale. Add a new reaction to TripCompleted and nothing else changes. Add a new driver scoring factor and only DriverScoringService changes. The Uber-like system you've built in these three articles isn't a tutorial CRUD app — it's a structural approach that holds up when the requirements get complicated.

Part 3 of the Uber-like System Design in .NET series.

Parts 1 and 2: Real-time Location Tracking · Trip State Machine

Full source code: github.com/AdrianBailador/uber-driver-matching-dotnet

Questions or suggestions? Open an issue on GitHub.

State Machines in .NET: Modelling Uber's Trip Lifecycle with EF Core

Adrián Bailador — Sun, 17 May 2026 09:37:36 +0000

A rider opens the app and requests a trip. A driver accepts. The driver is already moving toward the pickup when a bug in the assignment service fires a second time — and assigns a different driver to the same trip.

Now two drivers are heading to the same address, both thinking they have a fare. One of them will arrive, wait, and leave confused. The other will complete the trip. Depending on which one gets marked as completed first, the rider might be charged twice — or not at all.

This is what happens when you store trip data as a plain row in a database without enforcing valid state transitions. It's not a theoretical problem. It's the kind of bug that appears in production at 2am on a Friday, after months of working fine in development.

State machines solve this. Not because they're elegant (though they are) — because they make illegal transitions impossible, not just unlikely.

This is Part 2 of the Uber-like System Design in .NET series. In Part 1 we built the real-time location pipeline. Here we model the trip lifecycle: the states, the transitions, the persistence, and the race conditions.

The Trip Lifecycle

A trip moves through a defined sequence of states. Each state has a limited set of valid transitions — and any other transition is a bug.

The transitions that matter most are the ones that aren't allowed. A trip cannot go from Completed back to InProgress. A Cancelled trip cannot be assigned a driver. A payment cannot fire on a Requested trip. These aren't edge cases — they're the boundaries that define what a trip is.

Step 1: Modelling the States

Start with an enum that expresses the full lifecycle:

public enum TripStatus
{
    Requested,
    DriverAssigned,
    DriverEnRoute,
    InProgress,
    Completed,
    Cancelled,
    PaymentFailed
}

And a record for the transitions you want to raise as domain events:

public abstract record TripEvent
{
    public Guid TripId { get; init; }
    public DateTimeOffset OccurredAt { get; init; } = DateTimeOffset.UtcNow;
}

public record DriverAssigned(Guid TripId, string DriverId) : TripEvent;
public record TripStarted(Guid TripId) : TripEvent;
public record TripCompleted(Guid TripId, decimal FareAmount) : TripEvent;
public record TripCancelled(Guid TripId, string Reason, string CancelledBy) : TripEvent;
public record PaymentFailed(Guid TripId, string Reason) : TripEvent;

Step 2: The Transition Rules

The state machine is just a set of rules: given the current state, which transitions are valid?

public static class TripTransitions
{
    private static readonly Dictionary<TripStatus, HashSet<TripStatus>> _allowed = new()
    {
        [TripStatus.Requested]      = [TripStatus.DriverAssigned, TripStatus.Cancelled],
        [TripStatus.DriverAssigned] = [TripStatus.DriverEnRoute, TripStatus.Cancelled],
        [TripStatus.DriverEnRoute]  = [TripStatus.InProgress, TripStatus.Cancelled],
        [TripStatus.InProgress]     = [TripStatus.Completed, TripStatus.Cancelled],
        [TripStatus.Completed]      = [TripStatus.PaymentFailed],
        [TripStatus.PaymentFailed]  = [TripStatus.Completed, TripStatus.Cancelled],
        [TripStatus.Cancelled]      = [],
    };

    public static bool IsAllowed(TripStatus from, TripStatus to)
        => _allowed.TryGetValue(from, out var targets) && targets.Contains(to);

    public static void Validate(TripStatus from, TripStatus to)
    {
        if (!IsAllowed(from, to))
            throw new InvalidTripTransitionException(from, to);
    }
}

public class InvalidTripTransitionException : Exception
{
    public InvalidTripTransitionException(TripStatus from, TripStatus to)
        : base($"Cannot transition trip from {from} to {to}.") { }
}

This is the entire state machine. A dictionary. When you add a new state or a new transition, you change one line. When someone tries an illegal transition, they get an exception immediately — not a silent data corruption.

One design note: Validate throws an exception, which means under high concurrent load the stack trace generation has a small but measurable cost. If illegal transitions are genuinely expected at volume (e.g., a retry storm hitting an already-cancelled trip), consider replacing the exception with a Result type — the same pattern used in the service layer below. The IsAllowed method already exists for exactly that check without allocating an exception. For most systems the exception path is fine; for very high-throughput services it's worth considering.

Step 3: The Trip Aggregate

The Trip class owns the state transitions and raises domain events. Nothing outside it can change its status directly. The private set on every property isn't just about encapsulation — it's a guarantee of invariant consistency. DriverId is only ever set during AssignDriver, FareAmount only during Complete, CompletedAt only when the trip actually finishes. There is no way to create a Trip in a state where Status is Completed but FareAmount is null, or DriverId is set on a Cancelled trip. The class makes those combinations structurally impossible:

public class Trip
{
    public Guid Id { get; private set; }
    public string RiderId { get; private set; }
    public string? DriverId { get; private set; }
    public TripStatus Status { get; private set; }
    public decimal? FareAmount { get; private set; }
    public DateTimeOffset RequestedAt { get; private set; }
    public DateTimeOffset? CompletedAt { get; private set; }
    public byte[] RowVersion { get; private set; } = [];

    private readonly List<TripEvent> _events = [];
    public IReadOnlyList<TripEvent> Events => _events.AsReadOnly();

    private Trip() { }

    public static Trip Create(Guid riderId)
    {
        return new Trip
        {
            Id = Guid.NewGuid(),
            RiderId = riderId.ToString(),
            Status = TripStatus.Requested,
            RequestedAt = DateTimeOffset.UtcNow
        };
    }

    public void AssignDriver(string driverId)
    {
        TripTransitions.Validate(Status, TripStatus.DriverAssigned);
        DriverId = driverId;
        Status = TripStatus.DriverAssigned;
        _events.Add(new DriverAssigned(Id, driverId));
    }

    public void DriverEnRoute()
    {
        TripTransitions.Validate(Status, TripStatus.DriverEnRoute);
        Status = TripStatus.DriverEnRoute;
    }

    public void Start()
    {
        TripTransitions.Validate(Status, TripStatus.InProgress);
        Status = TripStatus.InProgress;
        _events.Add(new TripStarted(Id));
    }

    public void Complete(decimal fareAmount)
    {
        TripTransitions.Validate(Status, TripStatus.Completed);
        Status = TripStatus.Completed;
        FareAmount = fareAmount;
        CompletedAt = DateTimeOffset.UtcNow;
        _events.Add(new TripCompleted(Id, fareAmount));
    }

    public void FailPayment(string reason)
    {
        TripTransitions.Validate(Status, TripStatus.PaymentFailed);
        Status = TripStatus.PaymentFailed;
        _events.Add(new PaymentFailed(Id, reason));
    }

    public void Cancel(string reason, string cancelledBy)
    {
        TripTransitions.Validate(Status, TripStatus.Cancelled);
        Status = TripStatus.Cancelled;
        _events.Add(new TripCancelled(Id, reason, cancelledBy));
    }
}

The RowVersion property is not just metadata — it's the key to preventing the race condition we opened with. We'll use it in a moment.

Step 4: Persisting State with EF Core

The trip needs a table. The RowVersion column is what makes concurrent updates safe:

public class TripConfiguration : IEntityTypeConfiguration<Trip>
{
    public void Configure(EntityTypeBuilder<Trip> builder)
    {
        builder.HasKey(t => t.Id);

        builder.Property(t => t.Status)
            .HasConversion<string>();

        builder.Property(t => t.RowVersion)
            .IsRowVersion();

        builder.Property(t => t.RiderId).IsRequired();
        builder.Property(t => t.FareAmount).HasColumnType("decimal(10,2)");
    }
}

IsRowVersion() tells EF Core to include this column in every UPDATE statement's WHERE clause. SQL Server uses rowversion; PostgreSQL uses xmin. Either way, if the row has been modified since you read it, the update will affect 0 rows and EF Core throws DbUpdateConcurrencyException.

For the domain events, add a separate table that acts as an audit trail:

public class TripEventLog
{
    public long Id { get; set; }
    public Guid TripId { get; set; }
    public string EventType { get; set; } = string.Empty;
    public string Payload { get; set; } = string.Empty;
    public DateTimeOffset OccurredAt { get; set; }
}

Step 5: Handling the Race Condition

This is where most implementations fall apart. Two requests arrive at the same millisecond — one from the rider cancelling, one from the assignment service assigning a driver. Both read the trip as Requested. Both attempt a transition. Without protection, both succeed, leaving the trip in an undefined state.

The service that assigns a driver:

public class TripService
{
    private readonly AppDbContext _db;
    private readonly IEventBus _events;

    public TripService(AppDbContext db, IEventBus events)
    {
        _db = db;
        _events = events;
    }

    public async Task<Result> AssignDriverAsync(
        Guid tripId,
        string driverId,
        CancellationToken ct = default)
    {
        const int maxRetries = 3;

        for (var attempt = 0; attempt < maxRetries; attempt++)
        {
            var trip = await _db.Trips.FindAsync([tripId], ct);

            if (trip is null)
                return Result.Fail("Trip not found.");

            if (trip.Status == TripStatus.Cancelled)
                return Result.Fail("Trip was already cancelled.");

            try
            {
                trip.AssignDriver(driverId);
                await _db.SaveChangesAsync(ct);

                // Publish domain events after successful save
                foreach (var evt in trip.Events)
                    await _events.PublishAsync(evt, ct);

                return Result.Ok();
            }
            catch (InvalidTripTransitionException ex)
            {
                return Result.Fail(ex.Message);
            }
            catch (DbUpdateConcurrencyException)
            {
                // Another process modified this trip between our read and write.
                // Refresh and retry — the state we read is stale.
                if (attempt == maxRetries - 1)
                    return Result.Fail("Trip is being modified concurrently. Please retry.");

                await Task.Delay(TimeSpan.FromMilliseconds(50 * (attempt + 1)), ct);
            }
        }

        return Result.Fail("Failed to assign driver after retries.");
    }
}

The retry loop is important. DbUpdateConcurrencyException means someone else got there first — the trip was modified between when we read it and when we tried to write it. We don't give up: we reload the current state and retry, up to three times. If the trip was cancelled while we were retrying, the InvalidTripTransitionException will stop us cleanly.

This pattern — read, modify, save, catch concurrency exception, retry — is optimistic concurrency. It assumes conflicts are rare and handles them when they happen, rather than locking the row for the duration of the operation.

Step 6: Domain Events Driving Side Effects

When a trip completes, several things need to happen: charge the payment method, send the receipt, update the driver's stats, release the driver back to the available pool. None of these belong in TripService. They're separate concerns, triggered by the TripCompleted event.

public class TripCompletedHandler
{
    private readonly IPaymentService _payments;
    private readonly INotificationService _notifications;
    private readonly IDriverAvailabilityService _availability;

    public async Task HandleAsync(TripCompleted evt, CancellationToken ct = default)
    {
        // Each of these is independent — one failure shouldn't block the others
        var paymentResult = await _payments.ChargeAsync(evt.TripId, evt.FareAmount, ct);

        if (!paymentResult.Success)
        {
            // Publish PaymentFailed — TripService will handle the state transition
            await PublishPaymentFailedAsync(evt.TripId, paymentResult.Error, ct);
            return;
        }

        await Task.WhenAll(
            _notifications.SendReceiptAsync(evt.TripId, evt.FareAmount, ct),
            _availability.ReleaseDriverAsync(evt.TripId, ct));
    }
}

The TripCompletedHandler doesn't know how trips work. It knows what to do when one completes. This separation means you can add a new reaction to TripCompleted — a loyalty points award, a surge pricing adjustment, a data pipeline event — without touching any trip logic.

The gap you should know about. Dispatching events after SaveChangesAsync is the right order — you never want to publish an event for a write that didn't commit. But it leaves a window: if the process crashes after the database write succeeds but before IEventBus.PublishAsync completes, the trip is Completed in the database and the payment event was never dispatched. The rider won't be charged.

For 100% reliability, use the Outbox Pattern: instead of publishing to the event bus directly, save the event payload to an OutboxMessages table in the same database transaction as the state change. A background worker then reads and dispatches those events, marking each as processed. If the process crashes mid-dispatch, the worker retries. The event is never lost because it was committed atomically with the state.

The implementation in this article is correct for most systems. If missed payments or missed notifications are genuinely unacceptable, the Outbox Pattern is the next step.

Step 7: Handling Timeouts

A Requested trip that doesn't get a driver within 60 seconds should be automatically cancelled. This is a background concern, not part of the trip's own logic:

public class TripTimeoutService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<TripTimeoutService> _logger;
    private static readonly TimeSpan CheckInterval = TimeSpan.FromSeconds(15);
    private static readonly TimeSpan RequestTimeout = TimeSpan.FromSeconds(60);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(CheckInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var events = scope.ServiceProvider.GetRequiredService<IEventBus>();

            var cutoff = DateTimeOffset.UtcNow - RequestTimeout;

            var timedOut = await db.Trips
                .Where(t => t.Status == TripStatus.Requested && t.RequestedAt < cutoff)
                .ToListAsync(stoppingToken);

            foreach (var trip in timedOut)
            {
                try
                {
                    trip.Cancel("No driver found within timeout.", "system");
                    await db.SaveChangesAsync(stoppingToken);

                    foreach (var evt in trip.Events)
                        await events.PublishAsync(evt, stoppingToken);
                }
                catch (DbUpdateConcurrencyException)
                {
                    // A driver was assigned at the same moment we tried to cancel.
                    // The driver won — that's the right outcome. Skip.
                    _logger.LogInformation("Trip {TripId} was assigned during timeout window, skipping cancel.", trip.Id);
                }
                catch (InvalidTripTransitionException)
                {
                    // Trip was already transitioned by another process. Skip.
                }
            }
        }
    }
}

Note how DbUpdateConcurrencyException here is not an error — it means the trip was assigned just as we were about to cancel it. The driver won the race. That's exactly the right outcome, and we log it and move on.

Step 8: Wiring It Up

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));

builder.Services.AddScoped<TripService>();
builder.Services.AddHostedService<TripTimeoutService>();

var app = builder.Build();

// Request a trip
app.MapPost("/trips", async (
    RequestTripDto request,
    TripService service,
    AppDbContext db,
    CancellationToken ct) =>
{
    var trip = Trip.Create(request.RiderId);
    db.Trips.Add(trip);
    await db.SaveChangesAsync(ct);
    return Results.Created($"/trips/{trip.Id}", new { tripId = trip.Id });
});

// Assign a driver
app.MapPost("/trips/{tripId:guid}/assign", async (
    Guid tripId,
    AssignDriverDto request,
    TripService service,
    CancellationToken ct) =>
{
    var result = await service.AssignDriverAsync(tripId, request.DriverId, ct);
    return result.Success ? Results.Ok() : Results.Conflict(new { error = result.Error });
});

// Start the trip
app.MapPost("/trips/{tripId:guid}/start", async (
    Guid tripId,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();

    try
    {
        trip.Start();
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events)
            await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex)
    {
        return Results.Conflict(new { error = ex.Message });
    }
});

// Complete the trip
app.MapPost("/trips/{tripId:guid}/complete", async (
    Guid tripId,
    CompleteTripDto request,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();

    try
    {
        trip.Complete(request.FareAmount);
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events)
            await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex)
    {
        return Results.Conflict(new { error = ex.Message });
    }
});

app.Run();

What Uber Actually Does

Uber's trip state machine is significantly more complex. They have intermediate states for driver arrival confirmation, route deviation handling, stop requests, and partial ride cancellations. Their concurrency is handled not with database row versions but with distributed locks and event sourcing — every state change is an immutable event appended to a stream, and the current state is derived by replaying those events.

Their timeout system is part of a broader orchestration layer (they've written publicly about using Cadence/Temporal for this) that handles retries, compensating transactions, and saga-style distributed coordination.

What we've built is the correct structural shape: explicit states, validated transitions, optimistic concurrency, domain events as the integration mechanism. At Uber's scale, the same concepts apply with more moving parts and higher fault-tolerance requirements.

Common Mistakes

Mistake 1: Status as a raw string with no transition enforcement

// ❌ Nothing prevents any value being set
public class Trip
{
    public string Status { get; set; } = "Requested";
}

// Anywhere in the codebase...
trip.Status = "Completed"; // No validation. No events. Silent corruption.

If the status field is publicly settable, you don't have a state machine — you have a string column. Any code anywhere can put the trip into any state, bypassing every rule you thought you had.

Mistake 2: Checking status in the service instead of the aggregate

// ❌ Business rule leaking out of the domain
public async Task AssignDriverAsync(Guid tripId, string driverId)
{
    var trip = await _db.Trips.FindAsync(tripId);

    if (trip.Status != "Requested") // magic string
        throw new Exception("Cannot assign driver");

    trip.DriverId = driverId;
    trip.Status = "DriverAssigned"; // still a raw string
}

When transition logic lives in the service, it will be duplicated. The second endpoint that assigns a driver will either copy the check or forget it. The aggregate owns the rules.

Mistake 3: Dispatching events before SaveChangesAsync succeeds

// ❌ Event published before state is confirmed committed
await _events.PublishAsync(new TripCompleted(trip.Id, fare));
await db.SaveChangesAsync(); // if this fails, the event is already out

If the database write fails, the event is already in the bus. A payment handler somewhere has received TripCompleted for a trip the database doesn't recognise as completed. The rider gets charged for a trip that didn't finish.

Always save state first, publish after. But be honest with yourself: dispatching after SaveChangesAsync still leaves a gap — if the process dies after the DB write but before the publish, the event is lost. That gap is acceptable in many systems. When it isn't — when a missed payment or a missed notification is genuinely unacceptable — the fix is the Outbox Pattern described in Step 6.

Mistake 4: Ignoring DbUpdateConcurrencyException

// ❌ The exception propagates as a 500 error
trip.AssignDriver(driverId);
await db.SaveChangesAsync(); // throws DbUpdateConcurrencyException under load

Under load, concurrent modifications are expected, not exceptional. Handle them explicitly: retry with fresh state, or return a meaningful conflict response to the caller.

Mistake 5: No timeout for stuck trips

A trip stuck in Requested forever because no driver accepted is invisible without active monitoring. Add the background service. Add an alert if the timeout queue grows beyond a threshold.

Conclusion

A trip's lifecycle is a contract. It makes promises: a Completed trip was once InProgress, a Cancelled trip will never become Completed, a driver will only be assigned once. Enforcing those promises at the code level — through the aggregate's transition rules, the RowVersion concurrency token, and domain events as the integration point — is what turns a status column into a proper state machine.

The race condition from the opening isn't patched by adding more checks. It's solved structurally: the database rejects the second write at the data layer, and the retry logic handles it gracefully. No locks. No distributed coordination. Just a WHERE RowVersion = @expected clause doing its job.

In the next article we'll bring everything together: the full Uber-like system design, combining the location pipeline from Part 1 and the trip lifecycle from this article into a complete architecture with driver matching, surge pricing, and the full request flow.

Part 2 of the Uber-like System Design in .NET series.

Full source code: github.com/AdrianBailador/trip-state-machine-dotnet

Questions or suggestions? Open an issue on GitHub.

Real-time Driver Location Tracking in .NET: Redis GEO, State Buffer and SignalR

Adrián Bailador — Mon, 11 May 2026 19:51:51 +0000

Every four seconds, every active Uber driver sends their GPS coordinates to a server.

At peak, that's roughly 5 million updates per minute — before you even count the riders watching their driver move on a map in real time. The location pipeline is the heartbeat of the entire platform. If it slows down, drivers and riders fall out of sync. If it falls over, the app is effectively useless.

Building something like this in .NET is a good exercise in knowing when not to reach for a database. Location data is high-frequency, short-lived, and geospatial. A relational database would collapse under the write load. What you need is Redis.

This is the first article in a mini-series on designing an Uber-like system in .NET. Here we build the location tracking pipeline. In the next two articles we'll cover the trip state machine and the full system design.

The Problem in Concrete Terms

Before writing any code, it helps to make the numbers real:

5 million active drivers at peak, each sending a GPS update every 4 seconds
~1.25 million writes per second at the Redis layer
Riders watching a moving dot on a map — updates should feel instant (under 1 second latency)
Driver matching — when a rider requests a trip, the system needs to find available drivers within a radius in milliseconds

A naive implementation stores each update in a SQL table. After two minutes of load it becomes a 150-million-row table with a write queue backed up to the horizon. That's not the bottleneck you want to debug at 11pm.

The architecture we'll build instead:

Step 1: Modelling the Location Update

Keep it simple. A location update is a thin message:

public record LocationUpdate(
    string DriverId,
    double Latitude,
    double Longitude,
    DateTimeOffset Timestamp);

The driver sends this every four seconds. We don't store history here — that's a separate concern for analytics. What we store is current position.

Step 2: The Location State Buffer

The first instinct here is to use a queue — Channel<T>, a message bus, something that holds updates until they can be processed. That instinct is wrong for this problem.

A queue implies every item matters. In location tracking, only the latest position per driver matters. If a driver sends 10 updates while the processor is busy, 9 of them are noise — you only need the most recent. A queue retains all 10 and processes them in order; by the time it reaches update 10 it's processing history, not the present.

The right model is mutable state per driver. A ConcurrentDictionary<string, LocationUpdate> where each write simply overwrites the previous value:

public class LocationStateBuffer
{
    private readonly ConcurrentDictionary<string, LocationUpdate> _latest = new();
    private readonly ConcurrentDictionary<string, byte> _dirty = new();

    public void Update(LocationUpdate update)
    {
        _latest[update.DriverId] = update;
        _dirty[update.DriverId] = 0;
    }

    public IReadOnlyList<LocationUpdate> TakeSnapshot()
    {
        var snapshot = new List<LocationUpdate>();
        foreach (var driverId in _dirty.Keys.ToArray())
        {
            if (_dirty.TryRemove(driverId, out _) && _latest.TryGetValue(driverId, out var update))
                snapshot.Add(update);
        }
        return snapshot;
    }
}

The _dirty set tracks which drivers have sent updates since the last flush. TakeSnapshot returns only those drivers — if a driver hasn't moved, there's nothing to write to Redis. This means the flush is proportional to activity, not total driver count.

The endpoint writes are O(1) and never block regardless of what the background processor is doing:

app.MapPost("/drivers/{driverId}/location", (
    string driverId,
    LocationUpdateRequest request,
    LocationStateBuffer buffer) =>
{
    buffer.Update(new LocationUpdate(driverId, request.Latitude, request.Longitude, DateTimeOffset.UtcNow));
    return Results.Accepted();
});

No overflow. No stale updates blocking newer ones. Natural rate limiting built in — if a driver sends 10 updates between flushes, only 1 Redis write happens.

Step 3: Redis GEO

Redis has a native geospatial data type backed by sorted sets. The key commands:

GEOADD key longitude latitude member — store or update a position
GEOSEARCH key FROMMEMBER member BYRADIUS radius unit — find all members within a radius
GEOPOS key member — get the current position of a member

In StackExchange.Redis:

public class RedisLocationStore
{
    private readonly IDatabase _db;
    private const string DriversKey = "drivers:locations";

    public RedisLocationStore(IConnectionMultiplexer redis)
    {
        _db = redis.GetDatabase();
    }

    public async Task UpdateAsync(LocationUpdate update)
    {
        await _db.GeoAddAsync(DriversKey, new GeoEntry(
            longitude: update.Longitude,
            latitude: update.Latitude,
            member: update.DriverId));
    }

    public async Task<IEnumerable<NearbyDriver>> FindNearbyAsync(
        double latitude,
        double longitude,
        double radiusKm)
    {
        var results = await _db.GeoSearchAsync(
            DriversKey,
            longitude, latitude,
            new GeoSearchCircle(radiusKm, GeoUnit.Kilometers),
            options: GeoRadiusOptions.WithDistance | GeoRadiusOptions.WithCoordinates);

        return results.Select(r => new NearbyDriver(
            DriverId: r.Member.ToString(),
            DistanceKm: r.Distance ?? 0,
            Latitude: r.Position?.Latitude ?? 0,
            Longitude: r.Position?.Longitude ?? 0));
    }
}

public record NearbyDriver(string DriverId, double DistanceKm, double Latitude, double Longitude);

GEOSEARCH returns drivers sorted by distance and is fast enough to query on every rider request — it runs in O(N+log(M)) where N is the result set size, not the total driver count.

One important note: Redis GEO stores positions as compressed floats, so there's a small precision loss (~0.6mm error). For navigation that's irrelevant. What matters is that a GEOSEARCH returning the 10 nearest drivers within 5km finishes in under a millisecond even with millions of stored positions.

Step 4: The Background Processor

The BackgroundService flushes the state buffer to Redis every 500ms using PeriodicTimer:

public class LocationProcessorService : BackgroundService
{
    private readonly LocationStateBuffer _buffer;
    private readonly ILocationStore _store;
    private readonly IHubContext<DriverLocationHub> _hub;
    private readonly ILogger<LocationProcessorService> _logger;

    private static readonly TimeSpan FlushInterval = TimeSpan.FromMilliseconds(500);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(FlushInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            var updates = _buffer.TakeSnapshot();
            if (updates.Count == 0) continue;

            foreach (var update in updates)
            {
                try
                {
                    await _store.UpdateAsync(update);

                    await _hub.Clients
                        .Group($"watching:{update.DriverId}")
                        .SendAsync("DriverMoved", new
                        {
                            update.DriverId,
                            update.Latitude,
                            update.Longitude,
                            update.Timestamp
                        }, stoppingToken);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Failed flushing location for driver {DriverId}", update.DriverId);
                }
            }
        }
    }
}

PeriodicTimer is the idiomatic .NET 6+ way to run periodic work in a hosted service — it doesn't drift (each tick is measured from the previous tick's start, not end) and cancellation is handled automatically.

Each flush only touches drivers that sent updates since the last tick. If no driver moved, TakeSnapshot returns an empty list and the loop skips immediately. The Redis write and SignalR push are independent — a failed push doesn't block the Redis update, and a single missed UI notification is invisible to the rider.

Step 5: SignalR Hub

The rider opens a WebSocket connection when they're watching a trip. They join a group named after the driver they're tracking:

public class DriverLocationHub : Hub
{
    public async Task WatchDriver(string driverId)
    {
        // Leave any previous group first
        var previousDriver = Context.Items["watchingDriver"] as string;
        if (previousDriver is not null)
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"watching:{previousDriver}");

        await Groups.AddToGroupAsync(Context.ConnectionId, $"watching:{driverId}");
        Context.Items["watchingDriver"] = driverId;
    }

    public async Task StopWatching()
    {
        var driverId = Context.Items["watchingDriver"] as string;
        if (driverId is not null)
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"watching:{driverId}");
    }
}

On the client side (minimal TypeScript):

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/driver-location")
    .withAutomaticReconnect()
    .build();

connection.on("DriverMoved", (data) => {
    updateDriverMarker(data.driverId, data.latitude, data.longitude);
});

await connection.start();
await connection.invoke("WatchDriver", driverId);

The withAutomaticReconnect() is critical: mobile connections drop constantly. Without it, a brief network hiccup leaves the rider with a frozen map and no indication anything is wrong.

Step 6: Wiring It Up

var builder = WebApplication.CreateBuilder(args);

// Redis
var redis = await ConnectionMultiplexer.ConnectAsync(builder.Configuration["Redis:ConnectionString"]!);
builder.Services.AddSingleton<IConnectionMultiplexer>(redis);
builder.Services.AddSingleton<ILocationStore, RedisLocationStore>();

// Location state buffer — mutable per-driver state, flushed periodically
builder.Services.AddSingleton<LocationStateBuffer>();

// SignalR — add .AddStackExchangeRedis(...) when scaling horizontally
builder.Services.AddSignalR();

// Background processor
builder.Services.AddHostedService<LocationProcessorService>();

var app = builder.Build();

app.MapPost("/drivers/{driverId}/location", (
    string driverId,
    LocationUpdateRequest request,
    LocationStateBuffer buffer) =>
{
    buffer.Update(new LocationUpdate(driverId, request.Latitude, request.Longitude, DateTimeOffset.UtcNow));
    return Results.Accepted();
});

app.MapHub<DriverLocationHub>("/hubs/driver-location");

app.MapGet("/drivers/nearby", async (
    double lat, double lon, double radius,
    ILocationStore store) =>
{
    var drivers = await store.FindNearbyAsync(lat, lon, radius);
    return Results.Ok(drivers);
});

app.Run();

Handling Scale

The single-instance version above works fine up to a few thousand concurrent drivers. When you need to scale horizontally, two things change:

SignalR backplane. By default SignalR only pushes to connections on the same server instance. With multiple instances, a driver update arriving at instance A won't reach a rider connected to instance B. The fix is a Redis backplane:

builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration["Redis:ConnectionString"]!);

One line, and SignalR uses Redis pub/sub to fan out messages across all instances.

The state buffer is per-instance. LocationStateBuffer is in-memory — it doesn't survive restarts and doesn't span instances. For this use case that's fine: drivers resend their position every 4 seconds, so after a restart the buffer refills in seconds and no user-visible impact occurs.

What Uber Actually Does

Uber's real architecture is more complex — they use a custom geospatial sharding system called H3 (hexagonal hierarchical geospatial indexing), partition driver updates by city and region, and process location data through a streaming pipeline (Apache Kafka → Flink). Their dispatch system is a separate service with its own matching algorithm.

What we've built captures the essential shape: a fast write path that doesn't block on persistence, a Redis geospatial index that answers "who's nearby?" in milliseconds, and a WebSocket channel that keeps the rider map live.

The differences are scale and operational complexity, not architectural direction. The building blocks are the same.

Common Mistakes

Mistake 1: Writing location directly to SQL

// ❌ Every GPS update hits the database
await _dbContext.DriverLocations.AddAsync(new DriverLocation
{
    DriverId = update.DriverId,
    Latitude = update.Latitude,
    Longitude = update.Longitude,
    Timestamp = update.Timestamp
});
await _dbContext.SaveChangesAsync();

This works in development and collapses in production. Location is ephemeral data — you only need the current position, not every position. If you need history for analytics, write to a time-series store or an append-only stream asynchronously, not inline in the request path.

Mistake 2: Blocking the HTTP thread on Redis

// ❌ Driver request blocks until Redis confirms the write
await _redis.GeoAddAsync(DriversKey, new GeoEntry(lon, lat, driverId));
return Results.Ok();

Redis is fast, but adding network I/O to every driver request serialises your throughput. The state buffer decouples the HTTP response time from the Redis write time — the driver gets 202 in microseconds and Redis catches up on the next flush tick.

Mistake 3: Using a queue when you need mutable state

// ❌ Channel queues every update — processes stale positions
Channel.CreateBounded<LocationUpdate>(new BoundedChannelOptions(10_000)
{
    FullMode = BoundedChannelFullMode.DropOldest
});

A queue with DropOldest drops unpredictably under load and processes intermediate positions that are already outdated by the time the consumer reaches them. Location tracking is a state problem, not a message-passing problem. Model it as state.

Mistake 4: One SignalR group per trip instead of per driver

// ❌ Naming the group after the trip
await Groups.AddToGroupAsync(connectionId, $"trip:{tripId}");

Trip IDs change across retries and reassignments. Driver IDs don't. Name the group after the driver and the rider joins/leaves as the assignment changes.

Mistake 5: Forgetting the backplane when scaling SignalR

// ❌ Multiple instances, no backplane
// Driver updates arrive at instance A, rider is connected to instance B
// → rider map freezes
builder.Services.AddSignalR(); // missing .AddStackExchangeRedis(...)

This is the most common production bug in SignalR deployments. Everything works on a single instance in development and silently breaks when you scale to two.

Conclusion

The location tracking pipeline is a good example of matching the abstraction to the problem. GPS updates are high-frequency, short-lived, and geospatial — so we model them as mutable state (not a queue), index them in Redis GEO (not a relational table), and push changes in real time via SignalR (not polling).

None of this required a heavy framework or a distributed systems PhD. It's a ConcurrentDictionary, a Redis sorted set, and a WebSocket group — standard .NET primitives composed to handle a genuinely hard scale problem.

In the next article we'll build the trip state machine: how a ride moves from Requested to Completed, how to handle concurrent state transitions, and how to persist the lifecycle with EF Core.

Part 1 of the Uber-like System Design in .NET series.

Full source code: github.com/AdrianBailador/realtime-driver-location-dotnet

Questions or suggestions? Open an issue on GitHub.

CQRS Without MediatR: Hand-Rolled Command and Query Handlers in .NET

Adrián Bailador — Mon, 04 May 2026 09:56:45 +0000

For years, opening a new .NET project meant the same opening ritual: dotnet add package MediatR. The library became so synonymous with CQRS in the .NET community that many developers couldn't tell where the pattern ended and the package began.

Then MediatR moved to a commercial license. Suddenly, every team that had built their architecture around it was asking the same question: do we actually need this?

This isn't a criticism of MediatR or of Jimmy Bogard — the library shaped how a generation of .NET developers think about handlers, pipelines, and clean separation of concerns, and the community owes him a real debt. The licensing change is just an opportunity to look at what's underneath, and to notice how little of it actually needs to be a library at all.

Most teams don't need MediatR. CQRS is a pattern, not a library — and the .NET DI container has everything you need to implement it cleanly. This article shows how.

What CQRS Actually Is

Command Query Responsibility Segregation has two parts:

Commands change state. They have side effects. They might return a result, but their primary purpose is to modify the system.
Queries read state. They have no side effects. They return data and nothing else.

That's it. Everything else — the dispatcher, the handlers, the pipeline behaviors — is implementation detail. None of it requires a library.

The reason MediatR became the default is convenience: it gave you handler discovery, a dispatcher, and a behavior pipeline in three lines of Program.cs. But all of those things are about ten lines of code each, and writing them yourself gives you something MediatR never could: full control over the abstraction.

The Minimal Abstraction

Start with two interface families. One for commands, one for queries.

// Marker interfaces — they exist only for the type system
public interface ICommand { }
public interface ICommand<TResult> { }

public interface IQuery<TResult> { }

// Handlers
public interface ICommandHandler<TCommand>
    where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken ct = default);
}

public interface ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default);
}

public interface IQueryHandler<TQuery, TResult>
    where TQuery : IQuery<TResult>
{
    Task<TResult> HandleAsync(TQuery query, CancellationToken ct = default);
}

Five interfaces. No external dependencies. No reflection magic. The compiler enforces the relationship between commands, queries, and their handlers.

A note on the empty ICommand and IQuery interfaces: some developers consider marker interfaces an anti-pattern, and in many cases they're right — an attribute or a naming convention is usually enough. Here, they earn their keep. They give the assembly scanner an unambiguous anchor (AssignableTo(typeof(ICommand<>)) is impossible without them), and they let the dispatcher constrain its generic parameters so misuse is a compile error instead of a runtime one. They're not decoration — they're the type-system contract that makes everything else type-safe.

A concrete command and handler look like this:

public record CreateOrder(string CustomerEmail, List<OrderLine> Lines) : ICommand<OrderId>;

public class CreateOrderHandler : ICommandHandler<CreateOrder, OrderId>
{
    private readonly IOrderRepository _orders;
    private readonly IEventBus _events;

    public CreateOrderHandler(IOrderRepository orders, IEventBus events)
    {
        _orders = orders;
        _events = events;
    }

    public async Task<OrderId> HandleAsync(CreateOrder command, CancellationToken ct = default)
    {
        var order = Order.Create(command.CustomerEmail, command.Lines);

        await _orders.SaveAsync(order, ct);
        await _events.PublishAsync(new OrderCreated(order.Id), ct);

        return order.Id;
    }
}

And a query:

public record GetOrderById(Guid OrderId) : IQuery<OrderDto?>;

public class GetOrderByIdHandler : IQueryHandler<GetOrderById, OrderDto?>
{
    private readonly IOrderReadModel _reads;

    public GetOrderByIdHandler(IOrderReadModel reads)
    {
        _reads = reads;
    }

    public Task<OrderDto?> HandleAsync(GetOrderById query, CancellationToken ct = default)
        => _reads.GetByIdAsync(query.OrderId, ct);
}

That's the entire pattern. Everything from here on is plumbing.

The Dispatcher

The dispatcher resolves the handler for a given command or query and invokes it. It exists so callers don't have to inject every handler they want to use — they inject one dispatcher and send messages through it.

public interface ICommandDispatcher
{
    Task SendAsync(ICommand command, CancellationToken ct = default);
    Task<TResult> SendAsync<TResult>(ICommand<TResult> command, CancellationToken ct = default);
}

public interface IQueryDispatcher
{
    Task<TResult> SendAsync<TResult>(IQuery<TResult> query, CancellationToken ct = default);
}

The implementation is short. It uses the runtime type of the message to find the right handler in the DI container.

public class CommandDispatcher : ICommandDispatcher
{
    private readonly IServiceProvider _provider;

    public CommandDispatcher(IServiceProvider provider)
    {
        _provider = provider;
    }

    public Task SendAsync(ICommand command, CancellationToken ct = default)
    {
        var handlerType = typeof(ICommandHandler<>).MakeGenericType(command.GetType());
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)command, ct);
    }

    public Task<TResult> SendAsync<TResult>(ICommand<TResult> command, CancellationToken ct = default)
    {
        var handlerType = typeof(ICommandHandler<,>)
            .MakeGenericType(command.GetType(), typeof(TResult));
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)command, ct);
    }
}

public class QueryDispatcher : IQueryDispatcher
{
    private readonly IServiceProvider _provider;

    public QueryDispatcher(IServiceProvider provider)
    {
        _provider = provider;
    }

    public Task<TResult> SendAsync<TResult>(IQuery<TResult> query, CancellationToken ct = default)
    {
        var handlerType = typeof(IQueryHandler<,>)
            .MakeGenericType(query.GetType(), typeof(TResult));
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)query, ct);
    }
}

The dynamic calls are the trick. Without them you'd need reflection (MethodInfo.Invoke) and the cost is similar — but dynamic keeps the code readable and the call site cached after the first invocation.

If you want to avoid dynamic entirely, the alternative is one extra method per generic arity using MethodInfo.Invoke. The performance difference is negligible for everything except hot loops, and CQRS handlers are not a hot loop. From .NET 8 onwards, the JIT compiler is remarkably good at devirtualising and inlining generic dispatch — the "hand-rolled" version performs identically to MediatR for the vast majority of applications, which is one more reason not to be intimidated by writing this yourself.

One subtlety worth flagging in the dispatcher code: command.GetType() returns the runtime type of the command instance. If you build a command hierarchy where a derived class is sent through the pipeline but only a handler for the base type is registered, the resolution will fail at runtime — the container looks for a handler of the concrete type. In practice this is rarely a problem because commands are usually sealed record types, but it's worth knowing if you ever consider sharing handlers across command variants.

Wiring Everything Up

You need three things in Program.cs:

Register the dispatchers
Register all handlers
(Optionally) register pipeline behaviors

Manual registration works for small projects:

builder.Services.AddScoped<ICommandDispatcher, CommandDispatcher>();
builder.Services.AddScoped<IQueryDispatcher, QueryDispatcher>();

builder.Services.AddScoped<ICommandHandler<CreateOrder, OrderId>, CreateOrderHandler>();
builder.Services.AddScoped<IQueryHandler<GetOrderById, OrderDto?>, GetOrderByIdHandler>();
// ...one line per handler

This works, but for a real codebase you want auto-registration. The cleanest way is Scrutor, which adds assembly scanning to the standard DI container.

builder.Services.AddScoped<ICommandDispatcher, CommandDispatcher>();
builder.Services.AddScoped<IQueryDispatcher, QueryDispatcher>();

builder.Services.Scan(scan => scan
    .FromAssemblyOf<CreateOrder>()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<,>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(IQueryHandler<,>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime());

Three blocks of scanning, and every handler in your project is registered. Adding a new handler means writing the class — no Program.cs change required.

If you don't want a Scrutor dependency, you can scan manually with reflection:

public static IServiceCollection AddCqrsHandlers(this IServiceCollection services, Assembly assembly)
{
    var handlerInterfaces = new[]
    {
        typeof(ICommandHandler<>),
        typeof(ICommandHandler<,>),
        typeof(IQueryHandler<,>)
    };

    var handlerTypes = assembly.GetTypes()
        .Where(t => !t.IsAbstract && !t.IsInterface)
        .SelectMany(t => t.GetInterfaces()
            .Where(i => i.IsGenericType && handlerInterfaces.Contains(i.GetGenericTypeDefinition()))
            .Select(i => new { Implementation = t, Service = i }));

    foreach (var handler in handlerTypes)
        services.AddScoped(handler.Service, handler.Implementation);

    return services;
}

Call it once: builder.Services.AddCqrsHandlers(typeof(CreateOrder).Assembly);. About thirty lines of code that replaces an entire dependency.

Pipeline Behaviors Without Magic

This is where most people assume they need MediatR. They don't. The decorator pattern + Scrutor gives you the same thing with no surprises.

Suppose you want every command to be logged and validated. Define behaviors as decorators of ICommandHandler<,>:

public class LoggingCommandHandler<TCommand, TResult> : ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    private readonly ICommandHandler<TCommand, TResult> _inner;
    private readonly ILogger<TCommand> _logger;

    public LoggingCommandHandler(ICommandHandler<TCommand, TResult> inner, ILogger<TCommand> logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default)
    {
        var sw = Stopwatch.StartNew();
        _logger.LogInformation("Handling {Command}", typeof(TCommand).Name);

        try
        {
            var result = await _inner.HandleAsync(command, ct);
            _logger.LogInformation("Handled {Command} in {Elapsed}ms", typeof(TCommand).Name, sw.ElapsedMilliseconds);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed handling {Command} after {Elapsed}ms", typeof(TCommand).Name, sw.ElapsedMilliseconds);
            throw;
        }
    }
}

public class ValidationCommandHandler<TCommand, TResult> : ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    private readonly ICommandHandler<TCommand, TResult> _inner;
    private readonly IEnumerable<IValidator<TCommand>> _validators;

    public ValidationCommandHandler(
        ICommandHandler<TCommand, TResult> inner,
        IEnumerable<IValidator<TCommand>> validators)
    {
        _inner = inner;
        _validators = validators;
    }

    public async Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default)
    {
        var failures = _validators
            .Select(v => v.Validate(command))
            .SelectMany(r => r.Errors)
            .Where(e => e is not null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await _inner.HandleAsync(command, ct);
    }
}

Wire them with Scrutor.Decorate:

builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(ValidationCommandHandler<,>));
builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(LoggingCommandHandler<,>));

Order matters: the last Decorate call is the outermost layer. With the configuration above, every command flows through Logging → Validation → actual handler.

The benefit over MediatR's IPipelineBehavior is that you can see exactly what's happening. There's no next() delegate hiding behind a generic type — just plain decorators with their dependencies visible at the constructor.

Skipping the Dispatcher in Minimal APIs

Here's a question worth asking: do you even need the dispatcher?

If you're using Minimal APIs, the endpoint handler is already a function with access to DI. You can inject the command handler directly:

app.MapPost("/orders", async (
    CreateOrder command,
    ICommandHandler<CreateOrder, OrderId> handler,
    CancellationToken ct) =>
{
    var orderId = await handler.HandleAsync(command, ct);
    return Results.Created($"/orders/{orderId.Value}", new { orderId });
});

app.MapGet("/orders/{id:guid}", async (
    Guid id,
    IQueryHandler<GetOrderById, OrderDto?> handler,
    CancellationToken ct) =>
{
    var dto = await handler.HandleAsync(new GetOrderById(id), ct);
    return dto is null ? Results.NotFound() : Results.Ok(dto);
});

No dispatcher, no dynamic, no runtime type resolution. The compiler knows exactly which handler is being injected. Decorators still apply because they wrap the registered handler interface.

When does the dispatcher earn its keep? When you have callers that don't know the concrete command type at compile time — background workers reading from a queue, retry pipelines, or generic API endpoints that map a JSON envelope to a command. For typed endpoints, direct injection is simpler and faster.

A reasonable default: skip the dispatcher in your web layer, keep it for infrastructure code that handles message envelopes.

What You Lose Without MediatR

It's worth being honest about this:

Notification publishing. MediatR's IPublisher lets one event fan out to multiple handlers. If you need this, write it — it's about twenty lines.

public interface IDomainEventPublisher
{
    Task PublishAsync<TEvent>(TEvent @event, CancellationToken ct = default)
        where TEvent : IDomainEvent;
}

public class DomainEventPublisher : IDomainEventPublisher
{
    private readonly IServiceProvider _provider;

    public DomainEventPublisher(IServiceProvider provider) => _provider = provider;

    public async Task PublishAsync<TEvent>(TEvent @event, CancellationToken ct = default)
        where TEvent : IDomainEvent
    {
        var handlers = _provider.GetServices<IDomainEventHandler<TEvent>>();
        foreach (var handler in handlers)
            await handler.HandleAsync(@event, ct);
    }
}

Streaming requests. IStreamRequestHandler returns IAsyncEnumerable. If you need streaming, define an interface for it. Most apps don't.

Community familiarity. New developers will recognise MediatR. A custom abstraction means a paragraph in the README.

What you gain: no third-party dependency, no licensing concerns, no upgrade treadmill, total transparency about how messages get from sender to handler. For most projects, that's a fair trade.

Common Mistakes

Mistake 1: Treating CQRS as Two Databases

CQRS doesn't require separate read and write models, separate databases, or eventual consistency. Those are choices that can be made on top of CQRS, but the pattern itself is just about separating commands from queries at the code level.

You can have one database, one ORM, one set of tables, and still benefit from the separation. CreateOrderHandler writes through EF Core; GetOrderByIdHandler reads through Dapper. Same database, different optimisation strategies.

Mistake 2: Putting Logic in Commands or Queries

// ❌ Command with logic
public record CreateOrder(...)
{
    public bool IsValid() => Lines.Count > 0 && CustomerEmail.Contains("@");
    public decimal CalculateTotal() => Lines.Sum(l => l.Price * l.Quantity);
}

Commands and queries are messages. They carry data; they don't process it. All logic belongs in the handler or the domain. If a record starts growing methods, you've created a hidden service.

Mistake 3: Handlers That Call Other Handlers

// ❌ Handler invoking another handler
public class CreateOrderHandler : ICommandHandler<CreateOrder, OrderId>
{
    private readonly ICommandDispatcher _dispatcher;

    public async Task<OrderId> HandleAsync(CreateOrder command, CancellationToken ct = default)
    {
        var customerId = await _dispatcher.SendAsync(new EnsureCustomerExists(command.CustomerEmail), ct);
        // ...
    }
}

This is how you end up with implicit dependency graphs nobody can trace. If CreateOrderHandler needs to ensure a customer exists, inject ICustomerService and call a method. Handlers should be leaves of the call tree, not branches.

Mistake 4: Reusing Commands as DTOs

The shape that arrives from the API is rarely the shape your handler should accept. Validate, transform, and then construct the command:

// ❌ Treating the request body as a command
app.MapPost("/orders", (CreateOrderRequest req, ICommandDispatcher d) =>
    d.SendAsync(new CreateOrder(req.Email, req.Lines)));

If CreateOrderRequest and CreateOrder end up identical, that's fine — but they're allowed to diverge, and that ability is what makes the pattern useful.

Best Practices

Keep commands and queries flat. A command should be a record with primitive or value-object fields. If you're nesting domain entities inside, you're sending state through a command bus instead of identifiers.

One handler per command. Multiple handlers per command create ordering and ownership questions that don't have good answers. If you need fan-out, that's an event, not a command.

Make handlers thin. A handler orchestrates: load aggregate, call domain method, save, publish events. The domain method does the work. If your handler is 80 lines of logic, the logic belongs in the domain.

Test handlers as units. Handlers are easy to test — they're just classes with constructor dependencies. Mock the repository, call HandleAsync, assert the result and the side effects.

[Fact]
public async Task CreateOrderHandler_PersistsOrder_AndPublishesEvent()
{
    var orders = Substitute.For<IOrderRepository>();
    var events = Substitute.For<IEventBus>();
    var handler = new CreateOrderHandler(orders, events);

    var result = await handler.HandleAsync(new CreateOrder("a@b.com", [new OrderLine("SKU1", 1, 10)]));

    await orders.Received(1).SaveAsync(Arg.Any<Order>(), Arg.Any<CancellationToken>());
    await events.Received(1).PublishAsync(Arg.Any<OrderCreated>(), Arg.Any<CancellationToken>());
}

Keep your dispatcher dumb. Resist the urge to add caching, retries, or "smart" routing inside the dispatcher. Those are decorators, registered as such. The dispatcher's job is to find a handler and invoke it.

When MediatR Still Makes Sense

The licensing change is real, but if your team already pays for the commercial license and has years of code built around it, ripping it out is rarely the right call. The pattern doesn't change — just the package.

There are also legitimate alternatives if you want a maintained library: Wolverine, Brighter, and MassTransit all do CQRS with extras (durable messaging, sagas, transports). They're worth a look if you're crossing process boundaries.

But for the vast majority of monoliths and modular monoliths, the code in this article is the entire toolkit. Five interfaces, two dispatchers, decorator-based pipeline. No third-party dependency, no breaking changes to track, no surprises about how messages reach their handlers.

Conclusion

CQRS was always a pattern about separating writes from reads, not a library about routing messages. MediatR's commercial pivot was a useful forcing function — it made teams ask whether they actually needed the indirection, and a lot of them realised they didn't.

The hand-rolled version isn't a downgrade. It's the same pattern with the implementation visible. You can read every line of how a command reaches its handler. You can step through it in the debugger. You can change it when your needs change. The DI container does the heavy lifting; the rest is interfaces and a decorator or two.

If your codebase already has MediatR and works well, leave it. If you're starting fresh, or if licensing is a problem, this is a clean alternative — and you'll probably find that explicit handlers are easier to reason about than a generic mediator anyway.

The pattern was never the package. The package was just the convenience.

Full source code: github.com/AdrianBailador/cqrs-without-mediatr-dotnet

Questions or suggestions? Open an issue on GitHub.

Anti-Corruption Layer in .NET: Protecting Your Domain from External APIs

Adrián Bailador — Sun, 26 Apr 2026 10:55:26 +0000

We had a clean domain. Orders, customers, payments — all modelled carefully, all speaking the same language. Then we integrated with a payment provider.

Six months later, the PaymentStatus enum had values like PSPCONFIRMED, PSPREJECTED_RETRY, and AUTHORISED_3DS. Our Order entity had a StripeChargeId field. Our service layer was calling MapFromStripeWebhookPayload(). And every developer who touched payments had to understand Stripe's object model before they could understand ours.

The domain hadn't changed. But it had been contaminated.

The Anti-Corruption Layer is the pattern that prevents this. Here's how it works and how to implement it in .NET.

What Is the Anti-Corruption Layer?

The term comes from Eric Evans' Domain-Driven Design. When two systems need to communicate, the boundary between them is dangerous. The external system has its own model, its own vocabulary, its own assumptions about the world — and if you let those concepts bleed into your domain, you end up modelling their world instead of yours.

The Anti-Corruption Layer (ACL) is a translation boundary. It sits between your domain and the external system, converting the external model into your domain model — and vice versa. Your domain never sees the external types. The external system never sees your domain types.

It's not just a mapper. It's an architectural boundary that says: everything on this side speaks our language, everything on that side speaks theirs, and this layer translates between the two.

The Difference Between ACL and Adapter Pattern

You already know the Adapter Pattern — it wraps an incompatible interface to make it compatible. The ACL does something deeper: it translates between two different conceptual models, not just two different interfaces.

An Adapter changes the shape of a call. An ACL changes the meaning.

	Adapter Pattern	Anti-Corruption Layer
Purpose	Interface compatibility	Conceptual model translation
Operates at	Infrastructure level	Domain boundary
Handles	Method signatures	Domain concepts and language
Complexity	Low	Medium-high

In practice, an ACL often uses adapters internally — but its intent is model translation, not interface adaptation.

The Problem Without an ACL

Let's start with the contamination. You're building an e-commerce platform and integrating with a payment provider. Without an ACL, this is what happens:

// ❌ Domain entity contaminated by external concepts
public class Order
{
    public Guid Id { get; private set; }
    public decimal Total { get; private set; }

    // Stripe concepts leaking into the domain
    public string? StripePaymentIntentId { get; set; }
    public string? StripeCustomerId { get; set; }
    public string? StripeStatus { get; set; }  // "requires_payment_method", "succeeded", etc.
}

// ❌ Service layer that understands Stripe better than your own domain
public class OrderService
{
    private readonly StripeClient _stripe;

    public async Task ProcessPaymentAsync(Guid orderId, string paymentMethodId)
    {
        var order = await _repository.GetByIdAsync(orderId);

        // Stripe-specific logic inside domain service
        var paymentIntent = await _stripe.PaymentIntents.CreateAsync(new PaymentIntentCreateOptions
        {
            Amount = (long)(order.Total * 100), // Stripe uses cents
            Currency = "gbp",
            PaymentMethod = paymentMethodId,
            Confirm = true,
        });

        // Mapping Stripe statuses directly in domain logic
        order.StripePaymentIntentId = paymentIntent.Id;
        order.StripeStatus = paymentIntent.Status;

        if (paymentIntent.Status == "succeeded")
            order.MarkAsPaid();
        else if (paymentIntent.Status == "requires_action")
            order.MarkAsAwaitingAction();
    }
}

The problems:

Your domain knows what a PaymentIntent is. It shouldn't.
Every developer needs to know Stripe's status strings to understand your order logic.
If you switch payment providers, you rewrite the domain.
If Stripe renames a status, you hunt through domain code to find the references.

Building the Anti-Corruption Layer

The ACL has three responsibilities:

Translate external models into domain models
Isolate domain code from external API contracts
Absorb changes — when the external API changes, only the ACL changes

Step 1: Define Your Domain Model

First, define what your domain needs, in your language:

// Your domain concepts — no external dependencies
public record Payment
{
    public PaymentId Id { get; init; }
    public Money Amount { get; init; }
    public PaymentStatus Status { get; init; }
    public PaymentProvider Provider { get; init; }
    public string ExternalReference { get; init; } = string.Empty;
    public DateTimeOffset ProcessedAt { get; init; }
}

public enum PaymentStatus
{
    Pending,
    Authorised,
    Captured,
    Declined,
    RequiresAction,
    Refunded
}

public enum PaymentProvider
{
    Stripe,
    PayPal
}

public record Money(decimal Amount, string Currency)
{
    public static Money GBP(decimal amount) => new(amount, "GBP");
    public static Money USD(decimal amount) => new(amount, "USD");
}

public record PaymentId(string Value)
{
    public static PaymentId New() => new(Guid.NewGuid().ToString());
}

Step 2: Define the Domain Port

The domain declares what it needs through an interface — it doesn't care how it's implemented:

// The domain's view of payment processing — no external types
public interface IPaymentGateway
{
    Task<PaymentResult> ChargeAsync(PaymentRequest request, CancellationToken ct = default);
    Task<PaymentResult> RefundAsync(string externalReference, Money amount, CancellationToken ct = default);
    Task<Payment?> GetPaymentAsync(string externalReference, CancellationToken ct = default);
}

public record PaymentRequest(
    Money Amount,
    string PaymentMethodToken,
    string OrderReference,
    string CustomerEmail);

public record PaymentResult(
    bool Success,
    Payment? Payment,
    string? ErrorMessage,
    bool RequiresAction,
    string? ActionUrl);

Step 3: Implement the ACL Translator

This is the heart of the pattern. The ACL implementation knows about Stripe — but your domain never will:

// Infrastructure layer — the only place that knows about Stripe
public class StripePaymentGateway : IPaymentGateway
{
    private readonly PaymentIntentService _paymentIntentService;
    private readonly RefundService _refundService;
    private readonly ILogger<StripePaymentGateway> _logger;

    public StripePaymentGateway(
        PaymentIntentService paymentIntentService,
        RefundService refundService,
        ILogger<StripePaymentGateway> logger)
    {
        _paymentIntentService = paymentIntentService;
        _refundService = refundService;
        _logger = logger;
    }

    public async Task<PaymentResult> ChargeAsync(
        PaymentRequest request,
        CancellationToken ct = default)
    {
        try
        {
            // Translate domain request → Stripe request
            var options = TranslateToStripeOptions(request);
            var intent = await _paymentIntentService.CreateAsync(options, cancellationToken: ct);

            // Translate Stripe response → domain Payment
            var payment = TranslateFromStripe(intent);
            var requiresAction = intent.Status == "requires_action";

            return new PaymentResult(
                Success: intent.Status is "succeeded" or "requires_action",
                Payment: payment,
                ErrorMessage: null,
                RequiresAction: requiresAction,
                ActionUrl: intent.NextAction?.RedirectToUrl?.Url);
        }
        catch (StripeException ex)
        {
            _logger.LogWarning(ex, "Stripe charge failed for order {OrderReference}", request.OrderReference);

            // Translate Stripe error → domain result
            return new PaymentResult(
                Success: false,
                Payment: null,
                ErrorMessage: TranslateStripeError(ex.StripeError),
                RequiresAction: false,
                ActionUrl: null);
        }
    }

    public async Task<PaymentResult> RefundAsync(
        string externalReference,
        Money amount,
        CancellationToken ct = default)
    {
        try
        {
            var refund = await _refundService.CreateAsync(new RefundCreateOptions
            {
                PaymentIntent = externalReference,
                Amount = ToStripeCents(amount),
            }, cancellationToken: ct);

            return new PaymentResult(
                Success: refund.Status == "succeeded",
                Payment: null,
                ErrorMessage: null,
                RequiresAction: false,
                ActionUrl: null);
        }
        catch (StripeException ex)
        {
            _logger.LogError(ex, "Stripe refund failed for {ExternalReference}", externalReference);
            return new PaymentResult(false, null, TranslateStripeError(ex.StripeError), false, null);
        }
    }

    public async Task<Payment?> GetPaymentAsync(
        string externalReference,
        CancellationToken ct = default)
    {
        try
        {
            var intent = await _paymentIntentService.GetAsync(externalReference, cancellationToken: ct);
            return TranslateFromStripe(intent);
        }
        catch (StripeException ex) when (ex.HttpStatusCode == System.Net.HttpStatusCode.NotFound)
        {
            return null;
        }
    }

    // ── Translation methods ───────────────────────────────────────────────────
    // These are the core of the ACL. All Stripe-specific knowledge lives here.

    private static PaymentIntentCreateOptions TranslateToStripeOptions(PaymentRequest request) =>
        new()
        {
            Amount = ToStripeCents(request.Amount),
            Currency = request.Amount.Currency.ToLowerInvariant(),
            PaymentMethod = request.PaymentMethodToken,
            Confirm = true,
            ReceiptEmail = request.CustomerEmail,
            Metadata = new Dictionary<string, string>
            {
                ["order_reference"] = request.OrderReference
            }
        };

    private static Payment TranslateFromStripe(PaymentIntent intent) =>
        new()
        {
            Id = new PaymentId(intent.Id),
            Amount = new Money(intent.Amount / 100m, intent.Currency.ToUpperInvariant()),
            Status = TranslateStripeStatus(intent.Status),
            Provider = PaymentProvider.Stripe,
            ExternalReference = intent.Id,
            ProcessedAt = intent.Created
        };

    private static PaymentStatus TranslateStripeStatus(string stripeStatus) =>
        stripeStatus switch
        {
            "requires_payment_method" => PaymentStatus.Pending,
            "requires_confirmation"   => PaymentStatus.Pending,
            "requires_action"         => PaymentStatus.RequiresAction,
            "processing"              => PaymentStatus.Pending,
            "succeeded"               => PaymentStatus.Captured,
            "canceled"                => PaymentStatus.Declined,
            _ => PaymentStatus.Pending
        };

    private static string TranslateStripeError(StripeError? error) =>
        error?.Code switch
        {
            "card_declined"           => "Your card was declined.",
            "insufficient_funds"      => "Insufficient funds on your card.",
            "incorrect_cvc"           => "The security code is incorrect.",
            "expired_card"            => "Your card has expired.",
            "processing_error"        => "A processing error occurred. Please try again.",
            _ => "Payment could not be processed. Please try again."
        };

    private static long ToStripeCents(Money money) => (long)(money.Amount * 100);
}

Step 4: The Clean Domain Service

Now look at how clean your domain service becomes:

// ✅ Domain service that knows nothing about Stripe
public class OrderPaymentService
{
    private readonly IOrderRepository _orders;
    private readonly IPaymentGateway _paymentGateway;  // domain interface, not Stripe
    private readonly ILogger<OrderPaymentService> _logger;

    public OrderPaymentService(
        IOrderRepository orders,
        IPaymentGateway paymentGateway,
        ILogger<OrderPaymentService> logger)
    {
        _orders = orders;
        _paymentGateway = paymentGateway;
        _logger = logger;
    }

    public async Task<PaymentOutcome> ProcessPaymentAsync(
        Guid orderId,
        string paymentMethodToken,
        CancellationToken ct = default)
    {
        var order = await _orders.GetByIdAsync(orderId, ct)
            ?? throw new OrderNotFoundException(orderId);

        var request = new PaymentRequest(
            Amount: Money.GBP(order.Total),
            PaymentMethodToken: paymentMethodToken,
            OrderReference: order.Reference,
            CustomerEmail: order.CustomerEmail);

        var result = await _paymentGateway.ChargeAsync(request, ct);

        if (!result.Success)
        {
            _logger.LogWarning("Payment failed for order {OrderId}: {Error}", orderId, result.ErrorMessage);
            return PaymentOutcome.Failed(result.ErrorMessage!);
        }

        if (result.RequiresAction)
        {
            order.AwaitCustomerAction(result.Payment!);
            await _orders.SaveAsync(order, ct);
            return PaymentOutcome.RequiresAction(result.ActionUrl!);
        }

        order.MarkAsPaid(result.Payment!);
        await _orders.SaveAsync(order, ct);

        return PaymentOutcome.Succeeded(result.Payment!);
    }
}

public record PaymentOutcome
{
    public bool IsSuccess { get; init; }
    public bool NeedsAction { get; init; }
    public string? ActionUrl { get; init; }
    public string? Error { get; init; }
    public Payment? Payment { get; init; }

    public static PaymentOutcome Succeeded(Payment payment) =>
        new() { IsSuccess = true, Payment = payment };

    public static PaymentOutcome RequiresAction(string actionUrl) =>
        new() { IsSuccess = true, NeedsAction = true, ActionUrl = actionUrl };

    public static PaymentOutcome Failed(string error) =>
        new() { IsSuccess = false, Error = error };
}

No PaymentIntent. No StripeException. No requires_payment_method. The domain service is readable by anyone who understands the business, not just developers who know Stripe.

Step 5: Wiring It Up

// Program.cs
builder.Services.AddScoped<IPaymentGateway, StripePaymentGateway>();

// If you want to swap providers without touching the domain:
// builder.Services.AddScoped<IPaymentGateway, PayPalPaymentGateway>();

builder.Services.AddScoped<OrderPaymentService>();

// Stripe SDK services
builder.Services.AddSingleton<PaymentIntentService>();
builder.Services.AddSingleton<RefundService>();

StripeConfiguration.ApiKey = builder.Configuration["Stripe:SecretKey"];

Handling Webhooks Through the ACL

Webhooks are where contamination is most dangerous — you receive a raw external payload and have to decide what it means for your domain.

// ❌ Without ACL — Stripe webhook logic inside domain
[HttpPost("webhooks/stripe")]
public async Task<IActionResult> StripeWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var stripeEvent = EventUtility.ConstructEvent(payload, Request.Headers["Stripe-Signature"], _secret);

    if (stripeEvent.Type == "payment_intent.succeeded")
    {
        var intent = stripeEvent.Data.Object as PaymentIntent;
        // Now you're writing domain logic inside a Stripe webhook handler
    }
}

// ✅ With ACL — the domain sees a domain event
public interface IPaymentWebhookTranslator
{
    Task<DomainPaymentEvent?> TranslateAsync(string payload, string signature, CancellationToken ct = default);
}

public record DomainPaymentEvent(
    DomainPaymentEventType Type,
    string ExternalReference,
    Money? Amount);

public enum DomainPaymentEventType
{
    PaymentSucceeded,
    PaymentFailed,
    PaymentRefunded,
    DisputeOpened
}

// ACL implementation — knows about Stripe
public class StripeWebhookTranslator : IPaymentWebhookTranslator
{
    private readonly string _webhookSecret;

    public StripeWebhookTranslator(IConfiguration config)
    {
        _webhookSecret = config["Stripe:WebhookSecret"]!;
    }

    public Task<DomainPaymentEvent?> TranslateAsync(
        string payload,
        string signature,
        CancellationToken ct = default)
    {
        Event stripeEvent;

        try
        {
            stripeEvent = EventUtility.ConstructEvent(payload, signature, _webhookSecret);
        }
        catch (StripeException)
        {
            return Task.FromResult<DomainPaymentEvent?>(null);
        }

        var domainEvent = stripeEvent.Type switch
        {
            "payment_intent.succeeded" => TranslateSucceeded(stripeEvent),
            "payment_intent.payment_failed" => TranslateFailed(stripeEvent),
            "charge.refunded" => TranslateRefunded(stripeEvent),
            "charge.dispute.created" => TranslateDispute(stripeEvent),
            _ => null
        };

        return Task.FromResult(domainEvent);
    }

    private static DomainPaymentEvent? TranslateSucceeded(Event e)
    {
        if (e.Data.Object is not PaymentIntent intent) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentSucceeded,
            ExternalReference: intent.Id,
            Amount: new Money(intent.Amount / 100m, intent.Currency.ToUpperInvariant()));
    }

    private static DomainPaymentEvent? TranslateFailed(Event e)
    {
        if (e.Data.Object is not PaymentIntent intent) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentFailed,
            ExternalReference: intent.Id,
            Amount: null);
    }

    private static DomainPaymentEvent? TranslateRefunded(Event e)
    {
        if (e.Data.Object is not Charge charge) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentRefunded,
            ExternalReference: charge.PaymentIntentId,
            Amount: new Money(charge.AmountRefunded / 100m, charge.Currency.ToUpperInvariant()));
    }

    private static DomainPaymentEvent? TranslateDispute(Event e)
    {
        if (e.Data.Object is not Dispute dispute) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.DisputeOpened,
            ExternalReference: dispute.ChargeId,
            Amount: new Money(dispute.Amount / 100m, dispute.Currency.ToUpperInvariant()));
    }
}

// Clean controller — receives domain events, not Stripe events
[HttpPost("webhooks/payments")]
public async Task<IActionResult> PaymentWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var signature = Request.Headers["Stripe-Signature"].ToString();

    var domainEvent = await _webhookTranslator.TranslateAsync(payload, signature);

    if (domainEvent is null)
        return BadRequest();

    await _paymentEventHandler.HandleAsync(domainEvent);
    return Ok();
}

Switching Providers Without Touching the Domain

This is where the investment pays off. If you need to switch from Stripe to PayPal:

// New ACL implementation — everything Stripe is gone from this file
public class PayPalPaymentGateway : IPaymentGateway
{
    private readonly PayPalHttpClient _client;

    public async Task<PaymentResult> ChargeAsync(
        PaymentRequest request,
        CancellationToken ct = default)
    {
        // Translate domain request → PayPal request
        var paypalOrder = TranslateToPayPalOrder(request);
        var response = await _client.Execute(new OrdersCreateRequest().RequestBody(paypalOrder));

        // Translate PayPal response → domain result
        return TranslateFromPayPal(response.Result<Order>());
    }

    private static PaymentResult TranslateFromPayPal(Order order) =>
        new(
            Success: order.Status == "COMPLETED",
            Payment: new Payment
            {
                Id = new PaymentId(order.Id),
                Status: TranslatePayPalStatus(order.Status),
                Provider = PaymentProvider.PayPal,
                ExternalReference = order.Id,
                // ...
            },
            ErrorMessage: null,
            RequiresAction: order.Status == "PAYER_ACTION_REQUIRED",
            ActionUrl: order.Links?.FirstOrDefault(l => l.Rel == "payer-action")?.Href);

    private static PaymentStatus TranslatePayPalStatus(string status) =>
        status switch
        {
            "CREATED"  => PaymentStatus.Pending,
            "SAVED"    => PaymentStatus.Pending,
            "APPROVED" => PaymentStatus.Authorised,
            "COMPLETED" => PaymentStatus.Captured,
            "VOIDED"   => PaymentStatus.Declined,
            _ => PaymentStatus.Pending
        };
}

Change one line in Program.cs:

// Before
builder.Services.AddScoped<IPaymentGateway, StripePaymentGateway>();

// After
builder.Services.AddScoped<IPaymentGateway, PayPalPaymentGateway>();

The domain, the service layer, the controllers — unchanged. The ACL absorbed the migration.

Common Mistakes

Mistake 1: Putting translation logic in the domain

// ❌ Domain entity knows how to parse Stripe responses
public class Order
{
    public void ApplyStripeWebhook(StripeEvent e)
    {
        if (e.Type == "payment_intent.succeeded")
            Status = OrderStatus.Paid;
    }
}

The domain should never import external SDK types. If you see using Stripe; in a domain class, the ACL is missing.

Mistake 2: Leaking IDs across the boundary

// ❌ External ID stored as a first-class domain concept
public class Order
{
    public string StripePaymentIntentId { get; set; }  // Stripe concept in domain
}

// ✅ Store as an opaque external reference
public class Order
{
    public string? ExternalPaymentReference { get; private set; }  // domain concept
}

The domain doesn't know or care that ExternalPaymentReference is a Stripe PaymentIntent ID. It's just a reference to something external.

Mistake 3: Making the ACL a thin pass-through

// ❌ No translation — just wrapping the call
public class StripePaymentGateway : IPaymentGateway
{
    public async Task<PaymentIntent> ChargeAsync(PaymentIntentCreateOptions options)
    {
        return await _stripe.PaymentIntents.CreateAsync(options);
    }
}

If your ACL exposes external types in its return values or parameters, it's not an ACL. It's just a facade that provides a false sense of protection.

Mistake 4: One ACL for everything

If your system integrates with a payment provider, a shipping API, a CRM, and an email service, each deserves its own ACL. Mixing them creates the same coupling problem you were trying to solve.

Domain
├── Payments/
│   ├── IPaymentGateway.cs           ← domain port
│   └── Infrastructure/
│       └── StripePaymentGateway.cs  ← ACL for Stripe
├── Shipping/
│   ├── IShippingProvider.cs         ← domain port
│   └── Infrastructure/
│       └── DhlShippingProvider.cs   ← ACL for DHL
└── Notifications/
    ├── IEmailSender.cs              ← domain port
    └── Infrastructure/
        └── SendGridEmailSender.cs   ← ACL for SendGrid

Best Practices

Keep external types out of domain interfaces. If IPaymentGateway has a method that accepts or returns a Stripe type, the ACL has failed. Domain interfaces use only domain types.

Put all translation in one place. The mapping from Stripe statuses to PaymentStatus should live in exactly one method. When Stripe adds a new status, you change one switch expression.

Name the ACL after what it provides, not what it wraps. IPaymentGateway is better than IStripeAdapter. Your domain doesn't know it's talking to Stripe.

Write tests for the translation logic. The ACL is where subtle bugs hide — a missing status mapping, a wrong currency conversion, a misinterpreted error code. Unit test the translation methods directly.

[Theory]
[InlineData("succeeded", PaymentStatus.Captured)]
[InlineData("requires_action", PaymentStatus.RequiresAction)]
[InlineData("canceled", PaymentStatus.Declined)]
[InlineData("processing", PaymentStatus.Pending)]
public void TranslateStripeStatus_MapsCorrectly(string stripeStatus, PaymentStatus expected)
{
    var result = StripeStatusTranslator.Translate(stripeStatus);
    Assert.Equal(expected, result);
}

Let the ACL absorb errors too. Don't let StripeException propagate into the domain. Catch it in the ACL and translate it into a domain result. The domain should never handle payment provider exceptions.

Conclusion

The contamination I described at the start — StripeChargeId on Order, PSPCONFIRMED in the status enum, MapFromStripeWebhookPayload() in the service layer — wasn't inevitable. It happened gradually, one shortcut at a time, each one reasonable in isolation.

The Anti-Corruption Layer is the structural decision that makes those shortcuts impossible. It says: this is the boundary. On this side, we speak our language. On that side, they speak theirs. Here is where the translation happens.

The benefits accumulate slowly and then pay off all at once: when Stripe deprecates an endpoint, only the ACL changes. When you add a second payment provider, you add a second ACL. When a new developer joins the team, they can understand the payment flow without knowing Stripe's object model.

The domain stays clean. The external system stays external. The translation layer absorbs the chaos so everything else doesn't have to.

Full source code: github.com/AdrianBailador/anti-corruption-layer-dotnet

Questions or suggestions? Open an issue on GitHub.

Kubernetes Probes + .NET: Liveness, Readiness and Startup in Production

Adrián Bailador — Wed, 22 Apr 2026 18:49:01 +0000

I once watched a .NET service restart in a loop for twenty minutes while every other signal said it was fine. The readiness probe was passing. The liveness probe was passing. The pod was being killed anyway.

The problem was that both probes pointed to the same /health endpoint — one that checked the database. The database was slow during a migration. The pod failed liveness, got killed, restarted, tried to connect to the database again, failed liveness again. A perfectly healthy process was being murdered by its own health check.

Here's what I wish someone had explained before I deployed that.

Why One `/health` Endpoint Is Not Enough

The instinct is understandable. You add a /health endpoint, map it to Kubernetes probes, and feel responsible. But a single endpoint can't serve three fundamentally different questions:

Is this process alive and worth keeping? (Liveness)
Is this process ready to serve user traffic right now? (Readiness)
Has this process finished its startup sequence? (Startup)

Using the same endpoint for all three is like having one traffic light that controls both the pedestrian crossing and the highway on-ramp. The signals mean different things and the consequences of getting them wrong are different.

The consequences of mixing probes:

What goes wrong	What Kubernetes does	What actually happens
Database is slow	Liveness fails	Pod restarts — making the problem worse
Redis is unreachable	Liveness fails	Pod restarts — Redis is still unreachable
App is starting up	Liveness fires too early	Pod killed before it's even ready
Pod is overwhelmed	Readiness fails	Pod stops receiving traffic — correct behaviour

The right mental model: liveness is about the process, readiness is about the dependencies.

The Three Probes, Explained

Liveness Probe

Question it answers: Is this container alive enough to keep running?

Action on failure: Kubernetes restarts the container.

What to check: Only things that indicate the process itself is broken — a deadlock, an unrecoverable panic, a corrupted internal state. Not external dependencies. If your database is down, that's not a reason to restart your process. Restarting won't fix the database.

A liveness check that fails should answer yes to: "Would restarting this process fix the problem?"

Readiness Probe

Question it answers: Should this container receive traffic right now?

Action on failure: Kubernetes removes the pod from the Service endpoints. No traffic is routed to it. The pod keeps running.

What to check: Everything the pod needs to serve a request successfully — database connectivity, dependent services, cache availability. When readiness fails, traffic stops flowing to this pod until it recovers.

Startup Probe

Question it answers: Has this container finished starting up?

Action on failure: Kubernetes kills the container (same as liveness).

What it replaces: initialDelaySeconds on liveness/readiness probes.

The startup probe runs until it succeeds, then hands control to liveness and readiness. While the startup probe is running, liveness and readiness are suspended. This means your slow-starting container won't be killed before it's ready, without having to set dangerously long initialDelaySeconds values on all other probes.

A .NET service that runs EF Core migrations, warms up caches, and establishes connection pools at startup might need 30–90 seconds. The startup probe handles this cleanly.

Setting Up Health Checks in .NET

The foundation is tagging. Each health check gets one or more tags, and each Kubernetes probe maps to an endpoint that only runs checks with matching tags.

Installing the Packages

dotnet add package AspNetCore.HealthChecks.SqlServer
dotnet add package AspNetCore.HealthChecks.NpgSql
dotnet add package AspNetCore.HealthChecks.Redis
dotnet add package AspNetCore.HealthChecks.Uris

Registering Checks with Tags

builder.Services.AddHealthChecks()
    // Liveness: only checks the process itself
    .AddCheck<SelfHealthCheck>(
        name: "self",
        tags: ["live"])

    // Readiness + Liveness: disk space affects both
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])

    // Readiness only: external dependencies
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])

    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("Postgres")!,
        name: "postgresql",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])

    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded, // cache miss is survivable
        tags: ["ready"])

    .AddUrlGroup(
        uri: new Uri("https://api.stripe.com/v1/"),
        name: "stripe-api",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])

    // Startup: checks that migrations have run and caches are warm
    .AddCheck<StartupHealthCheck>(
        name: "startup-complete",
        tags: ["startup"]);

The SelfHealthCheck

The liveness check for the process itself. It should almost always return healthy — if it doesn't, the container will be restarted.

public class SelfHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        // Check for conditions that indicate the process is fundamentally broken.
        // Most of the time, this is just: I'm running, therefore I'm alive.
        var allocatedMemoryMb = GC.GetTotalMemory(forceFullCollection: false) / 1_048_576;

        if (allocatedMemoryMb > 2048)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy(
                $"Memory usage critical: {allocatedMemoryMb} MB allocated. Possible memory leak.",
                data: new Dictionary<string, object> { ["allocated_mb"] = allocatedMemoryMb }));
        }

        return Task.FromResult(HealthCheckResult.Healthy(
            data: new Dictionary<string, object> { ["allocated_mb"] = allocatedMemoryMb }));
    }
}

The StartupHealthCheck

Tracks whether the application has completed its initialisation sequence. You set a flag when startup is done; the probe checks the flag.

public class StartupHealthCheck : IHealthCheck
{
    private static bool _startupComplete = false;

    // Call this from your startup logic when everything is ready
    public static void MarkStartupComplete() => _startupComplete = true;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (!_startupComplete)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy(
                "Application has not completed startup sequence yet."));
        }

        return Task.FromResult(HealthCheckResult.Healthy("Startup complete."));
    }
}

Mark it done in Program.cs after migrations, cache warm-up, or whatever your startup sequence involves:

var app = builder.Build();

// Run migrations
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

// Warm up caches, establish connection pools, etc.
await WarmUpCachesAsync(app.Services);

// Signal that startup is complete
StartupHealthCheck.MarkStartupComplete();

app.Run();

Mapping the Three Endpoints

// Liveness — is the process alive?
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,  // degraded = still alive
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Readiness — can it serve traffic?
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,  // degraded can still serve
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Startup — has initialisation finished?
app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("startup"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status503ServiceUnavailable, // not ready yet
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Kubernetes YAML

Here's a complete Deployment spec with all three probes configured for a typical .NET API.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-dotnet-api
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-dotnet-api
  template:
    metadata:
      labels:
        app: my-dotnet-api
    spec:
      containers:
        - name: api
          image: myregistry/my-dotnet-api:latest
          ports:
            - containerPort: 8080

          # Startup probe: runs until the app finishes initialising.
          # Liveness and readiness are suspended while this is running.
          # 30 attempts × 5s interval = up to 150 seconds to start.
          startupProbe:
            httpGet:
              path: /health/startup
              port: 8080
            initialDelaySeconds: 0   # start checking immediately
            periodSeconds: 5         # check every 5 seconds
            failureThreshold: 30     # allow up to 150 seconds to start
            successThreshold: 1
            timeoutSeconds: 3

          # Liveness probe: runs after startup succeeds.
          # Failure → container restart.
          # Only check what a restart would actually fix.
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 0   # startup probe already handled the delay
            periodSeconds: 15        # don't hammer it — 15s is usually enough
            failureThreshold: 3      # 3 consecutive failures → restart
            successThreshold: 1
            timeoutSeconds: 5

          # Readiness probe: runs after startup succeeds.
          # Failure → pod removed from Service, no traffic routed.
          # Check all dependencies needed to serve a request.
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 0
            periodSeconds: 10        # check more frequently than liveness
            failureThreshold: 3      # 3 failures → stop sending traffic
            successThreshold: 2      # 2 successes to re-add to rotation
            timeoutSeconds: 5

          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"

          env:
            - name: ASPNETCORE_URLS
              value: "http://+:8080"
            - name: ConnectionStrings__DefaultConnection
              valueFrom:
                secretKeyRef:
                  name: my-dotnet-api-secrets
                  key: db-connection-string

Understanding the Numbers

periodSeconds — how often Kubernetes checks. Too low and you add unnecessary load; too high and you react slowly to failures.

Liveness: 15–30 seconds. A stuck process doesn't need sub-second detection.
Readiness: 5–10 seconds. You want traffic to re-route quickly when a pod recovers.
Startup: 5 seconds. You want to know as soon as the app is ready.

failureThreshold — how many consecutive failures before action is taken.

Set this to 3 minimum. A transient network hiccup or a momentary slow query shouldn't kill your pod. failureThreshold: 1 is almost always wrong in production.
For startup: set it to maxStartupSeconds / periodSeconds. If your app might take 90 seconds to start: 90 / 5 = 18 failures.

successThreshold — how many consecutive successes to consider the probe passing.

For readiness: setting this to 2 prevents a pod that's still recovering from being re-added to rotation after one fluke success. Default is 1.
For liveness: must be 1 (Kubernetes enforces this).

timeoutSeconds — how long Kubernetes waits for the probe to respond.

Your health check must complete within this time or it counts as a failure. Make sure your checks have timeouts shorter than this value.

Common Mistakes

Mistake 1: Checking external dependencies in the liveness probe

# ❌ This will cause restart loops
livenessProbe:
  httpGet:
    path: /health  # checks database
    port: 8080

If the database is down or slow, the liveness probe fails, the pod restarts, reconnects to the same database, fails again. You've created a restart loop that makes the incident worse.

# ✅ Liveness only checks the process
livenessProbe:
  httpGet:
    path: /health/live  # only checks self and disk
    port: 8080

Mistake 2: Using `initialDelaySeconds` instead of a startup probe

# ❌ Guessing how long startup takes
livenessProbe:
  initialDelaySeconds: 60  # hope it's enough

This creates two problems. If startup takes 61 seconds, the pod gets killed. If startup usually takes 10 seconds but you set 60, every pod is unavailable for 60 seconds unnecessarily — this matters during rolling updates.

# ✅ Let the startup probe determine when the app is ready
startupProbe:
  httpGet:
    path: /health/startup
    port: 8080
  periodSeconds: 5
  failureThreshold: 30  # up to 150 seconds, no guessing

Mistake 3: Setting `failureThreshold: 1`

# ❌ Any single timeout kills the pod
livenessProbe:
  failureThreshold: 1

A single slow response, a momentary GC pause, a brief network hiccup — all of these become pod restarts. In a high-traffic system, this creates cascades: one pod restarts, more traffic hits the remaining pods, they slow down, they restart, and so on.

# ✅ Require consecutive failures before action
livenessProbe:
  failureThreshold: 3  # three consecutive failures required

Mistake 4: The probe timeout is longer than the check timeout

livenessProbe:
  timeoutSeconds: 10

// ❌ The health check has no timeout — it can block for 30+ seconds
public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    var response = await _httpClient.GetAsync("/ping"); // no timeout
    // ...
}

If the check takes 15 seconds, Kubernetes considers it a timeout failure at 10 seconds — but the check is still running in the background, consuming resources and holding connections.

// ✅ Always add an explicit timeout inside your health check
public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    cts.CancelAfter(TimeSpan.FromSeconds(3)); // well under the probe's timeoutSeconds

    try
    {
        var response = await _httpClient.GetAsync("/ping", cts.Token);
        return response.IsSuccessStatusCode
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Degraded($"Returned {(int)response.StatusCode}");
    }
    catch (OperationCanceledException)
    {
        return HealthCheckResult.Degraded("Timed out after 3 seconds.");
    }
}

Mistake 5: Not setting `successThreshold` on readiness

When a pod recovers from a readiness failure, Kubernetes re-adds it to the Service after the first successful probe. That pod might be in the middle of warming up caches or draining a backlog. Setting successThreshold: 2 gives you an extra check before traffic returns.

readinessProbe:
  successThreshold: 2  # two consecutive successes before re-adding to rotation

Mistake 6: Exposing health check internals to the internet

The /health/ready endpoint can return database names, connection strings fragments in exception messages, and internal IP addresses. Don't expose it publicly.

// Route it through an internal ingress only
app.MapHealthChecks("/health/live").RequireHost("*.internal");
app.MapHealthChecks("/health/ready").RequireHost("*.internal");
app.MapHealthChecks("/health/startup").RequireHost("*.internal");

Or, if your service mesh makes RequireHost unreliable, use network policies at the Kubernetes level to restrict access to the health endpoints from outside the cluster.

Best Practices

One responsibility per probe. Liveness = process health. Readiness = traffic eligibility. Startup = initialisation complete. Never mix these concerns in a single endpoint.

Make liveness checks trivial. The liveness probe should fail only when a restart would actually help. That's a small set: deadlocks, unrecoverable panics, memory leaks, corrupted internal state. If you're unsure whether a condition should trigger a restart, it probably shouldn't.

Make readiness checks comprehensive. The readiness probe should reflect whether the pod can actually serve a request end-to-end. If a request needs the database and the database is down, readiness should fail. That's the correct behaviour — stop sending traffic to that pod.

Always set Degraded for non-critical dependencies. Redis down → Degraded, not Unhealthy. If readiness maps Degraded to 200 OK (which it should for most services), the pod stays in rotation and serves requests without caching. The alternative — taking the pod out of rotation because Redis is down — is usually worse.

Cache expensive checks. Probes run every 5–15 seconds. A health check that runs a database query on every call adds measurable load. Cache results for 15–30 seconds:

public class CachedDatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnectionFactory _factory;
    private HealthCheckResult _cached = HealthCheckResult.Healthy();
    private DateTimeOffset _lastRun = DateTimeOffset.MinValue;
    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(20);

    public CachedDatabaseHealthCheck(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (DateTimeOffset.UtcNow - _lastRun < CacheDuration)
            return _cached;

        try
        {
            await using var conn = await _factory.CreateConnectionAsync(cancellationToken);
            await conn.ExecuteAsync("SELECT 1");
            _cached = HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            _cached = HealthCheckResult.Unhealthy("Database unreachable.", ex);
        }

        _lastRun = DateTimeOffset.UtcNow;
        return _cached;
    }
}

Log probe failures. Kubernetes logs probe failures in pod events, but they don't always surface well. Add structured logging inside your health checks so you get context when things go wrong:

public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    try
    {
        await _connection.ExecuteAsync("SELECT 1");
        return HealthCheckResult.Healthy();
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Database health check failed for {CheckName}", context.Registration.Name);
        return HealthCheckResult.Unhealthy("Database check failed.", ex);
    }
}

Test your probes in staging. Kill your database, take down Redis, fill up the disk. Verify that:

Readiness fails and pods stop receiving traffic
Liveness does not fail (and therefore pods are not restarted)
The service degrades gracefully instead of crashing
Traffic re-routes to healthy pods automatically

Don't discover that your probe configuration is wrong during a real incident.

Putting It All Together

Here's the complete Program.cs with everything wired up:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
    .AddCheck<SelfHealthCheck>(
        name: "self",
        tags: ["live"])
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])
    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])
    .AddCheck<StartupHealthCheck>(
        name: "startup-complete",
        tags: ["startup"]);

var app = builder.Build();

// Run startup sequence
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

StartupHealthCheck.MarkStartupComplete();

// Map probe endpoints
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("startup"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status503ServiceUnavailable,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.Run();

Conclusion

The restart loop I described at the start was caused by a single wrong decision: using one endpoint for three different questions. The fix was twenty lines of code and ten minutes of work.

The mental model to take away:

Liveness asks: "Is this process broken beyond repair?" Only restart if the answer is yes.
Readiness asks: "Is this process ready to handle a request right now?" Remove from rotation if the answer is no.
Startup asks: "Has this process finished initialising?" Don't send liveness or readiness probes until the answer is yes.

Three questions. Three endpoints. Three probes. Each one doing exactly one job, with consequences matched to the answer.

Once you have this in place, Kubernetes becomes a genuine safety net — not something that makes incidents worse by restarting healthy pods in the middle of a database outage.

Have questions or found an issue with the examples? Open an issue on GitHub.

🚀 I've been quietly building new features into The Coffee Timer ☕ — my Pomodoro productivity app — and I'm excited to share what's new!

Adrián Bailador — Sun, 12 Apr 2026 19:24:04 +0000

Here's what just shipped:

☕ Focus Stats Dashboard — See your last 7 days of focus time, top tasks by

pomodoros, and key productivity metrics. (Premium)

🗺️ Interactive Onboarding Tour — A step-by-step guided tour with spotlight

tooltips so new users know exactly what everything does from day one.

🌍 Spanish / English toggle — One click to switch the entire UI between EN
and ES. Building for a global audience from the start.

All of this on top of Spotify integration, ambient sounds, streak tracking, and a beautiful coffee cup that fills as you work. ☕

If you're curious, give it a try → https://thecoffeetimer.com/

Built with React, TypeScript, .NET 8, Supabase & Stripe. Solo project, shipping fast. 🛠️

Health Checks in ASP.NET Core: Beyond the Basic /health Endpoint

Adrián Bailador — Sun, 12 Apr 2026 11:09:54 +0000

A service returning 200 OK on /health doesn't mean it's healthy. It means the process is alive and the route handler executed. Your database could be unreachable, your message broker offline, your disk at 99% capacity — and /health would still return green.

I've seen this exact situation cause a silent outage. The load balancer was happy, Kubernetes wasn't restarting anything, and the monitoring dashboard showed all services up. Meanwhile, every request that touched the database was failing. The health check was lying.

Here's how to make it tell the truth.

The Setup Everyone Has

// Program.cs — the version that gives you false confidence
app.MapGet("/health", () => "Healthy");

Or slightly better, using the built-in middleware:

builder.Services.AddHealthChecks();
app.MapHealthChecks("/health");

Both return 200 OK as long as the process is running. Neither checks anything meaningful.

What ASP.NET Core Health Checks Actually Give You

The Microsoft.AspNetCore.Diagnostics.HealthChecks package (included in the ASP.NET Core metapackage) provides an extensible pipeline where each check implements IHealthCheck:

public interface IHealthCheck
{
    Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default);
}

A HealthCheckResult is one of three states:

HealthCheckResult.Healthy() — everything is fine
HealthCheckResult.Degraded() — working but not at full capacity
HealthCheckResult.Unhealthy() — something is broken

The overall status of the endpoint is the worst status across all registered checks. One Unhealthy check makes the whole endpoint return 503 Service Unavailable.

Checking What Actually Matters

Database Connectivity

The most critical check for most APIs. Install the NuGet package for your database:

dotnet add package AspNetCore.HealthChecks.SqlServer
dotnet add package AspNetCore.HealthChecks.NpgSql       # PostgreSQL
dotnet add package AspNetCore.HealthChecks.MySql         # MySQL

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        healthQuery: "SELECT 1",
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["database", "sql"])
    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("Postgres")!,
        name: "postgresql",
        tags: ["database", "postgres"]);

A note on SELECT 1: It's the industry standard for this check — fast, universally supported, and harmless. Some purists argue it only verifies the connection, not whether the database is locked or whether the application user has write permissions. They're right. For most services, connectivity is enough. If you need deeper assurance, replace it with a lightweight query against a known table: SELECT TOP 1 1 FROM Orders WITH (NOLOCK). Just don't go overboard — a health check query that takes 500ms under load is worse than SELECT 1.

Redis Cache

dotnet add package AspNetCore.HealthChecks.Redis

builder.Services.AddHealthChecks()
    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded, // degraded, not unhealthy — cache miss is survivable
        tags: ["cache"]);

Notice I'm using Degraded here. If Redis is down, my app still works — it'll be slower, but it won't fail. This distinction matters for Kubernetes probes, as we'll see later.

External HTTP Dependencies

dotnet add package AspNetCore.HealthChecks.Uris

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        uri: new Uri("https://api.stripe.com/v1/"),
        name: "stripe-api",
        failureStatus: HealthStatus.Degraded,
        tags: ["external"]);

Writing a Custom Health Check

When a package doesn't exist for your dependency, write your own. It's straightforward:

public class OrderServiceHealthCheck : IHealthCheck
{
    private readonly IOrderRepository _orderRepository;

    public OrderServiceHealthCheck(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            var canConnect = await _orderRepository.CanConnectAsync(cancellationToken);

            if (!canConnect)
            {
                return HealthCheckResult.Unhealthy("Order repository is unreachable.");
            }

            var pendingOrders = await _orderRepository.GetPendingCountAsync(cancellationToken);

            // Degraded if queue is building up — not broken, but worth knowing
            if (pendingOrders > 10_000)
            {
                return HealthCheckResult.Degraded(
                    $"Order queue is growing: {pendingOrders} pending orders.",
                    data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
            }

            return HealthCheckResult.Healthy(
                data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(
                "Order service check threw an exception.",
                exception: ex);
        }
    }
}

builder.Services.AddHealthChecks()
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["orders", "database"]);

Disk Space

A check that's almost always missing — and that bites you at the worst moment:

public class DiskSpaceHealthCheck : IHealthCheck
{
    private readonly long _minimumFreeBytesThreshold;

    public DiskSpaceHealthCheck(long minimumFreeMegabytes = 500)
    {
        _minimumFreeBytesThreshold = minimumFreeMegabytes * 1024 * 1024;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var drive = DriveInfo.GetDrives()
            .FirstOrDefault(d => d.IsReady && d.Name == "/");

        if (drive is null)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy("Root drive not found."));
        }

        var freeBytes = drive.AvailableFreeSpace;
        var freeMb = freeBytes / (1024 * 1024);

        var data = new Dictionary<string, object>
        {
            ["free_mb"] = freeMb,
            ["total_mb"] = drive.TotalSize / (1024 * 1024)
        };

        if (freeBytes < _minimumFreeBytesThreshold)
        {
            return Task.FromResult(
                HealthCheckResult.Unhealthy($"Low disk space: {freeMb} MB free.", data: data));
        }

        if (freeBytes < _minimumFreeBytesThreshold * 2)
        {
            return Task.FromResult(
                HealthCheckResult.Degraded($"Disk space getting low: {freeMb} MB free.", data: data));
        }

        return Task.FromResult(HealthCheckResult.Healthy(data: data));
    }
}

Tagging Checks for Kubernetes Probes

This is where health checks go from useful to essential. Kubernetes uses three probes:

Probe	Purpose	Consequence if failing
Liveness	Is the process alive?	Restart the container
Readiness	Can it serve traffic?	Remove from load balancer
Startup	Has it finished starting up?	Don't check liveness/readiness yet

You don't want a slow Redis to restart your pod. You want it to stop receiving traffic until Redis recovers. Tags let you route different checks to different endpoints:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: connectionString,
        name: "sql-server",
        tags: ["ready"])                        // readiness only
    .AddRedis(
        redisConnectionString: redisConnection,
        name: "redis",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])                        // readiness only
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])                // both
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        tags: ["ready"]);                       // readiness only

Map separate endpoints filtered by tag:

// Liveness — only checks the process is alive and has disk space
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded still alive
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Readiness — checks everything needed to serve requests
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded can still serve
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Kubernetes configuration:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

startupProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30   # 30 * 5s = 150 seconds to start up

Rich JSON Responses

By default, the health endpoint returns plain text (Healthy, Degraded, Unhealthy). For monitoring dashboards and debugging, you want JSON:

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
});

static Task WriteHealthCheckResponse(HttpContext context, HealthReport report)
{
    context.Response.ContentType = "application/json";

    var response = new
    {
        status = report.Status.ToString(),
        duration = report.TotalDuration.TotalMilliseconds,
        checks = report.Entries.Select(e => new
        {
            name = e.Key,
            status = e.Value.Status.ToString(),
            description = e.Value.Description,
            duration = e.Value.Duration.TotalMilliseconds,
            data = e.Value.Data,
            exception = e.Value.Exception?.Message
        })
    };

    return context.Response.WriteAsync(
        JsonSerializer.Serialize(response, new JsonSerializerOptions
        {
            WriteIndented = true,
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
        }));
}

Output:

{
  "status": "Degraded",
  "duration": 142.5,
  "checks": [
    {
      "name": "sql-server",
      "status": "Healthy",
      "duration": 12.3,
      "data": {}
    },
    {
      "name": "redis",
      "status": "Degraded",
      "description": "Redis connection timeout after 5000ms",
      "duration": 5001.2,
      "data": {}
    },
    {
      "name": "disk-space",
      "status": "Healthy",
      "duration": 0.8,
      "data": {
        "free_mb": 42301,
        "total_mb": 102400
      }
    }
  ]
}

Adding a Timeout per Check

A health check that hangs is worse than one that fails fast. Add a timeout so a slow dependency doesn't block the entire health endpoint:

public class ExternalPaymentApiHealthCheck : IHealthCheck
{
    private readonly HttpClient _httpClient;

    public ExternalPaymentApiHealthCheck(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("payment-api");
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        cts.CancelAfter(TimeSpan.FromSeconds(3)); // never wait more than 3 seconds

        try
        {
            var response = await _httpClient.GetAsync("/ping", cts.Token);

            return response.IsSuccessStatusCode
                ? HealthCheckResult.Healthy()
                : HealthCheckResult.Degraded($"Payment API returned {(int)response.StatusCode}");
        }
        catch (OperationCanceledException)
        {
            return HealthCheckResult.Degraded("Payment API timed out after 3 seconds.");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Payment API unreachable.", ex);
        }
    }
}

Common Mistakes

Mistake 1: Exposing health check details publicly

The JSON response with database names, connection info hints, and exception messages shouldn't be public. I've seen exception stack traces leak connection strings through a public /health/detail endpoint. Restrict it.

The simplest option is filtering by host:

// Public endpoint — minimal response
app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = (ctx, report) =>
    {
        ctx.Response.ContentType = "text/plain";
        return ctx.Response.WriteAsync(report.Status.ToString());
    }
});

// Internal endpoint — full details, restricted by host
app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).RequireHost("*.internal.mycompany.com");

But in corporate environments with a Service Mesh like Istio, filtering by host can be unreliable — the mesh rewrites headers and internal routing makes RequireHost unpredictable. In those cases, a simple API key middleware is more robust:

app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).AddEndpointFilter(async (context, next) =>
{
    var config = context.HttpContext.RequestServices.GetRequiredService<IConfiguration>();
    var expectedKey = config["HealthChecks:ApiKey"];
    var providedKey = context.HttpContext.Request.Headers["X-Health-Key"].FirstOrDefault();

    if (string.IsNullOrEmpty(expectedKey) || providedKey != expectedKey)
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status401Unauthorized;
        return Results.Unauthorized();
    }

    return await next(context);
});

Store the key in your secrets manager, not in appsettings.json. Your monitoring tool sends it as a header. No network topology assumptions needed.

Mistake 2: Running expensive checks too frequently

Kubernetes probes can run every 5-10 seconds. A check that runs a full database query on every probe request adds load you don't need. Cache the result:

public class CachedDatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnectionFactory _factory;
    private HealthCheckResult _cachedResult = HealthCheckResult.Healthy();
    private DateTime _lastCheck = DateTime.MinValue;
    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(30);

    public CachedDatabaseHealthCheck(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (DateTime.UtcNow - _lastCheck < CacheDuration)
            return _cachedResult;

        try
        {
            await using var conn = await _factory.CreateConnectionAsync(cancellationToken);
            await conn.ExecuteAsync("SELECT 1");
            _cachedResult = HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            _cachedResult = HealthCheckResult.Unhealthy("Database check failed.", ex);
        }

        _lastCheck = DateTime.UtcNow;
        return _cachedResult;
    }
}

Mistake 3: Using the same endpoint for liveness and readiness

If your database is down and readiness returns 503, Kubernetes will also restart your pod if that same endpoint is used for liveness. You end up in a restart loop for a problem that has nothing to do with your process health. Always separate them.

Mistake 4: Not checking the things that actually fail

A health check that only verifies the process is running adds zero observability. Check the things that have actually caused incidents: the database, the message broker, the external APIs your service depends on, the file system if you write logs or uploads.

Best Practices

Name your checks clearly. sql-server, redis-cache, stripe-api — names that appear in logs and dashboards should be immediately recognizable.

Use Degraded generously. Not every problem is Unhealthy. A slow cache, a high queue depth, a non-critical external service being down — these deserve Degraded, not a pod restart.

Always include data in your results. Queue depth, free disk space, response times — the data dictionary in HealthCheckResult is your debugging surface when something goes wrong at 2am.

Test your health checks in staging. Deliberately take down your database and verify the readiness probe returns 503 and pods stop receiving traffic. Don't discover your health check doesn't work during an actual incident.

Register health checks as singletons or transient carefully. If your check holds state (like the cached result above), register it as a singleton. If it takes a scoped dependency like DbContext, register it as transient and resolve dependencies per-check execution.

Bonus: HealthCheck UI in Two Lines

If you want to impress a client or a manager with minimal effort, install the UI package:

dotnet add package AspNetCore.HealthChecks.UI
dotnet add package AspNetCore.HealthChecks.UI.InMemory.Storage

Configure it:

builder.Services.AddHealthChecksUI(options =>
{
    options.SetEvaluationTimeInSeconds(30); // poll every 30 seconds
    options.AddHealthCheckEndpoint("API", "/health/detail");
}).AddInMemoryStorage();

// After app.MapHealthChecks(...)
app.MapHealthChecksUI(options => options.UIPath = "/health-ui");

Navigate to /health-ui and you get a live dashboard showing the status of every check, historical trend, and response times — all generated from the JSON your endpoint already returns.

It's not something you'd expose publicly, but for internal dashboards, staging environments, or a demo to stakeholders it's genuinely useful. One caveat: AddInMemoryStorage resets history on restart. For persistent history use AspNetCore.HealthChecks.UI.SqlServer.Storage or the PostgreSQL equivalent.

Conclusion

A health endpoint that always returns 200 OK isn't a health check — it's a heartbeat. The difference matters at 2am when your database connection pool is exhausted, your Redis cluster is split-brained, or your disk is 98% full and nobody noticed.

The silent outage I described at the start? It cost us two hours of debugging because every signal said "healthy". Once we had real health checks in place, the next incident took ten minutes to diagnose — the Redis check was Degraded, the readiness probe had already removed that pod from rotation, and the logs had the exact connection timeout.

The setup takes an hour. The payoff is every incident after that.

One liveness endpoint — is the process worth keeping alive?
One readiness endpoint — is it ready to serve traffic right now?
Custom checks for every dependency that has caused an incident before
Rich JSON so you know why, not just that
And if you want bonus points with your team, the UI takes five minutes

Questions? Found an issue with the examples? Open an issue on GitHub.

IAsyncEnumerable in C#: Streaming Data Without Loading Everything into Memory

Adrián Bailador — Sun, 05 Apr 2026 11:38:54 +0000

My API crashed in production. 500,000 database records, a List, and a server with 8GB RAM. The math didn't work.

I spent two hours staring at the logs before I understood what happened. The fix took ten minutes. This is what I learned — and how it will save you the same headache.

The Problem We're Solving

I know, I know. You've written this a hundred times:

// ❌ The problem: 1 million records in memory
public async Task<List<LogEntry>> GetAllLogsAsync()
{
    return await _context.LogEntries.ToListAsync(); // Boom! Memory explosion
}

For a handful of records? Fine. But the day your dataset grows beyond what fits in RAM, that innocent ToListAsync() becomes a ticking bomb.

What Is IAsyncEnumerable?

Introduced in C# 8.0 (.NET Core 3.0), IAsyncEnumerable<T> lets you stream data asynchronously — processing items one by one as they arrive, without ever holding the full collection in memory. Think of it like reading a book page by page instead of photocopying the entire thing before you start.

// ✅ The solution: stream as data arrives
public IAsyncEnumerable<LogEntry> StreamLogsAsync()
{
    return _context.LogEntries.AsAsyncEnumerable(); // Memory-efficient
}

Production-Grade Patterns

These are the four patterns I reach for most often. Not theory — things I've actually shipped.

Pattern 1: Entity Framework Core Streaming

This is where most people start, and for good reason. If you have EF Core and a table that grows over time, you need this pattern sooner or later.

public class LogRepository
{
    private readonly AppDbContext _context;

    public LogRepository(AppDbContext context)
    {
        _context = context;
    }

    /// <summary>
    /// Streams logs matching criteria without loading all into memory.
    /// WARNING: Do NOT use with OrderBy/Limit without careful consideration.
    /// </summary>
    public async IAsyncEnumerable<LogEntry> StreamLogsAsync(
        DateTime from,
        DateTime to,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var log in _context.LogEntries
            .Where(l => l.Timestamp >= from && l.Timestamp <= to)
            .AsAsyncEnumerable()
            .WithCancellation(ct))
        {
            yield return log;
        }
    }

    /// <summary>
    /// Chunks large exports to prevent connection timeouts.
    /// </summary>
    public async IAsyncEnumerable<IReadOnlyList<LogEntry>> StreamBatchedLogsAsync(
        int batchSize = 1000,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        var query = _context.LogEntries
            .OrderBy(l => l.Id)
            .AsAsyncEnumerable();

        var batch = new List<LogEntry>(batchSize);

        await foreach (var log in query.WithCancellation(ct))
        {
            batch.Add(log);

            if (batch.Count >= batchSize)
            {
                yield return batch.ToList();
                batch.Clear();
            }
        }

        // Don't forget the partial batch
        if (batch.Count > 0)
        {
            yield return batch;
        }
    }
}

Pattern 2: HttpClient Streaming with JSON

Third-party APIs that return thousands of records in a single response are surprisingly common. Without streaming, you buffer the entire response before deserializing a single object. HttpCompletionOption.ResponseHeadersRead is the line that changes everything here — don't forget it.

public class StreamingApiClient
{
    private readonly HttpClient _httpClient;
    private readonly JsonSerializerOptions _jsonOptions;

    public StreamingApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _jsonOptions = new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
            DefaultBufferSize = 4096 // Tune for your payload size
        };
    }

    /// <summary>
    /// Streams items from an NDJSON endpoint.
    /// Each line is a separate JSON object.
    /// </summary>
    public async IAsyncEnumerable<T> StreamFromNdJsonAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url, 
            HttpCompletionOption.ResponseHeadersRead, // Critical: stream, don't buffer
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);
        using var reader = new StreamReader(stream, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            if (string.IsNullOrWhiteSpace(line))
                continue;

            // Deserialize each line independently
            var item = JsonSerializer.Deserialize<T>(line, _jsonOptions);

            if (item != null)
                yield return item;
        }
    }

    /// <summary>
    /// Streams using System.Text.Json's built-in async deserialization.
    /// Requires JSON array format: [{}, {}, {}]
    /// </summary>
    public async IAsyncEnumerable<T> StreamJsonArrayAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url,
            HttpCompletionOption.ResponseHeadersRead,
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);

        await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
            stream, 
            _jsonOptions, 
            ct))
        {
            if (item != null)
                yield return item;
        }
    }
}

Pattern 3: File Processing Pipeline

CSV imports, log analysis, data migrations — anything that reads a file line by line and does something with each row. The key insight here is that you can chain multiple IAsyncEnumerable<T> methods into a pipeline where memory stays flat regardless of file size.

public class LogFileProcessor
{
    /// <summary>
    /// Reads, transforms, and writes logs in a streaming pipeline.
    /// Memory usage stays constant regardless of file size.
    /// </summary>
    public async IAsyncEnumerable<ProcessedLog> ProcessLogFileAsync(
        string filePath,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var rawLog in ReadLinesAsync(filePath, ct))
        {
            // Transform on the fly - no memory buildup
            if (TryParseLog(rawLog, out var parsed))
            {
                var enriched = await EnrichLogAsync(parsed, ct);
                yield return enriched;
            }
        }
    }

    private static async IAsyncEnumerable<string> ReadLinesAsync(
        string path,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var reader = new StreamReader(path, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            yield return line;
        }
    }

    private static bool TryParseLog(string raw, out ParsedLog parsed)
    {
        // Your parsing logic here
        parsed = default!;
        return true;
    }

    private static async Task<ProcessedLog> EnrichLogAsync(
        ParsedLog log, 
        CancellationToken ct)
    {
        // Async enrichment (e.g., lookup user info)
        await Task.Delay(1, ct); // Simulate async work
        return new ProcessedLog(log);
    }
}

public record ParsedLog(string Timestamp, string Level, string Message);
public record ProcessedLog(ParsedLog Original);

Pattern 4: Controller Action with Streaming Response

ASP.NET Core handles IAsyncEnumerable<T> return types natively — it serializes as NDJSON and starts sending data to the client immediately. The client doesn't wait for the full dataset; it starts receiving records as soon as the first one is ready.

[ApiController]
[Route("api/[controller]")]
public class ReportsController : ControllerBase
{
    private readonly IReportService _reportService;

    public ReportsController(IReportService reportService)
    {
        _reportService = reportService;
    }

    /// <summary>
    /// Streams CSV data directly to the client.
    /// Client starts receiving data immediately, no server buffering.
    /// </summary>
    [HttpGet("export")]
    public IAsyncEnumerable<ReportRow> ExportData(
        [FromQuery] DateTime from,
        [FromQuery] DateTime to,
        CancellationToken ct)
    {
        // ASP.NET Core automatically serializes IAsyncEnumerable as NDJSON
        // or use custom formatting for CSV
        return _reportService.StreamReportAsync(from, to, ct);
    }

    /// <summary>
    /// Custom streaming for Server-Sent Events (SSE).
    /// </summary>
    [HttpGet("live-events")]
    public async IAsyncEnumerable<ServerSentEvent> GetLiveEvents(
        [EnumeratorCancellation] CancellationToken ct)
    {
        await foreach (var evt in _reportService.SubscribeToEventsAsync(ct))
        {
            yield return new ServerSentEvent
            {
                Id = evt.Id,
                Event = evt.Type,
                Data = JsonSerializer.Serialize(evt.Payload)
            };
        }
    }
}

public record ReportRow(string Id, string Name, decimal Value);
public record ServerSentEvent(string Id, string Event, string Data);

Before vs After: Performance Comparison

Let's make it concrete. Same data, same operation, two approaches.

The Old Way: List (Before)

public async Task<List<LargeRecord>> ProcessAllRecordsAsync()
{
    // Memory: O(n) - grows with dataset size
    // Time to first result: O(n) - wait for all
    var allRecords = await _repository.GetAllAsync();

    var processed = new List<LargeRecord>();
    foreach (var record in allRecords)
    {
        processed.Add(await ProcessAsync(record));
    }

    return processed;
}

// Usage - memory spikes here
var results = await ProcessAllRecordsAsync();
foreach (var item in results)
{
    await WriteToDiskAsync(item);
}

1M records at 100KB each — what actually happens:

Peak Memory: ~95 GB (yes, gigabytes)
Time to first output: 45 seconds of waiting
Result: OutOfMemoryException — your server gives up before you do

The New Way: IAsyncEnumerable (After)

public async IAsyncEnumerable<LargeRecord> ProcessAllRecordsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    // Memory: O(1) - constant regardless of dataset size
    // Time to first result: O(1) - immediate streaming
    await foreach (var record in _repository.StreamAllAsync(ct))
    {
        yield return await ProcessAsync(record);
    }
}

// Usage - constant memory footprint
await foreach (var item in ProcessAllRecordsAsync().WithCancellation(ct))
{
    await WriteToDiskAsync(item);
}

Same 1M records — completely different story:

Peak Memory: ~150 MB (constant, regardless of dataset size)
Time to first output: 50ms — the client starts receiving data almost instantly
Result: Smooth streaming, server stays healthy

BenchmarkDotNet Results

Common Errors and How to Fix Them

I've made every single one of these. You don't have to.

Error 1: Forgetting CancellationToken

// ❌ Bad: No way to cancel mid-stream
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _source.GetAsync())
    {
        yield return item; // Can't cancel this!
    }
}

// ✅ Good: Always include cancellation support
public async IAsyncEnumerable<Item> GetItemsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.GetAsync().WithCancellation(ct))
    {
        yield return item;
    }
}

Error 2: Buffering with ToListAsync()

// ❌ Bad: You just defeated the purpose
public async Task<List<Item>> GetItemsAsync() // Returns List<T>, not IAsyncEnumerable
{
    var items = new List<Item>();
    await foreach (var item in _source.GetAsync())
    {
        items.Add(item);
    }
    return items;
}

// ✅ Good: Return IAsyncEnumerable<T> directly
public IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    return _source.GetAsync(); // Stream through
}

Error 3: Disposing Resources Too Early

// ❌ Bad: reader disposed before streaming completes
public async IAsyncEnumerable<string> ReadFileAsync(string path)
{
    using var reader = new StreamReader(path); // Disposed on first yield!

    while (await reader.ReadLineAsync() is { } line)
    {
        yield return line; // reader is already disposed
    }
}

// ✅ Good: Keep scope alive
public async IAsyncEnumerable<string> ReadFileAsync(
    string path,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    using var reader = new StreamReader(path);

    try
    {
        while (await reader.ReadLineAsync(ct) is { } line)
        {
            yield return line;
        }
    }
    finally
    {
        // reader disposed when iteration completes or breaks
    }
}

Error 4: Not Configuring DbContext Lifetime

// ❌ Bad: Scoped DbContext disposed mid-stream in ASP.NET Core
[HttpGet("stream")]
public async IAsyncEnumerable<Order> GetOrders()
{
    var db = _serviceProvider.GetRequiredService<OrderDbContext>();
    // db will be disposed after the action method returns!

    await foreach (var order in db.Orders.AsAsyncEnumerable())
    {
        yield return order; // DbContext disposed here
    }
}

// ✅ Good: Use factory pattern for streaming
public class StreamingOrderService
{
    private readonly IDbContextFactory<OrderDbContext> _contextFactory;

    public async IAsyncEnumerable<Order> StreamOrdersAsync(
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await using var db = await _contextFactory.CreateDbContextAsync(ct);

        await foreach (var order in db.Orders.AsAsyncEnumerable().WithCancellation(ct))
        {
            yield return order;
        }
        // DbContext properly disposed when iteration completes
    }
}

Error 5: Ignoring Transaction Timeouts

// ❌ Bad: Long-running query may timeout
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _context.Items.AsAsyncEnumerable())
    {
        yield return item; // Connection held open indefinitely
    }
}

// ✅ Good: Set explicit command timeout
public async IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    _context.Database.SetCommandTimeout(TimeSpan.FromMinutes(5));

    await foreach (var item in _context.Items.AsAsyncEnumerable().WithCancellation(ct))
    {
        yield return item;
    }
}

Best Practices

A few rules I now follow without thinking.

1. Always Accept CancellationToken

public async IAsyncEnumerable<T> StreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.WithCancellation(ct))
    {
        ct.ThrowIfCancellationRequested(); // Optional: check between operations
        yield return await TransformAsync(item, ct);
    }
}

2. Use WithCancellation in Callers

await foreach (var item in service.StreamAsync().WithCancellation(ct))
{
    // Proper cancellation propagation
}

3. Configure JSON Buffer Sizes for HttpClient

var options = new JsonSerializerOptions
{
    DefaultBufferSize = 8192 // Adjust based on average payload size
};

await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
    stream, options, ct))
{
    // Optimal memory usage
}

4. Add Backpressure with ConfigureAwait

await foreach (var item in source.ConfigureAwait(false))
{
    // false reduces context switching in high-throughput scenarios
    await SlowOperationAsync(item).ConfigureAwait(false);
}

5. Use IAsyncDisposable for Resource Cleanup

public async IAsyncEnumerable<byte[]> StreamFileChunksAsync(
    string path,
    int chunkSize = 8192,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await using var fs = new FileStream(
        path, 
        FileMode.Open, 
        FileAccess.Read, 
        FileShare.Read,
        bufferSize: chunkSize, 
        useAsync: true);

    var buffer = new byte[chunkSize];
    int bytesRead;

    while ((bytesRead = await fs.ReadAsync(buffer, ct)) > 0)
    {
        yield return buffer.AsSpan(0, bytesRead).ToArray();
    }
}

6. Batch When Individual Items Are Too Small

public async IAsyncEnumerable<IReadOnlyList<T>> StreamBatchesAsync<T>(
    int batchSize = 100,
    [EnumeratorCancellation] CancellationToken ct = default)
    where T : class
{
    var batch = new List<T>(batchSize);

    await foreach (var item in _context.Set<T>().AsAsyncEnumerable().WithCancellation(ct))
    {
        batch.Add(item);

        if (batch.Count >= batchSize)
        {
            yield return batch;
            batch = new List<T>(batchSize);
        }
    }

    if (batch.Count > 0)
    {
        yield return batch;
    }
}

Conclusion

The mental shift is simple once it clicks:

Before: Load everything → Process everything → Return everything
After: Stream one item → Process it → Move to the next

That's it. No magic, no complex setup. Just a different way of thinking about data flow.

Reach for IAsyncEnumerable when:

✅ You're exporting database records by the thousands
✅ You're processing large files (CSV, logs, JSON dumps)
✅ You're consuming a streaming API
✅ Memory is a real concern on your server

Stick with List when:

❌ Your dataset is small (under ~1,000 items) — the overhead isn't worth it
❌ You need random access or multiple iterations
❌ You're chaining complex LINQ operations that don't support streaming

The 95% memory reduction I got wasn't theoretical. It was the difference between a service that crashed under load and one that handled the same data without breaking a sweat. Start with your EF Core queries and API clients — that's where you'll feel the impact immediately.

🚀 Big update drop for The Coffee Timer! ☕

Adrián Bailador — Mon, 30 Mar 2026 19:00:00 +0000

I've been heads-down building new features and polishing the experience — Here's what's new:

☕ Redesigned coffee cup: A fully SVG-based ceramic mug with realistic porcelain gradients, a 3D handle, crema/foam with latte art details, and smooth steam animations. It even fills up as your The Coffee Timer session progresses.

🎵 Spotify integration (Premium) Connect your Spotify account and play playlists, songs, or artists directly inside the app while you focus. Full search + library browsing — no need to switch tabs.

🔔 Background push notifications: The timer now sends a system notification even when the tab is closed or minimised. Never miss the end of a session again.

📱 Mobile responsiveness overhaul: Bigger touch targets, responsive layouts, no more overflow on small screens. The app now feels at home on any device.

⚡ Instant premium status Subscription state loads from cache instantly — no more waiting spinner before the UI unlocks.

🔒 Smart feature gating Non-premium users see a teaser of the Spotify player (blurred, with a lock icon) to show what they're missing. Guests get a "Sign in to unlock" CTA, and free users get "Upgrade to Premium".

The Coffee Timer is a productivity app built with React + TypeScript, .NET backend, Supabase, and Stripe — designed to make focused work feel a little more enjoyable.

https://thecoffeetimer.com/

If you want to try it or give feedback, drop a comment 👇

How I Fixed Supabase Rate Limiting in Production

Adrián Bailador — Sat, 28 Mar 2026 22:21:30 +0000

The Coffee Timer was hitting Supabase's rate limits in production. Here's the exact problem, why it happened, and the four-part fix that solved it.

The Problem: Frontend Calling Supabase Directly

The Coffee Timer is a subscription-based web app. The original architecture was straightforward — the frontend called Supabase directly for everything: authentication, subscription checks, feature flags, and data reads. It worked fine in development and in early production with a small user base.

Then it didn't.

Under real load, the frontend was making multiple Supabase calls per page render. A logged-in user opening the app would trigger:

A call to fetch the user profile
A call to check subscription status
A call to load their saved timers
A call to fetch feature flags

That's four Supabase requests for a single page load. Multiply that by concurrent users refreshing the app, and you hit HTTP 429 — Too Many Requests — fast.

POST https://[project].supabase.co/rest/v1/rpc/check_subscription
→ 429 Too Many Requests
Retry-After: 60

The UI would hang, subscriptions appeared as expired, and users were getting locked out of features they had paid for. Not great.

Understanding Supabase Rate Limits

Supabase rate limits operate at several levels. The ones that matter most for this problem are:

REST API requests per second — per project, across all clients
Auth requests per hour — per IP and per user
Realtime connections — concurrent subscriptions

The key insight is that Supabase is designed for moderate, server-side usage — not to act as a direct database connection from thousands of browser tabs. When you call Supabase directly from the frontend, every user's browser is a separate client hammering the same rate limit pool.

The fix is architectural: the browser should not be the one talking to Supabase for anything critical.

Fix 1 — Move Critical Operations to the .NET Backend

The most impactful change was moving subscription checks and write operations off the frontend and behind a .NET API. The browser now calls my API, and the API calls Supabase with a service-level key. One server-to-server connection, not hundreds of browser-to-Supabase connections.

// SubscriptionService.cs
public class SubscriptionService
{
    private readonly SupabaseClient _supabase;
    private readonly ILogger<SubscriptionService> _logger;

    public SubscriptionService(SupabaseClient supabase, ILogger<SubscriptionService> logger)
    {
        _supabase = supabase;
        _logger = logger;
    }

    public async Task<SubscriptionStatus> GetSubscriptionStatusAsync(string userId)
    {
        var response = await _supabase
            .From<Subscription>()
            .Where(s => s.UserId == userId && s.IsActive)
            .Single();

        if (response is null)
            return SubscriptionStatus.Free;

        return response.Plan switch
        {
            "pro"        => SubscriptionStatus.Pro,
            "enterprise" => SubscriptionStatus.Enterprise,
            _            => SubscriptionStatus.Free
        };
    }
}

The API endpoint the frontend calls:

[ApiController]
[Route("api/[controller]")]
[Authorize]
public class SubscriptionController : ControllerBase
{
    private readonly SubscriptionService _subscriptionService;

    public SubscriptionController(SubscriptionService subscriptionService)
    {
        _subscriptionService = subscriptionService;
    }

    [HttpGet("status")]
    public async Task<IActionResult> GetStatus()
    {
        var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
        if (userId is null) return Unauthorized();

        var status = await _subscriptionService.GetSubscriptionStatusAsync(userId);
        return Ok(new { status = status.ToString().ToLower() });
    }
}

The frontend now makes one call to GET /api/subscription/status, which returns a clean response. Supabase never sees the browser again for subscription checks.

A note on the Supabase .NET SDK: The official supabase-csharp SDK works, but it is not as actively maintained as the JavaScript client, and its fluent query API has known edge cases around complex filters and RPC deserialization. For production backends, you may want to fall back to a raw HttpClient against Supabase's REST endpoint — it is more explicit, easier to debug, and not subject to SDK-level bugs. I use the SDK for simple CRUD operations but switch to HttpClient for anything involving RPCs or custom headers.

Fix 2 — Use Supabase RPCs for Batched Operations

Even with the backend in place, there were still cases where a single operation needed to read and write across multiple tables. Doing that as separate sequential calls from the backend still generates N requests to Supabase.

The solution is Supabase RPCs — PostgreSQL functions exposed as a single HTTP call. Instead of three reads and a write, one function call handles the entire operation atomically.

-- Supabase SQL editor: create the function
CREATE OR REPLACE FUNCTION get_user_dashboard(p_user_id UUID)
RETURNS JSON
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
    result JSON;
BEGIN
    SELECT json_build_object(
        'subscription', (
            SELECT row_to_json(s)
            FROM subscriptions s
            WHERE s.user_id = p_user_id AND s.is_active = true
            LIMIT 1
        ),
        'timers', (
            SELECT json_agg(t)
            FROM timers t
            WHERE t.user_id = p_user_id
            ORDER BY t.updated_at DESC
            LIMIT 20
        ),
        'feature_flags', (
            SELECT json_agg(f)
            FROM feature_flags f
            WHERE f.user_id = p_user_id OR f.is_global = true
        )
    ) INTO result;

    RETURN result;
END;
$$;

Calling the RPC from the .NET backend:

public async Task<DashboardData> GetDashboardAsync(string userId)
{
    var response = await _supabase
        .Rpc("get_user_dashboard", new { p_user_id = userId });

    if (response.ResponseMessage?.IsSuccessStatusCode != true)
    {
        _logger.LogError("RPC get_user_dashboard failed for user {UserId}", userId);
        throw new InvalidOperationException("Failed to load dashboard data.");
    }

    return JsonSerializer.Deserialize<DashboardData>(response.Content!)
        ?? throw new InvalidOperationException("Empty response from dashboard RPC.");
}

One HTTP call to Supabase replaces three. The function runs inside the database — no network round-trips between tables.

Security note: SECURITY DEFINER means the function runs with the privileges of the function creator, not the caller. This is appropriate here because the backend uses a service-level key and the call never reaches the frontend. However, if you ever expose an RPC directly from the frontend, SECURITY DEFINER bypasses Row Level Security — validate p_user_id against auth.uid() explicitly inside the function body in that case, or switch to SECURITY INVOKER and rely on RLS policies instead.

When not to use RPCs: RPCs are great for batching reads or encapsulating complex transactional logic. They're not ideal for operations that need to be easily unit-tested or debugged in isolation. Use them selectively — one RPC for the dashboard load makes sense; one RPC for every operation in your app creates a maintenance burden.

Fix 3 — Add Server-Side Caching with IMemoryCache

A client-side cache eliminates redundant calls per user. But it doesn't help when many users are doing their first load simultaneously — each of their requests still hits Supabase independently from the backend.

The missing layer is a server-side cache using IMemoryCache. Subscription status is the same answer for a given user regardless of which request fetches it. Caching it on the backend means that 50 concurrent logins don't generate 50 Supabase calls — they generate one, and the rest are served from memory.

// Program.cs
builder.Services.AddMemoryCache();

// SubscriptionService.cs
public class SubscriptionService
{
    private readonly SupabaseClient _supabase;
    private readonly IMemoryCache _cache;
    private readonly ILogger<SubscriptionService> _logger;

    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(1);

    public SubscriptionService(
        SupabaseClient supabase,
        IMemoryCache cache,
        ILogger<SubscriptionService> logger)
    {
        _supabase = supabase;
        _cache = cache;
        _logger = logger;
    }

    public async Task<SubscriptionStatus> GetSubscriptionStatusAsync(string userId)
    {
        var cacheKey = $"subscription:{userId}";

        if (_cache.TryGetValue(cacheKey, out SubscriptionStatus cached))
            return cached;

        var response = await _supabase
            .From<Subscription>()
            .Where(s => s.UserId == userId && s.IsActive)
            .Single();

        var status = response?.Plan switch
        {
            "pro"        => SubscriptionStatus.Pro,
            "enterprise" => SubscriptionStatus.Enterprise,
            _            => SubscriptionStatus.Free
        };

        _cache.Set(cacheKey, status, CacheTtl);
        return status;
    }

    public void InvalidateCache(string userId)
    {
        _cache.Remove($"subscription:{userId}");
    }
}

Always get the userId from the authenticated JWT claim — never from the request body — when invalidating the cache. Accepting a userId from the client would allow one user to invalidate another user's cache entry:

// ✅ userId comes from the JWT, not from the request body
[HttpPost("checkout/complete")]
public async Task<IActionResult> CompleteCheckout([FromBody] CheckoutRequest request)
{
    var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
    if (userId is null) return Unauthorized();

    await _checkoutService.ProcessAsync(request.SessionId);
    _subscriptionService.InvalidateCache(userId);
    return Ok();
}

IMemoryCache vs IDistributedCache: IMemoryCache is process-local — if you run multiple backend instances behind a load balancer, each instance has its own cache and a user might hit a stale entry on a different node. For single-instance deployments (like Render's free/starter tier), IMemoryCache is fine. If you scale horizontally, switch to IDistributedCache backed by Redis to share cache state across instances.

Fix 4 — Cache Subscription State in localStorage with a TTL

Even with server-side caching, the browser still makes one API call per page load per user. For a subscription status that doesn't change often, that's unnecessary. A client-side cache in localStorage eliminates redundant calls for users navigating within the app.

// subscriptionCache.ts
const CACHE_KEY = "subscription_status";
const TTL_MS = 60 * 1000; // 1 minute

interface CachedSubscription {
  status: string;
  cachedAt: number;
}

export function getCachedSubscription(): string | null {
  try {
    const raw = localStorage.getItem(CACHE_KEY);
    if (!raw) return null;

    const cached: CachedSubscription = JSON.parse(raw);
    const age = Date.now() - cached.cachedAt;

    if (age > TTL_MS) {
      localStorage.removeItem(CACHE_KEY);
      return null;
    }

    return cached.status;
  } catch {
    localStorage.removeItem(CACHE_KEY);
    return null;
  }
}

export function setCachedSubscription(status: string): void {
  const entry: CachedSubscription = {
    status,
    cachedAt: Date.now(),
  };
  localStorage.setItem(CACHE_KEY, JSON.stringify(entry));
}

export function invalidateSubscriptionCache(): void {
  localStorage.removeItem(CACHE_KEY);
}

Using it when loading the app:

// useSubscription.ts
export async function getSubscriptionStatus(): Promise<string> {
  // Return cached value if still fresh
  const cached = getCachedSubscription();
  if (cached) return cached;

  // Fetch from backend, not Supabase directly
  const response = await fetch("/api/subscription/status", {
    headers: { Authorization: `Bearer ${await getAuthToken()}` },
  });

  if (!response.ok) throw new Error("Failed to fetch subscription status.");

  const { status } = await response.json();
  setCachedSubscription(status);
  return status;
}

Invalidate the cache whenever the subscription actually changes — on checkout completion, on plan upgrade, on logout:

// After a successful checkout
await completeCheckout(sessionId);
invalidateSubscriptionCache(); // Force fresh fetch on next load

Why 1 minute? The TTL is a balance between freshness and request volume. Too short (< 30s) and you still trigger frequent fetches for users navigating quickly. Too long (> 5min) and a user who just upgraded won't see their new features without a manual refresh. One minute means a subscription change feels near-instant while eliminating redundant calls under normal usage. If your use case needs faster propagation, consider pushing subscription changes to the client via a WebSocket and invalidating the cache explicitly — rather than shortening the TTL.

Important caveat: The localStorage cache means a user who cancels their subscription may continue to see Pro features for up to 1 minute on the client, until the TTL expires. This is an acceptable trade-off for most SaaS apps — the backend enforces the real access control, and client-side UI state catching up within 60 seconds is not a meaningful security gap. However, if you need stricter enforcement (e.g. metered API access or high-value feature gating), shorten the TTL or push subscription changes via WebSocket rather than relying on TTL expiry.

The Result: Before and After

Before:

4 direct Supabase REST calls per page load, from every browser tab
~120 Supabase requests/minute at peak with ~30 concurrent active users
429 errors appearing consistently above ~25 concurrent users
Subscription checks failing 8–12% of requests during busy periods
Median time-to-interactive: ~1,400ms (waiting on sequential Supabase calls)

After:

0 direct Supabase calls from the browser
Backend makes 1 RPC call to Supabase per cache miss — most page loads served from IMemoryCache
Supabase request volume dropped ~85% at equivalent user load
429 errors: eliminated
Median time-to-interactive: ~310ms (single backend call, mostly cache hits)

The Supabase dashboard's API usage graph made the change visible immediately — the spike pattern on every deployment flattened out the same day the caching layers went live.

Common Mistakes to Avoid

Calling Supabase directly from the frontend for subscription or billing checks
Subscription status is both critical and sensitive. It should never be computed or fetched client-side. A user can intercept and modify the response from a direct Supabase call. Route it through your backend where you control validation.

Not invalidating the cache after state changes
If you cache subscription status but forget to invalidate it after checkout, users will complete a payment and still see themselves on the free plan until the TTL expires. Always call invalidateSubscriptionCache() on any action that changes subscription state.

// ❌ Forgot to invalidate — user sees stale Free status after upgrading
await processUpgrade(userId);

// ✅ Invalidate immediately after the state change
await processUpgrade(userId);
invalidateSubscriptionCache();

Caching on the frontend but not on the backend
A localStorage cache eliminates redundant calls per user. It does nothing for simultaneous first-time loads. Without IMemoryCache on the backend, 50 users logging in at the same time still generate 50 Supabase calls. Both layers are necessary.

Using a short TTL as a substitute for proper cache invalidation
A 5-second TTL is not a caching strategy — it's a polling strategy with extra steps. Either cache with a meaningful TTL and invalidate on change, or don't cache at all.

// ❌ 5-second TTL — you're just polling Supabase every 5 seconds
const TTL_MS = 5 * 1000;

// ✅ 1-minute TTL + explicit invalidation on subscription change
const TTL_MS = 60 * 1000;

Sharing a service-level Supabase key in the frontend
The backend uses a service role key that bypasses Row Level Security. This key must never be exposed to the browser. Keep it server-side in environment variables.

// appsettings.json (server-side only)
{
  "Supabase": {
    "Url": "https://[project].supabase.co",
    "ServiceKey": "eyJ..."  // Never expose this in frontend code
  }
}

Best Practices

Never call Supabase directly from the browser for subscription, billing, or access control. These operations belong in your backend.
Use RPCs to batch related reads into a single HTTP call. Fewer calls = fewer chances to hit rate limits.
Add server-side caching with IMemoryCache for any data that is expensive to fetch and doesn't change per-request. It protects against burst load, not just steady-state traffic.
Cache on the client too, but only for non-sensitive UI state like subscription tier. Always enforce real access control on the backend.
Always invalidate both caches on state changes — the server-side cache and the localStorage cache — not just let the TTL expire.
Always derive userId from the JWT claim on the server, never from the request body, when performing sensitive operations like cache invalidation.
Use the Supabase service role key only on the backend. The frontend should use the anonymous key scoped to RLS policies.
Monitor your Supabase project's rate limit usage in the dashboard. Set up alerts before you hit limits, not after.
If you scale horizontally, switch IMemoryCache to IDistributedCache backed by Redis to avoid stale cache entries across instances.

Conclusion

Rate limiting is not a Supabase problem — it's an architecture problem. Supabase is a hosted service with usage boundaries, and calling it directly from every browser tab treats it like a local database. It isn't.

The fix for The Coffee Timer came down to four things: move critical operations to the backend, reduce the number of calls using RPCs, cache aggressively on the server with IMemoryCache, and add a client-side TTL cache as a last-mile optimization. None of these are complex changes, but together they eliminated 429 errors entirely, cut Supabase request volume by ~85%, and reduced time-to-interactive by more than 4x.

If your frontend is calling Supabase directly for anything that matters — subscription status, access control, billing — move it to your backend. Then cache it. The sooner, the better.

What Your .NET Exceptions Are Telling Attackers (And How to Stop It)

Adrián Bailador — Fri, 20 Mar 2026 21:08:58 +0000

How unhandled exceptions leak stack traces, connection strings, and internal architecture — and how to fix it properly in ASP.NET Core.

Introduction: The Exception That Becomes a Roadmap

Imagine you're building an API. A developer forgets to handle an edge case, and a request triggers an unhandled exception. What does the caller see?

In a default ASP.NET Core project in development mode, they see something like this:

System.NullReferenceException: Object reference not set to an instance of an object.
   at MyApi.Services.OrderService.GetOrderAsync(Int32 id)
      in /home/runner/work/MyApi/src/Services/OrderService.cs:line 47
   at MyApi.Controllers.OrdersController.GetOrder(Int32 id)
      in /home/runner/work/MyApi/src/Controllers/OrdersController.cs:line 23
   at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor...

ConnectionString: Server=prod-db.internal;Database=orders;User=sa;Password=Sup3rS3cr3t!

That response just told an attacker:

Your internal folder structure and project layout
The exact class and method where the error occurred
Your database server hostname
Your database credentials

This isn't hypothetical. Error responses are one of the most common sources of information disclosure in web APIs — and one of the easiest to fix.

What Attackers Learn from Your Exceptions

Different types of exceptions leak different types of information. Understanding what gets exposed helps prioritise what to fix first.

Stack Traces — Your Internal Architecture

A stack trace reveals the exact call chain inside your application. Attackers use this to understand how your code is structured, what libraries you use, and where to look for known vulnerabilities.

System.Data.SqlClient.SqlException: Invalid column name 'user_id'.
   at System.Data.SqlClient.SqlConnection.OnError(...)
   at MyApi.Repositories.UserRepository.FindByEmailAsync(String email)
   at MyApi.Services.AuthService.LoginAsync(LoginRequest request)

From this single exception, an attacker now knows:

You're using SQL Server (SqlClient)
A column is named user_id — useful for SQL injection attempts
Your authentication flow goes through AuthService.LoginAsync

Database Errors — Your Schema

Database exceptions are particularly dangerous because they expose table names, column names, and sometimes the exact query that failed.

Microsoft.EntityFrameworkCore.DbUpdateException:
An error occurred while saving the entity changes.
Table 'orders_db.dbo.CustomerPayments' doesn't exist.

Table names and database names are handed to the attacker on a silver platter.

Validation Errors — Your Business Rules

Even seemingly harmless validation errors can expose internal logic:

FluentValidation.ValidationException:
  -- OrderId: Order ID must be between 100000 and 999999. Severity: Error
  -- CustomerId: Customer must have a verified account with status 'Premium' or 'Enterprise'.

Now the attacker knows your ID ranges, your account tiers, and the status values your system uses internally.

The Fix: Global Exception Handling Middleware

The most important step is ensuring that no raw exception ever reaches the client in production. ASP.NET Core provides two clean ways to do this.

Option 1: UseExceptionHandler (Built-in)

For most APIs, the built-in UseExceptionHandler is the right starting point:

// Program.cs
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage(); // Full details in development only
}
else
{
    app.UseExceptionHandler("/error"); // Safe response in production
}

Add a dedicated error endpoint:

[ApiController]
public class ErrorController : ControllerBase
{
    [Route("/error")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public IActionResult HandleError()
    {
        return Problem(
            title: "An unexpected error occurred.",
            statusCode: StatusCodes.Status500InternalServerError
        );
    }
}

This returns a standardised RFC 7807 Problem Details response with no internal information:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "An unexpected error occurred.",
  "status": 500
}

Option 2: Custom Middleware (More Control)

For more control over logging, correlation IDs, and response shaping, write your own middleware:

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(
        RequestDelegate next,
        ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex);
        }
    }

    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        var correlationId = context.TraceIdentifier;

        // Log the full exception internally — never lose observability
        _logger.LogError(exception,
            "Unhandled exception. CorrelationId: {CorrelationId}, Path: {Path}",
            correlationId,
            context.Request.Path);

        var (statusCode, title) = exception switch
        {
            UnauthorizedAccessException => (401, "Unauthorised."),
            KeyNotFoundException        => (404, "Resource not found."),
            ArgumentException           => (400, "Invalid request."),
            _                           => (500, "An unexpected error occurred.")
        };

        context.Response.StatusCode = statusCode;
        context.Response.ContentType = "application/problem+json";

        // Return safe response — correlation ID allows support to look up the real error
        var problem = new
        {
            type    = "https://httpstatuses.com/" + statusCode,
            title   = title,
            status  = statusCode,
            traceId = correlationId   // Safe: links to logs without exposing details
        };

        await context.Response.WriteAsJsonAsync(problem);
    }
}

app.UseMiddleware<ExceptionHandlingMiddleware>();

The correlationId in the response is the key insight here: the client gets a reference they can provide to support, while you can look up the full exception in your logs. No information leakage, full observability.

Option 3: IExceptionHandler (ASP.NET Core 8+ — The Modern Approach)

If you're on .NET 8 or later, skip writing middleware from scratch. The IExceptionHandler interface is the clean, officially supported way to handle exceptions globally:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var correlationId = httpContext.TraceIdentifier;

        _logger.LogError(exception,
            "Unhandled exception. CorrelationId: {CorrelationId}, Path: {Path}",
            correlationId,
            httpContext.Request.Path);

        var (statusCode, title) = exception switch
        {
            UnauthorizedAccessException => (401, "Unauthorised."),
            KeyNotFoundException        => (404, "Resource not found."),
            ArgumentException           => (400, "Invalid request."),
            _                           => (500, "An unexpected error occurred.")
        };

        httpContext.Response.StatusCode = statusCode;

        var problem = new ProblemDetails
        {
            Title  = title,
            Status = statusCode,
            Extensions = { ["traceId"] = correlationId }
        };

        await httpContext.Response.WriteAsJsonAsync(problem, cancellationToken);

        // Return true = exception is handled, pipeline stops here
        // Return false = pass to the next handler in the chain
        return true;
    }
}

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// ...

app.UseExceptionHandler();

You can register multiple handlers in order — useful when you want different handlers for domain exceptions vs unexpected errors:

builder.Services.AddExceptionHandler<DomainExceptionHandler>();   // handles first
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();   // fallback

If a handler returns false from TryHandleAsync, the next registered handler gets a chance. This gives you a clean chain of responsibility without messy if/else trees in a single middleware class. For new projects on .NET 8+, this is the approach to use.

Problem Details: The Standard Way to Return Errors

ASP.NET Core 7+ has built-in support for RFC 7807 Problem Details. Use it instead of rolling your own error response format:

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        // Add correlation ID to every problem response
        context.ProblemDetails.Extensions["traceId"] =
            context.HttpContext.TraceIdentifier;

        // Never include exception details in production
        context.ProblemDetails.Extensions.Remove("exception");
    };
});

// In Program.cs
app.UseExceptionHandler();
app.UseStatusCodePages();

For custom domain exceptions, create specific Problem Details responses:

public class OrderNotFoundException : Exception
{
    public int OrderId { get; }
    public OrderNotFoundException(int orderId)
        : base($"Order {orderId} was not found.")
    {
        OrderId = orderId;
    }
}

// In your exception handler
if (exception is OrderNotFoundException notFound)
{
    return TypedResults.Problem(
        title: "Order not found.",
        detail: $"No order with ID {notFound.OrderId} exists.",  // Safe — no internal details
        statusCode: 404
    );
}

Logging Exceptions Safely

Fixing the response is half the job. The other half is making sure you're not accidentally logging sensitive data.

What NOT to Log

// ❌ Logs the full request body — may contain passwords, card numbers, PII
_logger.LogError("Request failed: {Request}", JsonSerializer.Serialize(request));

// ❌ Logs the connection string from the exception message
_logger.LogError("DB error: {Message}", exception.Message);

// ❌ Logs authentication tokens
_logger.LogInformation("User authenticated with token: {Token}", token);

// ❌ String interpolation bypasses structured logging — if user.ToString()
//    accidentally includes a password hash or sensitive field, it leaks to your logs
_logger.LogError($"Error processing user {user}");

What to Log Instead

// ✅ Log the exception object — structured logging handles it safely
_logger.LogError(exception, "Order processing failed for OrderId: {OrderId}", orderId);

// ✅ Always use message templates, never string interpolation
//    This logs the UserId value, not the entire object
_logger.LogWarning("Authentication failed for UserId: {UserId}", user.Id);

// ✅ Log that sensitive data was present, not its value
_logger.LogInformation("Payment processed. CardLastFour: {Last4}", card.LastFour);

Why string interpolation is dangerous in logs: When you write _logger.LogError($"Error for {user}"), the entire user object is serialised via ToString() before the logger ever sees it. If your model's ToString() override (or a default JSON serialiser) includes a password hash, an API key, or a session token, that value ends up in your log store in plain text. Structured logging with message templates ({UserId}) passes the value as a typed parameter — you control exactly what gets captured.

Filtering Sensitive Properties in Serilog

If you're using Serilog, use destructuring policies to automatically redact sensitive fields:

Log.Logger = new LoggerConfiguration()
    .Destructure.ByTransforming<LoginRequest>(r => new
    {
        r.Email,
        Password = "***REDACTED***"
    })
    .WriteTo.Console()
    .CreateLogger();

Validating Input Before It Throws

Many exception-based information leaks start with unvalidated input. If you validate properly at the boundary, the dangerous exceptions never get thrown.

// ❌ Throws SqlException with schema details if input is malicious
public async Task<Order> GetOrderAsync(string rawId)
{
    var id = int.Parse(rawId); // throws FormatException with the raw input
    return await _db.Orders.FindAsync(id);
}

// ✅ Validate at the boundary — exception never reaches the DB layer
public async Task<IActionResult> GetOrder([FromRoute] int id)
{
    if (id <= 0)
        return BadRequest(new { error = "Invalid order ID." });

    var order = await _orderService.GetOrderAsync(id);
    return order is null ? NotFound() : Ok(order);
}

For complex validation, use FluentValidation and return structured errors without exposing internal rules:

public class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderValidator()
    {
        RuleFor(x => x.ProductId)
            .GreaterThan(0)
            .WithMessage("Invalid product.");   // Generic — doesn't reveal ID ranges

        RuleFor(x => x.Quantity)
            .InclusiveBetween(1, 100)
            .WithMessage("Quantity must be between 1 and 100.");
    }
}

Hiding Server and Technology Information

Beyond exceptions, ASP.NET Core leaks information through HTTP response headers by default. Remove them:

// Program.cs — remove the Server header
builder.WebHost.ConfigureKestrel(options =>
{
    options.AddServerHeader = false;
});

Also remove the X-Powered-By header if you're behind IIS:

<!-- web.config -->
<system.webServer>
  <httpProtocol>
    <customHeaders>
      <remove name="X-Powered-By" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

And never expose the ASP.NET Core version in error responses. Verify this with your production error handler:

// ❌ Reveals framework version
context.Response.Headers["X-AspNet-Version"] = Environment.Version.ToString();

// ✅ Remove it entirely
context.Response.Headers.Remove("X-AspNet-Version");

Environment-Specific Configuration

The most common mistake is accidentally deploying with ASPNETCORE_ENVIRONMENT=Development in production. This enables the developer exception page, which shows full stack traces.

Lock this down explicitly:

// Program.cs — explicit check, not implicit trust
if (!app.Environment.IsProduction())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler();
    app.UseHsts();
}

And verify it in your CI/CD pipeline. In GitHub Actions:

- name: Verify production environment
  run: |
    if [ "$ASPNETCORE_ENVIRONMENT" = "Development" ]; then
      echo "ERROR: Cannot deploy with Development environment"
      exit 1
    fi
  env:
    ASPNETCORE_ENVIRONMENT: ${{ vars.ASPNETCORE_ENVIRONMENT }}

Common Errors and How to Avoid Them

Showing stack traces in production
This is the most critical issue. Always configure UseExceptionHandler or custom middleware for production. Use IHostEnvironment.IsProduction() — never rely on #if DEBUG for security decisions.

Returning exception messages directly to clients
Never do return BadRequest(exception.Message). Exception messages are written for developers, not clients. They frequently contain internal paths, SQL fragments, or configuration values. Always return a message you explicitly wrote.

// ❌
return BadRequest(ex.Message);

// ✅
return BadRequest("The request could not be processed. Please check your input.");

Catching and swallowing exceptions silently
Hiding exceptions without logging them destroys your ability to debug production issues.

// ❌ Exception disappears — you'll never know this happened
try { await ProcessOrderAsync(order); }
catch (Exception) { }

// ✅ Log it, then decide how to respond
try { await ProcessOrderAsync(order); }
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to process order {OrderId}", order.Id);
    throw; // or return a safe error response
}

Leaking internal IDs in error messages
Avoid returning internal identifiers (auto-increment IDs, GUIDs from internal systems) in error messages. They help attackers enumerate resources.

// ❌ Confirms the resource exists and reveals the internal ID format
return NotFound($"Order with ID {id} not found in database.");

// ✅ Generic — reveals nothing
return NotFound();

Using Environment.StackTrace in responses or logs
Developers sometimes manually include Environment.StackTrace in log messages or error responses when debugging a tricky issue — and forget to remove it. This is just as dangerous as an unhandled exception reaching the client: it exposes the full call stack, file paths, and line numbers.

// ❌ Never include Environment.StackTrace in HTTP responses
return StatusCode(500, new {
    error = "Something went wrong",
    stack = Environment.StackTrace  // Full stack trace sent to the client
});

// ❌ Logging it is safer but still leaks internal structure to your log store
_logger.LogError("Error occurred. Stack: {Stack}", Environment.StackTrace);

// ✅ Log the exception object instead — it includes the stack trace
//    in a structured way, scoped to the actual exception that was thrown
_logger.LogError(exception, "Unhandled error processing order {OrderId}", orderId);

The exception object passed to _logger.LogError(exception, ...) captures the stack trace as a structured field in your log store. You get full context without manually concatenating strings — and it never accidentally ends up in an HTTP response.

Different error responses for valid vs invalid users
If your API returns different error messages for "user not found" vs "wrong password", attackers can enumerate valid usernames. Use identical responses:

// ❌ Reveals whether the email exists
if (user is null) return Unauthorized("Email address not registered.");
if (!VerifyPassword(user, request.Password)) return Unauthorized("Incorrect password.");

// ✅ Same message either way
if (user is null || !VerifyPassword(user, request.Password))
    return Unauthorized("Invalid credentials.");

Don't forget timing attacks. Identical messages aren't enough on their own. If validating a non-existent user takes 2ms (a quick null check) and validating a wrong password takes 200ms (a bcrypt hash comparison), an attacker can still enumerate valid emails by measuring response times — even without reading the message body. Use a constant-time dummy verification to equalise the response time regardless of whether the user exists:
var user = await _db.Users.FirstOrDefaultAsync(u => u.Email == request.Email);

// Always run the hash comparison — even for non-existent users
// This ensures the response time is the same whether the user exists or not
var passwordValid = user is not null
    ? VerifyPassword(user.PasswordHash, request.Password)
    : BCrypt.Verify(request.Password, _dummyHash); // constant-time dummy check

if (user is null || !passwordValid)
    return Unauthorized("Invalid credentials.");
This is a more advanced technique, but it closes the gap between "secure messages" and "truly secure authentication."

Best Practices

Never expose stack traces in production. Configure UseExceptionHandler before deploying — it's off by default in non-Development environments only if you set it up.
Return Problem Details (RFC 7807) for all error responses. It's a standard format that clients can handle generically.
Always include a correlation/trace ID in error responses. It lets clients report errors to support without exposing internal details.
Log the full exception internally — never sacrifice observability for security. The goal is to hide details from clients, not from your own monitoring.
Validate all input at the boundary. Most information leaks start with unvalidated data reaching layers that weren't designed to handle it.
Use identical error messages for authentication failures to prevent username enumeration.
Remove server headers (Server, X-Powered-By, X-AspNet-Version) from all responses.
Audit your error responses in staging before every release. Run your API against a tool like OWASP ZAP and check what error details leak.

Conclusion

Exceptions are not just a reliability concern — they're a security boundary. Every unhandled exception that reaches a client is a potential information disclosure vulnerability. Stack traces, database schemas, internal paths, and connection strings all become attacker intelligence when they leak through error responses.

The fixes are straightforward: global exception middleware, Problem Details responses, structured logging with redaction, and environment-specific configuration. None of this requires a security specialist — it's standard ASP.NET Core development practice that every team should have in place before going to production.

The goal is simple: your logs should have everything, your clients should have nothing they didn't need to know.