@opengroundplan/core 0.1.1

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

@@ -0,0 +1,142 @@
+using System.Text.Json;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+/// A payload reduced to what a client can depend on: which fields exist, whether they are
+/// always present, and what type they hold. Values are discarded — a contract is not a
+/// fixture, and snapshotting values makes every data change look like a contract change.
+public sealed class ContractShape
+{
+    public string Kind { get; set; } = "unknown";
+
+    public ContractShape? Items { get; set; }
+
+    public Dictionary<string, ContractField>? Fields { get; set; }
+}
+
+public sealed class ContractField
+{
+    public bool Required { get; set; }
+
+    public ContractShape Shape { get; set; } = new();
+}
+
+public sealed class ContractOperation
+{
+    public ContractShape? Request { get; set; }
+
+    public ContractShape? Response { get; set; }
+}
+
+public sealed class ContractSnapshot
+{
+    public string Version { get; set; } = string.Empty;
+
+    /// Keyed by operation, conventionally "GET /orders/{id}".
+    public Dictionary<string, ContractOperation> Operations { get; set; } = [];
+}
+
+public static class ContractDescriber
+{
+    /// Describes any object by round-tripping it through the same serializer the API uses,
+    /// so the snapshot records what a client actually receives, not what the CLR type says.
+    public static ContractShape Describe(object? value, JsonSerializerOptions? options = null) =>
+        Describe(JsonSerializer.SerializeToElement(value, options));
+
+    public static ContractShape Describe(JsonElement element) => element.ValueKind switch
+    {
+        JsonValueKind.Null or JsonValueKind.Undefined => new ContractShape { Kind = "null" },
+        JsonValueKind.True or JsonValueKind.False => new ContractShape { Kind = "boolean" },
+        JsonValueKind.Number => new ContractShape { Kind = "number" },
+        JsonValueKind.String => new ContractShape { Kind = "string" },
+        JsonValueKind.Array => DescribeArray(element),
+        JsonValueKind.Object => DescribeObject(element),
+        _ => new ContractShape(),
+    };
+
+    /// Several samples of the same payload. A field absent from any sample is optional.
+    public static ContractShape DescribeAll(IEnumerable<JsonElement> samples)
+    {
+        ContractShape? merged = null;
+        foreach (var sample in samples)
+        {
+            merged = merged is null ? Describe(sample) : Merge(merged, Describe(sample));
+        }
+
+        return merged ?? new ContractShape();
+    }
+
+    public static ContractShape Merge(ContractShape a, ContractShape b)
+    {
+        if (a.Kind == "unknown")
+        {
+            return b;
+        }
+
+        if (b.Kind == "unknown")
+        {
+            return a;
+        }
+
+        if (a.Kind != b.Kind)
+        {
+            return new ContractShape();
+        }
+
+        if (a.Kind == "array")
+        {
+            return new ContractShape
+            {
+                Kind = "array",
+                Items = Merge(a.Items ?? new ContractShape(), b.Items ?? new ContractShape()),
+            };
+        }
+
+        if (a.Kind != "object")
+        {
+            return a;
+        }
+
+        var left = a.Fields ?? [];
+        var right = b.Fields ?? [];
+        var fields = new Dictionary<string, ContractField>(StringComparer.Ordinal);
+        foreach (var name in left.Keys.Union(right.Keys, StringComparer.Ordinal))
+        {
+            var hasLeft = left.TryGetValue(name, out var leftField);
+            var hasRight = right.TryGetValue(name, out var rightField);
+            fields[name] = hasLeft && hasRight
+                ? new ContractField
+                {
+                    Required = leftField!.Required && rightField!.Required,
+                    Shape = Merge(leftField.Shape, rightField!.Shape),
+                }
+                // Present in one sample only — the client cannot rely on it.
+                : new ContractField { Required = false, Shape = (leftField ?? rightField)!.Shape };
+        }
+
+        return new ContractShape { Kind = "object", Fields = fields };
+    }
+
+    private static ContractShape DescribeArray(JsonElement element)
+    {
+        var items = element.EnumerateArray().ToList();
+        // An empty array promises nothing about its items, so it stays unknown rather than
+        // inventing a shape the next sample would contradict.
+        return new ContractShape
+        {
+            Kind = "array",
+            Items = items.Count == 0 ? new ContractShape() : DescribeAll(items),
+        };
+    }
+
+    private static ContractShape DescribeObject(JsonElement element)
+    {
+        var fields = new Dictionary<string, ContractField>(StringComparer.Ordinal);
+        foreach (var property in element.EnumerateObject())
+        {
+            fields[property.Name] = new ContractField { Required = true, Shape = Describe(property.Value) };
+        }
+
+        return new ContractShape { Kind = "object", Fields = fields };
+    }
+}

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

