@opengroundplan/core 0.1.1

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersionHeaders.cs

@@ -0,0 +1,62 @@
+using System.Globalization;
+using Microsoft.AspNetCore.Http;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+/// Response headers that tell a client what it got and how long it has left. Formats are
+/// fixed by RFC 9745 (Deprecation), RFC 8594 (Sunset) and RFC 8288 (Link).
+public sealed class ApiVersionHeaders(ApiVersionPolicy policy)
+{
+    /// IMF-fixdate, the only form RFC 8594 allows: Sat, 01 Aug 2026 00:00:00 GMT.
+    public static string HttpDate(DateOnly day) =>
+        day.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc)
+            .ToString("R", CultureInfo.InvariantCulture);
+
+    public IReadOnlyDictionary<string, string> For(VersionResolution resolution)
+    {
+        var options = policy.Options;
+        var headers = new Dictionary<string, string>(StringComparer.Ordinal);
+
+        if (options.EmitResponseHeader)
+        {
+            headers[options.HeaderName] = resolution.Version;
+        }
+
+        // Caches key on the URL, so only strategies that hide the version outside the URL
+        // need a Vary. Getting this wrong serves one client's version to another.
+        var vary = options.Strategy switch
+        {
+            "header" => options.HeaderName,
+            "accept" => "Accept",
+            _ => null,
+        };
+        if (vary is not null)
+        {
+            headers["Vary"] = vary;
+        }
+
+        var deprecation = policy.DeprecationFor(resolution.Version);
+        if (deprecation is null)
+        {
+            return headers;
+        }
+
+        var announced = deprecation.Announced.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc);
+        headers["Deprecation"] = FormattableString.Invariant($"@{new DateTimeOffset(announced).ToUnixTimeSeconds()}");
+        headers["Sunset"] = HttpDate(deprecation.Sunset);
+        if (!string.IsNullOrWhiteSpace(options.PolicyUrl))
+        {
+            headers["Link"] = $"<{options.PolicyUrl}>; rel=\"deprecation\", <{options.PolicyUrl}>; rel=\"sunset\"";
+        }
+
+        return headers;
+    }
+
+    public void Apply(HttpResponse response, VersionResolution resolution)
+    {
+        foreach (var (name, value) in For(resolution))
+        {
+            response.Headers[name] = value;
+        }
+    }
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersionNegotiator.cs

