HTTP Caching and ETags

using Microsoft.Extensions.Primitives;
using Microsoft.Net.Http.Headers;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderService, OrderService>();
var app = builder.Build();

app.MapPut("/orders/{id:int}/shipping-address", async (int id, AddressChange change, HttpContext http, IOrderService orders, CancellationToken ct) =>
{
    var precondition = Precondition.FromIfMatch(http.Request.Headers.IfMatch);
    if (precondition is null)
        return Results.Problem(statusCode: StatusCodes.Status428PreconditionRequired, title: "Send If-Match with the order's ETag.");

    var result = await orders.UpdateAddressAsync(id, precondition, change.Address, ct);
    if (result.CurrentVersion is { } version)
        http.Response.GetTypedHeaders().ETag = new EntityTagHeaderValue($"\"{version}\"");

    return result.Outcome switch
    {
        UpdateOutcome.NotFound => Results.NotFound(),
        UpdateOutcome.Conflict => Results.Problem(statusCode: StatusCodes.Status412PreconditionFailed,
            title: "The order was changed by someone else. GET it again and reapply your change."),
        _ => Results.NoContent(),
    };
});
app.Run();

// AnyVersion is If-Match: *, "update only if the order exists". Versions empty means nothing usable was sent.
public sealed record Precondition(bool AnyVersion, IReadOnlyList<uint> Versions)
{
    public static Precondition? FromIfMatch(StringValues header)
    {
        if (StringValues.IsNullOrEmpty(header)) return null;
        if (!EntityTagHeaderValue.TryParseList(header, out var tags)) return new(false, []);
        if (tags.Any(t => t.Equals(EntityTagHeaderValue.Any))) return new(true, []);

        // If-Match uses strong comparison, so weak tags never match and are dropped.
        var versions = tags.Where(t => !t.IsWeak)
            .Select(t => uint.TryParse(t.Tag.AsSpan().Trim('"'), out var v) ? v : (uint?)null)
            .OfType<uint>()
            .ToList();
        return new(false, versions);
    }
}

public enum UpdateOutcome { Updated, NotFound, Conflict }
public sealed record UpdateResult(UpdateOutcome Outcome, uint? CurrentVersion);
public sealed record AddressChange(string Address);

public interface IOrderService
{
    Task<UpdateResult> UpdateAddressAsync(int id, Precondition precondition, string address, CancellationToken ct);
}

// Stand-in: the real implementation is the EF Core concurrency-token save from the concurrency lesson.
public sealed class OrderService : IOrderService
{
    public Task<UpdateResult> UpdateAddressAsync(int id, Precondition precondition, string address, CancellationToken ct) =>
        Task.FromResult(new UpdateResult(UpdateOutcome.NotFound, null));
}

GET /orders/5001 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Cache-Control: private, no-cache
ETag: "17"
Content-Type: application/json; charset=utf-8

###

GET /orders/5001 HTTP/1.1
Host: api.example.com
If-None-Match: "17"

HTTP/1.1 304 Not Modified
Cache-Control: private, no-cache
ETag: "17"

###

PUT /orders/5001/shipping-address HTTP/1.1
Host: api.example.com
If-Match: "16"
Content-Type: application/json

{"address": "9 Quay Rd, Leith"}

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var catalog = app.MapGroup("/catalog").AddEndpointFilter(async (context, next) =>
{
    var response = context.HttpContext.Response;
    // The returned IResult runs after the filter, so the final status is only known when headers are sent.
    response.OnStarting(() =>
    {
        if (response.StatusCode == StatusCodes.Status200OK)
        {
            // Browsers keep it 60 s, the CDN 5 minutes, and may serve stale for 30 s while refetching.
            response.Headers.CacheControl = "public, max-age=60, s-maxage=300, stale-while-revalidate=30";
            response.Headers.Vary = "Accept-Language";
        }
        else
        {
            response.Headers.CacheControl = "no-store";
        }
        return Task.CompletedTask;
    });
    return await next(context);
});

catalog.MapGet("/categories", (HttpRequest request) =>
{
    var french = request.Headers.AcceptLanguage.ToString().StartsWith("fr", StringComparison.OrdinalIgnoreCase);
    return TypedResults.Ok(french ? new[] { "Eclairage", "Mobilier" } : new[] { "Lighting", "Furniture" });
});

app.Run();