@@ -0,0 +1,64 @@
+using System.Text.Json;
+
+namespace {{ solutionName | dot }}.ApiVersioning;
+
+public sealed class ContractBrokenException(IReadOnlyList<ContractChange> changes)
+    : Exception($"Contract broken for shipped clients:{Environment.NewLine}{ContractDiff.Format(changes)}")
+{
+    public IReadOnlyList<ContractChange> Changes { get; } = changes;
+}
+
+/// Reading and writing committed contract snapshots — the only part that touches disk.
+public sealed class ContractStore(ApiVersionPolicy policy)
+{
+    private static readonly JsonSerializerOptions Serialization = new()
+    {
+        WriteIndented = true,
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
+    };
+
+    public string PathFor(string version) => Path.Combine(policy.Options.ContractDir, version + ".json");
+
+    public ContractSnapshot? Load(string version)
+    {
+        var file = PathFor(version);
+        return File.Exists(file)
+            ? JsonSerializer.Deserialize<ContractSnapshot>(File.ReadAllText(file), Serialization)
+            : null;
+    }
+
+    public string Save(ContractSnapshot snapshot)
+    {
+        var file = PathFor(snapshot.Version);
+        Directory.CreateDirectory(Path.GetDirectoryName(file)!);
+        File.WriteAllText(file, JsonSerializer.Serialize(snapshot, Serialization) + Environment.NewLine);
+        return file;
+    }
+
+    /// Compares the live contract with what is committed. Throws on a breaking change;
+    /// additive changes are returned so a test can report them and the author can refresh
+    /// the baseline in the same commit that introduced them.
+    public IReadOnlyList<ContractChange> Verify(ContractSnapshot current, bool update = false)
+    {
+        var baseline = Load(current.Version);
+        if (baseline is null)
+        {
+            Save(current);
+            return [];
+        }
+
+        var changes = ContractDiff.Compare(baseline, current);
+        var breaking = ContractDiff.Breaking(changes);
+        if (breaking.Count > 0 && !update)
+        {
+            throw new ContractBrokenException(breaking);
+        }
+
+        if (update)
+        {
+            Save(current);
+        }
+
+        return changes;
+    }
+}

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

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.ApiVersioning</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.ApiVersioning</AssemblyName>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <!-- Options binding, middleware, and System.Text.Json all ship in the shared framework, so this
+       project needs no PackageReference and stays compatible with central package management. -->
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+</Project>

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/__init__.py