@@ -0,0 +1,129 @@
+using System.Text.RegularExpressions;
+using Microsoft.AspNetCore.Http;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+public enum VersionSource
+{
+    Default,
+    Path,
+    Header,
+    Query,
+    Accept,
+}
+
+/// What will be served, where the request said so, and what the client originally asked for —
+/// so a fallback is visible in logs rather than indistinguishable from an explicit request.
+public readonly record struct VersionResolution(string Version, VersionSource Source, string? Requested);
+
+/// Raised when a client names a version this deployment cannot serve.
+public sealed class UnsupportedApiVersionException(string requested, IReadOnlyList<string> supported)
+    : Exception($"Unsupported API version '{requested}'; supported: {string.Join(", ", supported)}")
+{
+    public string Requested { get; } = requested;
+
+    public IReadOnlyList<string> Supported { get; } = supported;
+}
+
+/// Negotiation is a pure function of the request, so it is testable without a server.
+public sealed partial class ApiVersionNegotiator(ApiVersionPolicy policy)
+{
+    // What a path segment must look like to count as a version attempt. Without this,
+    // /api/orders under the path strategy reads as a request for version "orders".
+    [GeneratedRegex(@"^(v\d+(\.\d+)?|\d{4}-\d{2}-\d{2})$", RegexOptions.IgnoreCase)]
+    private static partial Regex VersionShaped();
+
+    public VersionResolution Resolve(HttpRequest request) =>
+        Resolve(request.Path.Value ?? "/", name => request.Headers[name].ToString(), name => request.Query[name].ToString());
+
+    public VersionResolution Resolve(string path, Func<string, string?> header, Func<string, string?> query)
+    {
+        var options = policy.Options;
+        if (!options.Enabled)
+        {
+            return new VersionResolution(options.Default, VersionSource.Default, null);
+        }
+
+        var requested = Requested(path, header, query);
+        if (string.IsNullOrWhiteSpace(requested))
+        {
+            return new VersionResolution(options.Default, VersionSource.Default, null);
+        }
+
+        if (!policy.Has(requested))
+        {
+            return options.Strict
+                ? throw new UnsupportedApiVersionException(requested, policy.Supported)
+                : new VersionResolution(options.Default, VersionSource.Default, requested);
+        }
+
+        return new VersionResolution(requested, SourceOf(options.Strategy), requested);
+    }
+
+    public string? VersionFromPath(string path)
+    {
+        var prefix = policy.Options.PathPrefix.TrimEnd('/');
+        var rest = prefix.Length > 0 && path.StartsWith(prefix, StringComparison.Ordinal)
+            ? path[prefix.Length..]
+            : path;
+
+        var segment = rest.Split('/', StringSplitOptions.RemoveEmptyEntries).FirstOrDefault();
+        if (segment is null)
+        {
+            return null;
+        }
+
+        return policy.Has(segment) || VersionShaped().IsMatch(segment) ? segment : null;
+    }
+
+    /// Pulls `version=<value>` out of any media range in an Accept header.
+    public static string? VersionFromAccept(string? accept)
+    {
+        if (string.IsNullOrWhiteSpace(accept))
+        {
+            return null;
+        }
+
+        foreach (var mediaRange in accept.Split(','))
+        {
+            foreach (var parameter in mediaRange.Split(';').Skip(1))
+            {
+                var parts = parameter.Split('=', 2);
+                if (parts.Length != 2 || !parts[0].Trim().Equals("version", StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                var value = parts[1].Trim().Trim('"');
+                if (value.Length > 0)
+                {
+                    return value;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    private string? Requested(string path, Func<string, string?> header, Func<string, string?> query)
+    {
+        var options = policy.Options;
+        return options.Strategy switch
+        {
+            "path" => VersionFromPath(path),
+            "header" => Trimmed(header(options.HeaderName)),
+            "query" => Trimmed(query(options.QueryParam)),
+            _ => VersionFromAccept(header("Accept")),
+        };
+    }
+
+    private static string? Trimmed(string? value) => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+
+    private static VersionSource SourceOf(string strategy) => strategy switch
+    {
+        "path" => VersionSource.Path,
+        "header" => VersionSource.Header,
+        "query" => VersionSource.Query,
+        _ => VersionSource.Accept,
+    };
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersionOptions.cs

@@ -0,0 +1,58 @@
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+/// The one typed default table for API versioning. Bound from the "ApiVersioning"
+/// configuration section, so every value is overridable by appsettings, environment, or
+/// user secrets — and nothing else in the codebase may hold a version literal.
+public sealed class ApiVersionOptions
+{
+    public const string SectionName = "ApiVersioning";
+
+    public bool Enabled { get; set; } = true;
+
+    /// path | header | query | accept.
+    public string Strategy { get; set; } = "{{ apiVersionStrategy }}";
+
+    /// Oldest first. Declaration order IS the ordering — no version grammar is parsed.
+    public IList<string> Supported { get; set; } =
+        "{{ apiVersionSupported }}".Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+    /// Served when the client states none. Keep it the oldest supported version: a client
+    /// shipped two years ago sends nothing, and it must not silently move to new behaviour.
+    public string Default { get; set; } = "{{ apiVersionDefault }}";
+
+    /// false lets an unknown version fall back to Default — only sane behind a gateway
+    /// that has already validated it.
+    public bool Strict { get; set; } = true;
+
+    public string HeaderName { get; set; } = "{{ apiVersionHeaderName }}";
+
+    public string QueryParam { get; set; } = "{{ apiVersionQueryParam }}";
+
+    public string MediaType { get; set; } = "{{ apiVersionMediaType }}";
+
+    public string PathPrefix { get; set; } = "{{ apiVersionPathPrefix }}";
+
+    public IList<DeprecationOptions> Deprecations { get; set; } = [];
+
+    /// Minimum notice before a version may be retired. Raise it for partner and embedded
+    /// clients; never lower it to make a shipping date work.
+    public int MinSunsetDays { get; set; } = {{ apiVersionMinSunsetDays }};
+
+    /// Sent as Link rel="deprecation" and rel="sunset" when set.
+    public string PolicyUrl { get; set; } = "{{ apiVersionPolicyUrl }}";
+
+    public bool EmitResponseHeader { get; set; } = true;
+
+    public string ContractDir { get; set; } = "{{ apiVersionContractDir }}";
+}
+
+/// One version on the way out, with the dates that were promised. Both are required:
+/// a deprecation without a clock is a rumour.
+public sealed class DeprecationOptions
+{
+    public string Version { get; set; } = string.Empty;
+
+    public DateOnly Announced { get; set; }
+
+    public DateOnly Sunset { get; set; }
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersionPolicy.cs

@@ -0,0 +1,99 @@
+using Microsoft.Extensions.Options;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+/// What is supported, in what order, and what is on the way out. Ordering is the position
+/// in the supported list, so v10 never sorts before v9.
+public sealed class ApiVersionPolicy
+{
+    private readonly Dictionary<string, int> _order;
+    private readonly Dictionary<string, DeprecationOptions> _deprecations;
+
+    public ApiVersionPolicy(IOptions<ApiVersionOptions> options)
+        : this(options.Value)
+    {
+    }
+
+    public ApiVersionPolicy(ApiVersionOptions options)
+    {
+        Options = Validate(options);
+        _order = Options.Supported
+            .Select((version, index) => (version, index))
+            .ToDictionary(pair => pair.version, pair => pair.index, StringComparer.Ordinal);
+        _deprecations = Options.Deprecations.ToDictionary(item => item.Version, StringComparer.Ordinal);
+    }
+
+    public ApiVersionOptions Options { get; }
+
+    public IReadOnlyList<string> Supported => (IReadOnlyList<string>)Options.Supported;
+
+    public string Latest => Options.Supported[^1];
+
+    public string Oldest => Options.Supported[0];
+
+    public string Default => Options.Default;
+
+    public bool Has(string version) => _order.ContainsKey(version);
+
+    /// Negative when <paramref name="a"/> is older, positive when newer, zero when equal.
+    public int Compare(string a, string b) => Rank(a) - Rank(b);
+
+    public DeprecationOptions? DeprecationFor(string version) =>
+        _deprecations.TryGetValue(version, out var deprecation) ? deprecation : null;
+
+    /// Versions past their sunset date that are still being served. Reported, never enforced:
+    /// removing a version from Supported is an operator's decision, not a clock's.
+    public IReadOnlyList<DeprecationOptions> Overdue(DateOnly today) =>
+        Options.Deprecations.Where(item => item.Sunset <= today).ToList();
+
+    private int Rank(string version) =>
+        _order.TryGetValue(version, out var index)
+            ? index
+            : throw new ArgumentOutOfRangeException(
+                nameof(version),
+                $"Unknown API version '{version}'; supported: {string.Join(", ", Options.Supported)}");
+
+    /// A default outside the supported set, or a sunset inside the notice window, is a promise
+    /// already broken. Finding it at startup costs a restart; finding it later costs the client.
+    private static ApiVersionOptions Validate(ApiVersionOptions options)
+    {
+        if (options.Supported.Count == 0)
+        {
+            throw new OptionsValidationException(
+                ApiVersionOptions.SectionName,
+                typeof(ApiVersionOptions),
+                ["Supported must list at least one version"]);
+        }
+
+        var failures = new List<string>();
+        if (options.Supported.Distinct(StringComparer.Ordinal).Count() != options.Supported.Count)
+        {
+            failures.Add("Supported repeats a version");
+        }
+
+        if (!options.Supported.Contains(options.Default, StringComparer.Ordinal))
+        {
+            failures.Add($"Default '{options.Default}' is not in Supported ({string.Join(", ", options.Supported)})");
+        }
+
+        foreach (var deprecation in options.Deprecations)
+        {
+            if (!options.Supported.Contains(deprecation.Version, StringComparer.Ordinal))
+            {
+                failures.Add($"Deprecations names '{deprecation.Version}', which is not in Supported");
+                continue;
+            }
+
+            var notice = deprecation.Sunset.DayNumber - deprecation.Announced.DayNumber;
+            if (notice < options.MinSunsetDays)
+            {
+                failures.Add(
+                    $"{deprecation.Version} gives {notice} days of notice, below MinSunsetDays ({options.MinSunsetDays})");
+            }
+        }
+
+        return failures.Count == 0
+            ? options
+            : throw new OptionsValidationException(ApiVersionOptions.SectionName, typeof(ApiVersionOptions), failures);
+    }
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersioningMiddleware.cs

@@ -0,0 +1,58 @@
+using System.Text.Json;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+/// Negotiates the version, stamps the response, and refuses an unknown version itself —
+/// nothing downstream should run for a contract this deployment cannot honour.
+public sealed class ApiVersioningMiddleware(
+    RequestDelegate next,
+    ApiVersionNegotiator negotiator,
+    ApiVersionHeaders headers)
+{
+    public const string ProblemMediaType = "application/problem+json";
+
+    /// Read from a handler as `HttpContext.Items[ApiVersioningMiddleware.ItemKey]`.
+    public const string ItemKey = "ApiVersion";
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        VersionResolution resolution;
+        try
+        {
+            resolution = negotiator.Resolve(context.Request);
+        }
+        catch (UnsupportedApiVersionException error)
+        {
+            await WriteProblemAsync(context, error);
+            return;
+        }
+
+        context.Items[ItemKey] = resolution;
+        headers.Apply(context.Response, resolution);
+        await next(context);
+    }
+
+    private static async Task WriteProblemAsync(HttpContext context, UnsupportedApiVersionException error)
+    {
+        context.Response.StatusCode = StatusCodes.Status400BadRequest;
+        context.Response.ContentType = ProblemMediaType;
+        // `about:blank` is the RFC-correct type when the status code already says everything.
+        await context.Response.WriteAsync(JsonSerializer.Serialize(new
+        {
+            type = "about:blank",
+            title = "Unsupported API version",
+            status = StatusCodes.Status400BadRequest,
+            detail = error.Message,
+            supported = error.Supported,
+            requested = error.Requested,
+        }));
+    }
+}
+
+public static class ApiVersioningApplicationBuilderExtensions
+{
+    public static IApplicationBuilder UseApiVersioning(this IApplicationBuilder app) =>
+        app.UseMiddleware<ApiVersioningMiddleware>();
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ApiVersioningServiceCollectionExtensions.cs

@@ -0,0 +1,18 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+public static class ApiVersioningServiceCollectionExtensions
+{
+    /// Binds the "ApiVersioning" section over the typed defaults. The policy validates on
+    /// first resolution, so a broken deprecation window fails at startup, not in the field.
+    public static IServiceCollection AddApiVersioning(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.Configure<ApiVersionOptions>(configuration.GetSection(ApiVersionOptions.SectionName));
+        services.AddSingleton<ApiVersionPolicy>();
+        services.AddSingleton<ApiVersionNegotiator>();
+        services.AddSingleton<ApiVersionHeaders>();
+        return services;
+    }
+}

package/templates/layers/api-versioning/files/src/__solutionName.dot__.ApiVersioning/ContractDiff.cs

@@ -0,0 +1,152 @@
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+public enum ChangeSeverity
+{
+    Neutral,
+    Additive,
+    Breaking,
+}
+
+public enum ContractDirection
+{
+    Request,
+    Response,
+}
+
+public readonly record struct ContractChange(string Path, ChangeSeverity Severity, string Message);
+
+/// The same edit is safe in one direction and fatal in the other — adding a field to a
+/// response costs nothing, adding a required request field breaks every shipped client —
+/// so direction is part of every comparison.
+public static class ContractDiff
+{
+    public static IReadOnlyList<ContractChange> Compare(
+        ContractShape before,
+        ContractShape after,
+        ContractDirection direction,
+        string path = "$")
+    {
+        // The old contract promised nothing here, so narrowing it cannot break anyone.
+        if (before.Kind == "unknown")
+        {
+            return [];
+        }
+
+        if (before.Kind != after.Kind)
+        {
+            return [new ContractChange(path, ChangeSeverity.Breaking, $"type changed from {before.Kind} to {after.Kind}")];
+        }
+
+        return before.Kind switch
+        {
+            "array" => Compare(before.Items ?? new ContractShape(), after.Items ?? new ContractShape(), direction, path + "[]"),
+            "object" => CompareObjects(before.Fields ?? [], after.Fields ?? [], direction, path),
+            _ => [],
+        };
+    }
+
+    public static IReadOnlyList<ContractChange> Compare(ContractSnapshot before, ContractSnapshot after)
+    {
+        var changes = new List<ContractChange>();
+
+        foreach (var (name, operation) in before.Operations.OrderBy(pair => pair.Key, StringComparer.Ordinal))
+        {
+            if (!after.Operations.TryGetValue(name, out var following))
+            {
+                // Retiring an operation is what a new version is for, never an in-place edit.
+                changes.Add(new ContractChange(name, ChangeSeverity.Breaking, "operation removed"));
+                continue;
+            }
+
+            changes.AddRange(CompareDirection(operation.Request, following.Request, ContractDirection.Request, name));
+            changes.AddRange(CompareDirection(operation.Response, following.Response, ContractDirection.Response, name));
+        }
+
+        changes.AddRange(after.Operations.Keys
+            .Where(name => !before.Operations.ContainsKey(name))
+            .OrderBy(name => name, StringComparer.Ordinal)
+            .Select(name => new ContractChange(name, ChangeSeverity.Additive, "new operation")));
+
+        return changes;
+    }
+
+    public static IReadOnlyList<ContractChange> Breaking(IEnumerable<ContractChange> changes) =>
+        changes.Where(change => change.Severity == ChangeSeverity.Breaking).ToList();
+
+    public static string Format(IEnumerable<ContractChange> changes) =>
+        string.Join(Environment.NewLine, changes.Select(c => $"  [{c.Severity}] {c.Path}: {c.Message}"));
+
+    private static IReadOnlyList<ContractChange> CompareDirection(
+        ContractShape? before,
+        ContractShape? after,
+        ContractDirection direction,
+        string operation)
+    {
+        if (before is null)
+        {
+            return [];
+        }
+
+        var path = $"{operation}.{Name(direction)}";
+        return after is null
+            ? [new ContractChange(path, ChangeSeverity.Breaking, $"{Name(direction)} contract removed")]
+            : Compare(before, after, direction, path);
+    }
+
+    private static List<ContractChange> CompareObjects(
+        Dictionary<string, ContractField> before,
+        Dictionary<string, ContractField> after,
+        ContractDirection direction,
+        string path)
+    {
+        var response = direction == ContractDirection.Response;
+        var changes = new List<ContractChange>();
+
+        foreach (var (name, field) in before.OrderBy(pair => pair.Key, StringComparer.Ordinal))
+        {
+            var child = $"{path}.{name}";
+            if (!after.TryGetValue(name, out var following))
+            {
+                changes.Add(response
+                    ? new ContractChange(child, ChangeSeverity.Breaking, "response field removed")
+                    // The server stops reading it; a client still sending it is unaffected.
+                    : new ContractChange(child, ChangeSeverity.Neutral, "request field no longer read"));
+                continue;
+            }
+
+            if (field.Required && !following.Required)
+            {
+                changes.Add(response
+                    ? new ContractChange(child, ChangeSeverity.Breaking, "guaranteed response field is now optional")
+                    : new ContractChange(child, ChangeSeverity.Additive, "required request field is now optional"));
+            }
+
+            if (!field.Required && following.Required)
+            {
+                changes.Add(response
+                    ? new ContractChange(child, ChangeSeverity.Additive, "optional response field is now guaranteed")
+                    : new ContractChange(child, ChangeSeverity.Breaking, "optional request field is now required"));
+            }
+
+            changes.AddRange(Compare(field.Shape, following.Shape, direction, child));
+        }
+
+        foreach (var (name, field) in after.OrderBy(pair => pair.Key, StringComparer.Ordinal))
+        {
+            if (before.ContainsKey(name))
+            {
+                continue;
+            }
+
+            var child = $"{path}.{name}";
+            changes.Add(!response && field.Required
+                ? new ContractChange(child, ChangeSeverity.Breaking, "new required request field")
+                : new ContractChange(child, ChangeSeverity.Additive, $"new {Name(direction)} field"));
+        }
+
+        return changes;
+    }
+
+    private static string Name(ContractDirection direction) =>
+        direction == ContractDirection.Request ? "request" : "response";
+}