@@ -0,0 +1,67 @@
+"""Public surface of the versioning layer. Import from here, not from the modules."""
+
+from .contract import (
+    ADDITIVE,
+    BREAKING,
+    NEUTRAL,
+    REQUEST,
+    RESPONSE,
+    ContractChange,
+    breaking_changes,
+    describe,
+    describe_all,
+    diff_contracts,
+    diff_shapes,
+    format_changes,
+)
+from .errors import PROBLEM_MEDIA_TYPE, UnsupportedApiVersionError
+from .headers import http_date, version_response_headers
+from .middleware import ApiVersionMiddleware
+from .negotiate import VersionResolution, resolve_version, version_from_accept, version_from_path
+from .settings import (
+    ENV_PREFIX,
+    ApiVersionConfigError,
+    ApiVersionSettings,
+    Deprecation,
+    get_settings,
+    load_settings,
+)
+from .snapshot import ContractBrokenError, load_snapshot, save_snapshot, verify_contract
+from .versions import UnknownVersionError, VersionPolicy, get_policy
+
+__all__ = [
+    "ADDITIVE",
+    "BREAKING",
+    "ENV_PREFIX",
+    "NEUTRAL",
+    "PROBLEM_MEDIA_TYPE",
+    "REQUEST",
+    "RESPONSE",
+    "ApiVersionConfigError",
+    "ApiVersionMiddleware",
+    "ApiVersionSettings",
+    "ContractBrokenError",
+    "ContractChange",
+    "Deprecation",
+    "UnknownVersionError",
+    "UnsupportedApiVersionError",
+    "VersionPolicy",
+    "VersionResolution",
+    "breaking_changes",
+    "describe",
+    "describe_all",
+    "diff_contracts",
+    "diff_shapes",
+    "format_changes",
+    "get_policy",
+    "get_settings",
+    "http_date",
+    "load_settings",
+    "load_snapshot",
+    "resolve_version",
+    "save_snapshot",
+    "verify_contract",
+    "version_from_accept",
+    "version_from_path",
+    "version_response_headers",
+]

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/contract.py

@@ -0,0 +1,191 @@
+"""Contract shapes and the differ.
+
+A payload is reduced to what a client can depend on: which fields exist, whether they are
+always present, and what type they hold. Values are discarded — a contract is not a
+fixture, and snapshotting values makes every data change look like a contract change.
+
+Direction is part of every comparison because the same edit is safe one way and fatal the
+other: adding a field to a response costs nothing, adding a required field to a request
+breaks every client already shipped.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+BREAKING = "breaking"
+ADDITIVE = "additive"
+NEUTRAL = "neutral"
+
+REQUEST = "request"
+RESPONSE = "response"
+
+
+@dataclass(frozen=True, slots=True)
+class ContractChange:
+    path: str
+    severity: str
+    message: str
+
+
+def describe(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {"kind": "null"}
+    if isinstance(value, bool):
+        return {"kind": "boolean"}
+    if isinstance(value, (int, float)):
+        return {"kind": "number"}
+    if isinstance(value, str):
+        return {"kind": "string"}
+    if isinstance(value, list):
+        # An empty list promises nothing about its items, so it stays unknown rather than
+        # inventing a shape the next sample would contradict.
+        items = describe_all(value) if value else {"kind": "unknown"}
+        return {"kind": "array", "items": items}
+    if isinstance(value, dict):
+        fields = {key: {"required": True, "shape": describe(item)} for key, item in value.items()}
+        return {"kind": "object", "fields": fields}
+    return {"kind": "unknown"}
+
+
+def describe_all(samples: list[Any]) -> dict[str, Any]:
+    """Several samples of the same payload. A field absent from any sample is optional."""
+    if not samples:
+        return {"kind": "unknown"}
+    shape = describe(samples[0])
+    for sample in samples[1:]:
+        shape = merge_shapes(shape, describe(sample))
+    return shape
+
+
+def merge_shapes(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
+    if a["kind"] == "unknown":
+        return b
+    if b["kind"] == "unknown":
+        return a
+    if a["kind"] != b["kind"]:
+        return {"kind": "unknown"}
+    if a["kind"] == "array":
+        return {"kind": "array", "items": merge_shapes(a["items"], b["items"])}
+    if a["kind"] == "object":
+        fields: dict[str, Any] = {}
+        for key in set(a["fields"]) | set(b["fields"]):
+            left, right = a["fields"].get(key), b["fields"].get(key)
+            if left and right:
+                fields[key] = {
+                    "required": left["required"] and right["required"],
+                    "shape": merge_shapes(left["shape"], right["shape"]),
+                }
+            else:
+                # Present in one sample only — the client cannot rely on it.
+                fields[key] = {"required": False, "shape": (left or right)["shape"]}
+        return {"kind": "object", "fields": fields}
+    return a
+
+
+def diff_shapes(
+    before: dict[str, Any],
+    after: dict[str, Any],
+    direction: str,
+    path: str = "$",
+) -> list[ContractChange]:
+    # The old contract promised nothing here, so narrowing it cannot break anyone.
+    if before["kind"] == "unknown":
+        return []
+    if before["kind"] != after["kind"]:
+        return [
+            ContractChange(path, BREAKING, f"type changed from {before['kind']} to {after['kind']}")
+        ]
+    if before["kind"] == "array":
+        return diff_shapes(before["items"], after["items"], direction, f"{path}[]")
+    if before["kind"] == "object":
+        return _diff_objects(before["fields"], after["fields"], direction, path)
+    return []
+
+
+def _diff_objects(
+    before: dict[str, Any],
+    after: dict[str, Any],
+    direction: str,
+    path: str,
+) -> list[ContractChange]:
+    changes: list[ContractChange] = []
+
+    for name, field in before.items():
+        child = f"{path}.{name}"
+        following = after.get(name)
+
+        if following is None:
+            changes.append(
+                ContractChange(child, BREAKING, "response field removed")
+                if direction == RESPONSE
+                # The server stops reading it; a client still sending it is unaffected.
+                else ContractChange(child, NEUTRAL, "request field no longer read")
+            )
+            continue
+
+        if field["required"] and not following["required"]:
+            changes.append(
+                ContractChange(child, BREAKING, "guaranteed response field is now optional")
+                if direction == RESPONSE
+                else ContractChange(child, ADDITIVE, "required request field is now optional")
+            )
+        if not field["required"] and following["required"]:
+            changes.append(
+                ContractChange(child, ADDITIVE, "optional response field is now guaranteed")
+                if direction == RESPONSE
+                else ContractChange(child, BREAKING, "optional request field is now required")
+            )
+
+        changes.extend(diff_shapes(field["shape"], following["shape"], direction, child))
+
+    for name, field in after.items():
+        if name in before:
+            continue
+        child = f"{path}.{name}"
+        changes.append(
+            ContractChange(child, BREAKING, "new required request field")
+            if direction == REQUEST and field["required"]
+            else ContractChange(child, ADDITIVE, f"new {direction} field")
+        )
+
+    return changes
+
+
+def diff_contracts(before: dict[str, Any], after: dict[str, Any]) -> list[ContractChange]:
+    changes: list[ContractChange] = []
+    before_ops = before.get("operations", {})
+    after_ops = after.get("operations", {})
+
+    for operation, contract in before_ops.items():
+        following = after_ops.get(operation)
+        if following is None:
+            # Retiring an operation is what a new version is for, never an in-place edit.
+            changes.append(ContractChange(operation, BREAKING, "operation removed"))
+            continue
+        for direction in (REQUEST, RESPONSE):
+            source = contract.get(direction)
+            target = following.get(direction)
+            if source is None:
+                continue
+            if target is None:
+                changes.append(
+                    ContractChange(f"{operation}.{direction}", BREAKING, f"{direction} contract removed")
+                )
+                continue
+            changes.extend(diff_shapes(source, target, direction, f"{operation}.{direction}"))
+
+    for operation in after_ops:
+        if operation not in before_ops:
+            changes.append(ContractChange(operation, ADDITIVE, "new operation"))
+
+    return changes
+
+
+def breaking_changes(changes: list[ContractChange]) -> list[ContractChange]:
+    return [change for change in changes if change.severity == BREAKING]
+
+
+def format_changes(changes: list[ContractChange]) -> str:
+    return "\n".join(f"  [{change.severity}] {change.path}: {change.message}" for change in changes)

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/errors.py

@@ -0,0 +1,28 @@
+"""RFC 9457 problem details for a version a client asked for but this deployment cannot serve."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+PROBLEM_MEDIA_TYPE = "application/problem+json"
+
+
+class UnsupportedApiVersionError(Exception):
+    status = 400
+
+    def __init__(self, requested: str, supported: Sequence[str]) -> None:
+        super().__init__(f"Unsupported API version {requested!r}; supported: {', '.join(supported)}")
+        self.requested = requested
+        self.supported = tuple(supported)
+
+    def to_problem(self) -> dict[str, Any]:
+        # `about:blank` is the RFC-correct type when the status code already says everything.
+        return {
+            "type": "about:blank",
+            "title": "Unsupported API version",
+            "status": self.status,
+            "detail": str(self),
+            "supported": list(self.supported),
+            "requested": self.requested,
+        }

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/headers.py

@@ -0,0 +1,56 @@
+"""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) —
+protocol literals, not tunables.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from email.utils import format_datetime
+
+from .negotiate import VersionResolution
+from .settings import epoch_seconds
+from .versions import VersionPolicy, get_policy
+
+
+def http_date(day: date) -> str:
+    """IMF-fixdate, the only form RFC 8594 allows: Sat, 01 Aug 2026 00:00:00 GMT."""
+    return format_datetime(datetime(day.year, day.month, day.day, tzinfo=timezone.utc), usegmt=True)
+
+
+def _vary(policy: VersionPolicy) -> str | None:
+    # 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.
+    if policy.settings.strategy == "header":
+        return policy.settings.header_name
+    if policy.settings.strategy == "accept":
+        return "Accept"
+    return None
+
+
+def version_response_headers(
+    resolution: VersionResolution,
+    policy: VersionPolicy | None = None,
+) -> dict[str, str]:
+    policy = policy or get_policy()
+    settings = policy.settings
+    headers: dict[str, str] = {}
+
+    if settings.emit_response_header:
+        headers[settings.header_name] = resolution.version
+
+    vary = _vary(policy)
+    if vary:
+        headers["Vary"] = vary
+
+    deprecation = policy.deprecation_for(resolution.version)
+    if deprecation is None:
+        return headers
+
+    headers["Deprecation"] = f"@{epoch_seconds(deprecation.announced)}"
+    headers["Sunset"] = http_date(deprecation.sunset)
+    if settings.policy_url:
+        url = settings.policy_url
+        headers["Link"] = f'<{url}>; rel="deprecation", <{url}>; rel="sunset"'
+    return headers

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/middleware.py

@@ -0,0 +1,76 @@
+"""Pure ASGI middleware — no framework import, so it wraps FastAPI, Starlette, Litestar or
+a bare ASGI app unchanged."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from .errors import PROBLEM_MEDIA_TYPE, UnsupportedApiVersionError
+from .headers import version_response_headers
+from .negotiate import resolve_version
+from .versions import VersionPolicy, get_policy
+
+Scope = dict[str, Any]
+Message = dict[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+
+class ApiVersionMiddleware:
+    def __init__(self, app: Any, policy: VersionPolicy | None = None) -> None:
+        self.app = app
+        self.policy = policy or get_policy()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            key.decode("latin-1"): value.decode("latin-1") for key, value in scope.get("headers", [])
+        }
+        try:
+            resolution = resolve_version(
+                scope.get("path", "/"),
+                headers,
+                scope.get("query_string", b"").decode("latin-1"),
+                self.policy,
+            )
+        except UnsupportedApiVersionError as error:
+            await _send_problem(send, error)
+            return
+
+        # Readable from a handler as `request.scope["api_version"]`.
+        scope["api_version"] = resolution
+        if isinstance(scope.get("state"), dict):
+            scope["state"]["api_version"] = resolution
+
+        extra = [
+            (name.encode("latin-1"), value.encode("latin-1"))
+            for name, value in version_response_headers(resolution, self.policy).items()
+        ]
+
+        async def send_with_version(message: Message) -> None:
+            if message.get("type") == "http.response.start":
+                message = dict(message)
+                message["headers"] = list(message.get("headers", [])) + extra
+            await send(message)
+
+        await self.app(scope, receive, send_with_version)
+
+
+async def _send_problem(send: Send, error: UnsupportedApiVersionError) -> None:
+    body = json.dumps(error.to_problem()).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": error.status,
+            "headers": [
+                (b"content-type", PROBLEM_MEDIA_TYPE.encode("latin-1")),
+                (b"content-length", str(len(body)).encode("latin-1")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})