Renamed the Web package as Infrastructure (#25)

This PR contains the work done to rename the _Web_ package as _Infrastructure_, to provide a clear naming and purpose to this particular package within the project.

To provide further details about the work:

* Infrastructure
  * Asset fingerprinting: an FNV-1a token derived from the static files directory, appended as ?v= to asset URLs so deploys bust caches; pre-rendered pages also revalidate via weak ETags.
  * New middlewares: fixed-window RateLimitMiddleware (per-client budgets keyed by trusted X-Forwarded-For or remote address) and VaryMiddleware (Accept-Encoding on every response); SecurityHeadersMiddleware now also stamps error responses.
  * Auto-generated HEAD endpoints, cache max-age configuration, and Docker build/Compose refinements.
  * Protocols and scaffolding: Asset/AssetExtension, the Page protocol (viewport, stylesheets, scripts, versioned URLs), and LocalizedRequestContext.
  * Rate limiter's counter store swapped from an actor to a Mutex (no executor hop per request) with amortized batch eviction instead of O(n²) scans under client floods.
  * FingerprintAssets reports unreadable files to a logger instead of silently producing a token that never busts their cache.

Reviewed-on: rock-n-code/loud-amsterdam#25
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Packages/Infrastructure/Package.swift

@@ -16,6 +16,13 @@ let package = Package(
         ),
     ],
     dependencies: [
+        .package(
+            path: "../Localization"
+        ),
+        .package(
+            url: "https://github.com/elementary-swift/elementary.git",
+            from: "0.6.0"
+        ),
         .package(
             url: "https://github.com/hummingbird-project/hummingbird.git",
             from: "2.25.0"
@@ -25,6 +32,11 @@ let package = Package(
         .target(
             name: "Infrastructure",
             dependencies: [
+                .byName(name: "Localization"),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
                 .product(
                     name: "Hummingbird",
                     package: "hummingbird"
@@ -36,12 +48,21 @@ let package = Package(
             name: "InfrastructureTests",
             dependencies: [
                 .byName(name: "Infrastructure"),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
                 .product(
                     name: "HummingbirdTesting",
                     package: "hummingbird"
                 ),
             ],
-            path: "Tests"
+            path: "Tests",
+            resources: [
+                // Copied verbatim rather than processed: the String Catalog is read as raw JSON at
+                // runtime so it resolves identically on Darwin and Linux (which cannot compile it).
+                .copy("Catalogs/Localizable.xcstrings")
+            ]
         ),
     ]
 )

Packages/Infrastructure/README.md

@@ -0,0 +1,34 @@
+# Infrastructure
+The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized HTML responses, and the page and asset scaffolding.
+
+## Overview
+The package provides, grouped by role:
+
+| Role | Types |
+| --- | --- |
+| Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
+| Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
+| Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
+| Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
+| Contexts | `LocalizedRequestContext` |
+
+## Design rules
+The package holds only what every service can reuse; anything a service owns is injected, never referenced:
+
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow.
+- **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
+
+## Layout
+Sources are split by visibility, then by kind, one type per file:
+
+```
+Sources/Public/<Kind>/     public API (Protocols, Middlewares, Responses, …)
+Sources/Internal/<Kind>/   implementation details (e.g. FNV1aHash)
+Tests/Cases/…              mirrors the source layout
+Tests/Utils/…              stubs and test-only extensions
+```
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- macOS 15, matching the sibling `Localization` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).

Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// Hashes bytes with the FNV-1a 64-bit algorithm.
+///
+/// The hash is stable across processes and platforms, which `Hasher` deliberately is not, so it
+/// suits values that must agree between instances and survive restarts: the asset version token
+/// (``FingerprintAssets``) and the entity tags of the pre-rendered pages (`CachedHTMLResponse`).
+/// It is not cryptographic — a collision only risks serving a stale cached asset, not security.
+struct FNV1aHash {
+
+    // MARK: Properties
+
+    /// The running hash value.
+    private var hash: UInt64
+
+    // MARK: Initializers
+
+    /// Creates a hasher at the FNV-1a offset basis.
+    init() {
+        self.hash = 0xcbf2_9ce4_8422_2325
+    }
+
+    // MARK: Computed
+
+    /// The hash of everything combined so far, as a fixed-width, 16-character hexadecimal token.
+    ///
+    /// Reading it does not consume the running hash: more bytes can be combined afterwards.
+    var digest: String {
+        String(
+            format: "%016llx",
+            hash
+        )
+    }
+
+    // MARK: Functions
+
+    /// Folds the given bytes into the hash.
+    /// - Parameter bytes: the bytes to fold in.
+    mutating func combine(
+        _ bytes: some Sequence<UInt8>
+    ) {
+        for byte in bytes {
+            hash = (hash ^ UInt64(byte)) &* 0x100_0000_01b3
+        }
+    }
+
+}

Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift

@@ -0,0 +1,53 @@
+/// A file extension used by an ``Asset``.
+///
+/// Each case's raw value is the extension itself (e.g. `"css"`), which an asset appends to its
+/// file name when resolving paths.
+public enum AssetExtension: String, Sendable {
+    /// A Cascading Style Sheets file.
+    case css
+    /// A JavaScript file.
+    case js
+    /// A Portable Network Graphics image.
+    case png
+    /// A Windows icon image.
+    case ico
+    /// A Scalable Vector Graphics image.
+    case svg
+    /// A plain text file.
+    case txt
+    /// A web application manifest file.
+    case webmanifest
+    /// An Extensible Markup Language file.
+    case xml
+}
+
+// MARK: - Extensions
+
+public extension AssetExtension {
+
+    // MARK: Computed
+
+    /// The file's content type.
+    var contentType: String {
+        switch self {
+        case .css: "text/css"
+        case .js: "text/javascript"
+        case .png: "image/png"
+        case .ico: "image/vnd.microsoft.icon"
+        case .svg: "image/svg+xml"
+        case .txt: "text/plain"
+        case .webmanifest: "application/manifest+json"
+        case .xml: "application/xml"
+        }
+    }
+
+    /// The sub-directory within the static root that holds files with this extension, if any.
+    var subdirectory: String? {
+        switch self {
+        case .css: "css"
+        case .js: "js"
+        default: nil
+        }
+    }
+
+}

Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift

@@ -0,0 +1,12 @@
+import HTTPTypes
+
+public extension HTTPField.Name {
+    /// The `Permissions-Policy` field name (not provided as a standard `HTTPField.Name`).
+    static let permissionsPolicy = Self("Permissions-Policy")!
+    /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
+    static let referrerPolicy = Self("Referrer-Policy")!
+    /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
+    static let frameOptions = Self("X-Frame-Options")!
+    /// The `X-Forwarded-For` field name (not provided as a standard `HTTPField.Name`).
+    static let xForwardedFor = Self("X-Forwarded-For")!
+}

Packages/Infrastructure/Sources/Public/Extensions/Int+Constants.swift

@@ -0,0 +1,9 @@
+extension Int {
+    /// A namespace for the rate limit's default configuration values.
+    public enum RateLimit {
+        /// The default number of requests admitted per client per window.
+        public static let limit = 5
+        /// The default window length, in seconds (1 minute).
+        public static let window = 60
+    }
+}

Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift

@@ -0,0 +1,23 @@
+extension String {
+    /// A namespace for the security headers' default configuration values.
+    ///
+    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is
+    /// "sticky" in browsers, so it stays off unless explicitly configured in production.
+    public enum Security {
+        /// The default `Content-Security-Policy`.
+        ///
+        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins
+        /// (`object-src 'none'`), pins the document base URL (`base-uri 'self'`), and forbids framing
+        /// (`frame-ancestors 'none'`). No inline-style exception is included, so pages must link
+        /// external stylesheets.
+        public static let contentSecurityPolicy = "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
+        /// The default `X-Content-Type-Options` (disables MIME sniffing).
+        public static let contentTypeOptions = "nosniff"
+        /// The default `X-Frame-Options` (forbids framing the page).
+        public static let frameOptions = "DENY"
+        /// The default `Referrer-Policy`.
+        public static let referrerPolicy = "strict-origin-when-cross-origin"
+        /// The default `Permissions-Policy` (denies access to powerful browser features a static site does not use).
+        public static let permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
+    }
+}

Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift

@@ -0,0 +1,85 @@
+import Foundation
+import Logging
+
+/// Derives a version token from the contents of the static files directory.
+///
+/// The token folds every file under the directory — its relative path and its bytes, in a stable order — into one FNV-1a digest, so it changes whenever any
+/// asset changes and agrees across the instances of a deployment. The pages append it to their asset URLs (`?v=<token>`), which lets the assets be
+/// served with a long-lived, immutable cache policy: a deploy that changes an asset changes the URLs pointing at it, so no client ever revalidates or holds a
+/// stale copy.
+public struct FingerprintAssets: Sendable {
+
+    // MARK: Properties
+
+    /// The logger unreadable files are reported to, or `nil` to skip them silently.
+    private let logger: Logger?
+
+    // MARK: Initializers
+
+    /// Creates an asset fingerprinting method.
+    /// - Parameter logger: the logger unreadable files are reported to, or `nil` (the default) to skip them silently.
+    public init(
+        logger: Logger? = nil
+    ) {
+        self.logger = logger
+    }
+
+    // MARK: Functions
+
+    /// Fingerprints the static files under the given directory.
+    ///
+    /// A file that cannot be read is reported to the ``logger`` and left out of the token, so its
+    /// later changes would not bust caches — a warning there usually points at a permissions
+    /// problem in the deployment.
+    /// - Parameter path: the directory the static files are served from.
+    /// - Returns: the version token, or `nil` when the directory holds no readable files (asset URLs are then left unversioned).
+    public func callAsFunction(
+        _ path: String
+    ) -> String? {
+        let manager = FileManager.default
+
+        guard let enumerated = manager.enumerator(atPath: path) else {
+            return nil
+        }
+
+        // The path-based enumerator yields paths relative to the directory, so the token depends
+        // only on the directory's contents — never on where the directory itself lives (the
+        // URL-based enumerator standardizes symlinked bases, e.g. `/var/…` to `/private/var/…`,
+        // which would leak the absolute path into the hash).
+        var files: [String] = []
+
+        while let relativePath = enumerated.nextObject() as? String {
+            if enumerated.fileAttributes?[.type] as? FileAttributeType == .typeRegular {
+                files.append(relativePath)
+            }
+        }
+
+        var hash = FNV1aHash()
+        var hashed = false
+
+        for relativePath in files.sorted() {
+            guard let contents = manager.contents(
+                atPath: "\(path)/\(relativePath)"
+            ) else {
+                logger?.warning(
+                    "Static file could not be read while fingerprinting; the version token will not reflect it.",
+                    metadata: ["path": "\(relativePath)"]
+                )
+
+                continue
+            }
+
+            hash.combine(Array(relativePath.utf8))
+            hash.combine(contents)
+
+            hashed = true
+        }
+
+        guard hashed else {
+            return nil
+        }
+
+        return hash.digest
+    }
+
+}

Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift

@@ -0,0 +1,60 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+import Localization
+
+/// Resolves the visitor's preferred language and records it on the request context.
+///
+/// Placed ahead of the localized responders in the middleware chain, it reads the request's
+/// `Accept-Language` header, negotiates the best supported match (falling back to the default
+/// language), and stores it on the context's ``LocalizedRequestContext/language``.
+///
+/// The request is otherwise passed through untouched — the URL and routing are not affected — so
+/// each page is served at its existing path and varies its content by header.
+public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
+
+    // MARK: Properties
+
+    /// Negotiates the request's language from its `Accept-Language` header.
+    private let negotiate: Negotiate
+
+    // MARK: Initializers
+
+    /// Creates a localization middleware that negotiates against the given bundle's String Catalog languages.
+    /// - Parameter bundle: the bundle whose String Catalog names the supported languages.
+    public init(
+        bundle: Bundle
+    ) {
+        self.negotiate = .init(bundle: bundle)
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension LocalizationMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Negotiates the request's language and records it on the context before passing it down.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var context = context
+
+        context.language = negotiate(
+            acceptLanguage: request.headers[.acceptLanguage]
+        )
+
+        return try await next(request, context)
+    }
+
+}

Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift

@@ -0,0 +1,74 @@
+import Elementary
+import Foundation
+import Hummingbird
+
+/// Serves a custom error page for requests that match neither a route nor a static file.
+///
+/// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error that bubbles up when no file exists for the requested
+/// path and responds with the rendered error page and a `404 Not Found` status. The page is served in the language stored on the context by
+/// ``LocalizationMiddleware``, falling back to the default language.
+public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
+
+    // MARK: Properties
+
+    /// The error page, rendered once per supported language and reused for every not-found response.
+    private let responses: LocalizedHTMLCollectionResponse
+
+    // MARK: Initializers
+
+    /// Creates a not-found middleware.
+    /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog names the languages the page is rendered for.
+    ///   - document: builds the error page to render for a given locale.
+    public init<Document: HTMLDocument>(
+        bundle: Bundle,
+        document: (Locale) -> Document
+    ) {
+        self.responses = .init(
+            bundle: bundle,
+            status: .notFound,
+            document: document
+        )
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension NotFoundMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain, rendering the error page if it results in a not-found response.
+    ///
+    /// Any error other than `.notFound` is rethrown unchanged.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response, or the rendered error page with a `404 Not Found` status.
+    /// - Throws: any non-not-found error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        do {
+            return try await next(request, context)
+        }
+        catch let error {
+            guard
+                let responseError = error as? any HTTPResponseError,
+                responseError.status == .notFound
+            else {
+                throw error
+            }
+
+            return responses.response(
+                for: context.language,
+                request: request
+            )
+        }
+    }
+
+}

Packages/Infrastructure/Sources/Public/Middlewares/RateLimitMiddleware.swift

@@ -0,0 +1,291 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+import NIOCore
+import Synchronization
+
+/// Rejects a client's requests with `429 Too Many Requests` once they exceed a fixed-window rate limit.
+///
+/// Added to the routes that must not be hammered — the subscription endpoint, an unauthenticated database write — it admits up to the configured limit of
+/// requests per client per window, and answers the excess with `429 Too Many Requests` and a `Retry-After` header naming the seconds until the
+/// window resets.
+///
+/// A client is keyed by the first `X-Forwarded-For` entry when the ``Configuration`` trusts it, by the connection's remote address otherwise, and by
+/// one shared bucket when neither names the client. The counters live in memory with a bounded capacity, so a flood of distinct clients cannot grow the
+/// store without bound — and each instance of a multi-instance deployment enforces its own budget.
+public struct RateLimitMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The fixed-window request counters, keyed by client.
+    private let buckets: Buckets
+
+    /// The limits the middleware enforces.
+    private let configuration: Configuration
+
+    // MARK: Initializers
+
+    /// Creates a rate-limit middleware.
+    /// - Parameter configuration: the limits the middleware enforces. Defaults to a budget suited to a form endpoint: a handful of requests per
+    ///   client per minute.
+    public init(
+        configuration: Configuration = .init()
+    ) {
+        self.buckets = .init(
+            limit: configuration.limit,
+            window: configuration.window
+        )
+        self.configuration = configuration
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension RateLimitMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain while the client stays within its budget, and answers it with `429 Too Many Requests` and a `Retry-After`
+    /// header once it does not.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response, or the `429` rejection.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        let admission = buckets.admit(
+            client(
+                for: request,
+                context: context
+            )
+        )
+
+        switch admission {
+        case .admitted:
+            return try await next(
+                request,
+                context
+            )
+        case .limited(let retryAfter):
+            var response = Response(status: .tooManyRequests)
+
+            response.headers[.retryAfter] = String(max(1, retryAfter.components.seconds))
+
+            return response
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RateLimitMiddleware {
+
+    // MARK: Methods
+
+    /// The key identifying the requesting client: the first `X-Forwarded-For` entry when trusted, the connection's remote address otherwise, and one
+    /// bucket shared by every unidentifiable client when neither is known.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    /// - Returns: the client key the request is counted under.
+    func client(
+        for request: Request,
+        context: Context
+    ) -> String {
+        if
+            configuration.trustForwardedFor,
+            let forwarded = request.headers[.xForwardedFor]?
+                .split(separator: ",")
+                .first?
+                .trimmingCharacters(in: .whitespaces),
+            !forwarded.isEmpty
+        {
+            return forwarded
+        }
+
+        if let address = (context as? any RemoteAddressRequestContext)?.remoteAddress {
+            return address.ipAddress
+                ?? address.description
+        }
+
+        return .unidentified
+    }
+
+}
+
+// MARK: - Buckets
+
+private extension RateLimitMiddleware {
+
+    /// The outcome of asking the ``Buckets`` store to admit a request.
+    enum Admission {
+        /// The request is within the client's budget.
+        case admitted
+        /// The client exhausted its budget; the payload is the time until its window resets.
+        case limited(retryAfter: Duration)
+    }
+
+    /// The fixed-window request counters, keyed by client.
+    ///
+    /// The counters sit behind a mutex rather than an actor: an admission is a handful of dictionary operations, so the lock is held only briefly and the
+    /// calling task never suspends — requests skip the executor hop an actor would add on every pass through the middleware.
+    final class Buckets: Sendable {
+
+        // MARK: Properties
+
+        /// The maximum number of clients tracked at once, bounding the store's memory.
+        private let capacity: Int
+
+        /// The per-client counters: the start of the client's current window and its request count.
+        private let counters: Mutex<[String: (start: ContinuousClock.Instant, count: Int)]>
+
+        /// The number of requests admitted per client per ``window``.
+        private let limit: Int
+
+        /// The length of the fixed window the ``limit`` applies to.
+        private let window: Duration
+
+        // MARK: Initializers
+
+        /// Creates a counter store.
+        /// - Parameters:
+        ///   - limit: the number of requests admitted per client per window.
+        ///   - window: the length of the fixed window the limit applies to.
+        ///   - capacity: the maximum number of clients tracked at once.
+        init(
+            limit: Int,
+            window: Duration,
+            capacity: Int = 10_000
+        ) {
+            self.capacity = capacity
+            self.counters = .init([:])
+            self.limit = limit
+            self.window = window
+        }
+
+        // MARK: Functions
+
+        /// Counts a request against the client's current window and admits it while the count stays within the limit.
+        /// - Parameter client: the key the request is counted under.
+        /// - Returns: the admission outcome.
+        func admit(
+            _ client: String
+        ) -> Admission {
+            let now = ContinuousClock.now
+
+            return counters.withLock { counters in
+                if let counter = counters[client], now < counter.start.advanced(by: window) {
+                    guard counter.count < limit else {
+                        return .limited(retryAfter: now.duration(to: counter.start.advanced(by: window)))
+                    }
+
+                    counters[client] = (counter.start, counter.count + 1)
+
+                    return .admitted
+                }
+
+                makeRoom(
+                    in: &counters,
+                    at: now
+                )
+
+                counters[client] = (now, 1)
+
+                return .admitted
+            }
+        }
+
+        // MARK: Methods
+
+        /// Keeps the store within its capacity before a new client is tracked: expired windows are dropped first, and when the store remains full, the
+        /// oldest live windows are evicted in one batch — a tenth of the capacity — so the sort that finds them runs once per batch of admissions
+        /// instead of once per request while a flood of distinct clients keeps the store full.
+        /// - Parameters:
+        ///   - counters: the counters the room is made in.
+        ///   - now: the instant the expiry is evaluated against.
+        private func makeRoom(
+            in counters: inout [String: (start: ContinuousClock.Instant, count: Int)],
+            at now: ContinuousClock.Instant
+        ) {
+            guard counters.count >= capacity else {
+                return
+            }
+
+            counters = counters.filter {
+                now < $0.value.start.advanced(by: window)
+            }
+
+            let headroom = max(1, capacity / 10)
+            let excess = counters.count - (capacity - headroom)
+
+            guard excess > 0 else {
+                return
+            }
+
+            let oldest = counters
+                .sorted { $0.value.start < $1.value.start }
+                .prefix(excess)
+
+            for counter in oldest {
+                counters.removeValue(forKey: counter.key)
+            }
+        }
+
+    }
+
+}
+
+// MARK: - Configuration
+
+extension RateLimitMiddleware {
+    /// The limits a ``RateLimitMiddleware`` enforces.
+    public struct Configuration: Sendable {
+
+        // MARK: Properties
+
+        /// The number of requests admitted per client per ``window``.
+        public let limit: Int
+
+        /// Whether a client is keyed by the first `X-Forwarded-For` entry.
+        ///
+        /// Enable it only behind a reverse proxy that sets the header — there, the connection's own address would name the proxy for every visitor,
+        /// sharing one budget across all of them. On a directly reachable server the header is client-supplied, so trusting it lets a client forge fresh keys
+        /// at will.
+        public let trustForwardedFor: Bool
+
+        /// The length of the fixed window the ``limit`` applies to.
+        public let window: Duration
+
+        // MARK: Initializers
+
+        /// Creates a rate-limit configuration.
+        /// - Parameters:
+        ///   - limit: the number of requests admitted per client per window.
+        ///   - window: the length of the fixed window the limit applies to.
+        ///   - trustForwardedFor: whether a client is keyed by the first `X-Forwarded-For` entry.
+        public init(
+            limit: Int = .RateLimit.limit,
+            window: Duration = .seconds(Int.RateLimit.window),
+            trustForwardedFor: Bool = false
+        ) {
+            self.limit = limit
+            self.trustForwardedFor = trustForwardedFor
+            self.window = window
+        }
+
+    }
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    /// The bucket shared by every client the middleware cannot identify.
+    static let unidentified = "unidentified"
+}

Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift

@@ -0,0 +1,161 @@
+import HTTPTypes
+import Hummingbird
+
+/// Stamps a set of security-related HTTP headers onto every response.
+///
+/// Placed at (or near) the top of the middleware chain, it adds the configured headers to whatever
+/// response bubbles back up — the rendered pages, the error page produced by
+/// ``NotFoundMiddleware``, and every static file served by `FileMiddleware` — so the browser applies
+/// the strict, hardened interpretation of the content instead of its lenient legacy defaults.
+///
+/// The headers are precomputed once from the ``Configuration`` at initialization and reused for
+/// every request, so the per-request cost is a handful of header copies.
+public struct SecurityHeadersMiddleware<Context: RequestContext> {
+
+    // MARK: Properties
+
+    /// The precomputed headers applied to every response.
+    private let fields: HTTPFields
+
+    // MARK: Initializers
+
+    /// Creates a security-headers middleware.
+    /// - Parameter configuration: the headers applied to every response. Defaults to a hardened
+    ///   baseline suitable for a static site, with `Strict-Transport-Security` left off (see
+    ///   ``Configuration``).
+    public init(
+        configuration: Configuration = .init()
+    ) {
+        self.fields = configuration.fields
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension SecurityHeadersMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain and stamps the configured security headers onto the
+    /// response on the way back up.
+    ///
+    /// Errors that can render themselves (`HTTPResponseError`, like the `HTTPError`s thrown by the
+    /// controllers) are converted to their response here rather than left to the router: the router
+    /// converts them above the middleware chain, where the response would escape these headers.
+    /// Existing values for the same header names are replaced so downstream middleware cannot leave
+    /// a weaker policy in place.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response with the security headers applied.
+    /// - Throws: any downstream error that does not render as an HTTP response.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var response: Response
+
+        do {
+            response = try await next(
+                request,
+                context
+            )
+        } catch let error as any HTTPResponseError {
+            response = try error.response(
+                from: request,
+                context: context
+            )
+        }
+
+        for field in fields {
+            response.headers[field.name] = field.value
+        }
+
+        return response
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension SecurityHeadersMiddleware.Configuration {
+
+    // MARK: Computed
+
+    /// The configuration expressed as the headers to apply, omitting any whose value is `nil`.
+    var fields: HTTPFields {
+        var fields = HTTPFields()
+
+        fields[.contentSecurityPolicy] = contentSecurityPolicy
+        fields[.xContentTypeOptions] = contentTypeOptions
+        fields[.frameOptions] = frameOptions
+        fields[.referrerPolicy] = referrerPolicy
+        fields[.permissionsPolicy] = permissionsPolicy
+        fields[.strictTransportSecurity] = strictTransportSecurity
+
+        return fields
+    }
+
+}
+
+// MARK: - Configuration
+
+extension SecurityHeadersMiddleware {
+    /// The set of security headers a ``SecurityHeadersMiddleware`` applies.
+    ///
+    /// Each property maps to a single response header. A `nil` value omits that header entirely,
+    /// which is how `Strict-Transport-Security` stays disabled by default: it is only safe to send
+    /// over HTTPS and is "sticky" in browsers, so it must stay off in plain-HTTP development and be
+    /// switched on (via configuration) only in TLS-terminated production.
+    public struct Configuration: Sendable {
+        
+        // MARK: Properties
+        
+        /// The `Content-Security-Policy` value (controls which sources the browser will load).
+        public let contentSecurityPolicy: String?
+        /// The `X-Content-Type-Options` value (disables MIME sniffing when set to `nosniff`).
+        public let contentTypeOptions: String?
+        /// The `X-Frame-Options` value (controls whether the page may be framed).
+        public let frameOptions: String?
+        /// The `Referrer-Policy` value (controls how much referrer information is shared).
+        public let referrerPolicy: String?
+        /// The `Permissions-Policy` value (gates access to powerful browser features).
+        public let permissionsPolicy: String?
+        /// The `Strict-Transport-Security` value, or `nil` to omit the header (the default).
+        public let strictTransportSecurity: String?
+        
+        // MARK: Initializers
+        
+        /// Creates a security-headers configuration.
+        ///
+        /// Every parameter defaults to the hardened baseline defined in `String.Security`, except
+        /// `strictTransportSecurity`, which defaults to `nil` (omitted). Pass `nil` for any header
+        /// to drop it from the response.
+        /// - Parameters:
+        ///   - contentSecurityPolicy: the `Content-Security-Policy` value.
+        ///   - contentTypeOptions: the `X-Content-Type-Options` value.
+        ///   - frameOptions: the `X-Frame-Options` value.
+        ///   - referrerPolicy: the `Referrer-Policy` value.
+        ///   - permissionsPolicy: the `Permissions-Policy` value.
+        ///   - strictTransportSecurity: the `Strict-Transport-Security` value, or `nil` to omit it.
+        public init(
+            contentSecurityPolicy: String? = String.Security.contentSecurityPolicy,
+            contentTypeOptions: String? = String.Security.contentTypeOptions,
+            frameOptions: String? = String.Security.frameOptions,
+            referrerPolicy: String? = String.Security.referrerPolicy,
+            permissionsPolicy: String? = String.Security.permissionsPolicy,
+            strictTransportSecurity: String? = nil
+        ) {
+            self.contentSecurityPolicy = contentSecurityPolicy
+            self.contentTypeOptions = contentTypeOptions
+            self.frameOptions = frameOptions
+            self.referrerPolicy = referrerPolicy
+            self.permissionsPolicy = permissionsPolicy
+            self.strictTransportSecurity = strictTransportSecurity
+        }
+        
+    }
+}

Packages/Infrastructure/Sources/Public/Middlewares/VaryMiddleware.swift

@@ -0,0 +1,71 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+
+/// Appends header names to the `Vary` header of every response passing through.
+///
+/// Placed just above the response-compression middleware, it marks each response as varying on `Accept-Encoding`: the static files and pre-rendered
+/// pages are served with `Cache-Control: public`, so without the signal a shared cache could store a compressed body and hand it to a client that
+/// never advertised support for the encoding.
+///
+/// Names already present on a response's `Vary` header — such as the `Accept-Language` the localized pages carry — are kept, and duplicates are not
+/// added.
+public struct VaryMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The header names appended to every response's `Vary` header.
+    private let names: [String]
+
+    // MARK: Initializers
+
+    /// Creates a vary middleware.
+    /// - Parameter fields: the header names appended to every response's `Vary` header. Defaults to `Accept-Encoding`, the request header
+    ///   the response-compression middleware acts on.
+    public init(
+        fields: [HTTPField.Name] = [.acceptEncoding]
+    ) {
+        self.names = fields.map(\.rawName)
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension VaryMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain and appends the configured names to the response's `Vary` header on the way back up.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response with the `Vary` names applied.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var response = try await next(
+            request,
+            context
+        )
+
+        var vary = response.headers[.vary]?
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespaces) } ?? []
+
+        for name in names where !vary.contains(where: {
+            $0.caseInsensitiveCompare(name) == .orderedSame
+        }) {
+            vary.append(name)
+        }
+
+        response.headers[.vary] = vary.joined(separator: ", ")
+
+        return response
+    }
+
+}

Packages/Infrastructure/Sources/Public/Protocols/Asset.swift

@@ -0,0 +1,81 @@
+/// An asset shipped with a website: a file stored under the static files root and served by
+/// Hummingbird's `FileMiddleware` middleware.
+///
+/// A conforming asset supplies its file name and the extensions it is available with, each
+/// resolving to its own file; the protocol derives the paths from them: the file's path within
+/// the static files root and the URL path it is served at, optionally versioned to bust caches.
+public protocol Asset: Sendable {
+
+    // MARK: Properties
+
+    /// The file extensions the asset is available with.
+    var fileExtensions: [AssetExtension] { get }
+
+    /// The asset's file name, without extension.
+    var fileName: String { get }
+
+}
+
+// MARK: - Implementations
+
+public extension Asset {
+
+    // MARK: Methods
+
+    /// Resolves the asset's path against the given base directory.
+    ///
+    /// - Parameters:
+    ///   - basePath: the directory the static files are served from.
+    ///   - fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the `basePath` path.
+    func path(
+        relativeTo basePath: String,
+        for fileExtension: AssetExtension
+    ) -> String {
+        let relativePath = relativePath(for: fileExtension)
+
+        guard !basePath.isEmpty else {
+            return relativePath
+        }
+
+        return "\(basePath)/\(relativePath)"
+    }
+
+    /// Resolves the asset's path relative to the static files root (e.g. `"css/shared.css"`).
+    ///
+    /// This also matches the URL path the file is served at by `FileMiddleware`.
+    ///
+    /// - Parameter fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the static files root.
+    func relativePath(
+        for fileExtension: AssetExtension
+    ) -> String {
+        let file = "\(fileName).\(fileExtension.rawValue)"
+
+        return fileExtension.subdirectory
+            .map { "\($0)/\(file)" } ?? file
+    }
+
+    /// Resolves the absolute URL path the asset is served at (e.g. `"/css/shared.css"`).
+    ///
+    /// A version token appends as a `v` query parameter (e.g. `"/css/shared.css?v=abc123"`):
+    /// `FileMiddleware` ignores the query when resolving the file, while caches key on the full
+    /// URL, so a deploy that changes the assets busts every cached copy at once.
+    /// - Parameters:
+    ///   - fileExtension: the extension of the file to resolve.
+    ///   - version: the version token to append, or `nil` to leave the URL unversioned.
+    /// - Returns: the path to use in `href` and `src` attributes.
+    func urlPath(
+        for fileExtension: AssetExtension,
+        version: String? = nil
+    ) -> String {
+        let path = "/\(relativePath(for: fileExtension))"
+
+        guard let version, !version.isEmpty else {
+            return path
+        }
+
+        return "\(path)?v=\(version)"
+    }
+
+}

Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift

@@ -0,0 +1,15 @@
+import Hummingbird
+
+/// A request context that carries the language negotiated for the request.
+///
+/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language`
+/// header and stores it here, so downstream controllers and middleware can serve the matching
+/// localization without re-reading the header.
+public protocol LocalizedRequestContext: RequestContext {
+
+    // MARK: Properties
+
+    /// The language identifier negotiated for the request.
+    var language: String { get set }
+
+}

Packages/Infrastructure/Sources/Public/Protocols/Page.swift

@@ -0,0 +1,87 @@
+import Elementary
+import Foundation
+
+/// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
+///
+/// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
+/// rest of the document around them: the viewport declaration and stylesheet links followed by the metadata in the head, and the content followed by
+/// the script tags in the body.
+public protocol Page: HTMLDocument, Sendable {
+
+    // MARK: Associated types
+
+    /// The type of the page's markup.
+    associatedtype Content: HTML
+
+    /// The type of the page's head metadata markup.
+    associatedtype Metadata: HTML
+
+    // MARK: Properties
+
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    var assetVersion: String? { get }
+
+    /// The page's markup, rendered before the ``scripts``.
+    @HTMLBuilder
+    var content: Content { get }
+
+    /// The locale the page content is localized to.
+    var locale: Locale { get }
+
+    /// The markup placed in the document head after the ``stylesheets``: icon and manifest
+    /// links, extra meta tags, and the like.
+    @HTMLBuilder
+    var metadata: Metadata { get }
+
+    /// The scripts loaded at the end of the document body, in order.
+    var scripts: [any Asset] { get }
+
+    /// The stylesheets linked in the document head, in order.
+    var stylesheets: [any Asset] { get }
+
+}
+
+// MARK: - Implementations
+
+public extension Page {
+
+    // MARK: Computed
+
+    /// The page ``content`` followed by its ``scripts``.
+    @HTMLBuilder
+    var body: some HTML {
+        content
+
+        for file in scripts {
+            script(.src(file.urlPath(
+                for: .js,
+                version: assetVersion
+            ))) {}
+        }
+    }
+
+    /// The viewport declaration and ``stylesheets`` links followed by the ``metadata``, placed in the document head.
+    ///
+    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already
+    /// emits `<meta charset="UTF-8">` before this markup, and HTML5 allows only one.
+    @HTMLBuilder
+    var head: some HTML {
+        meta(
+            .name(.viewport),
+            .content("width=device-width, initial-scale=1")
+        )
+
+        metadata
+
+        for file in stylesheets {
+            link(
+                .rel(.stylesheet),
+                .href(file.urlPath(
+                    for: .css,
+                    version: assetVersion
+                ))
+            )
+        }
+    }
+
+}

Packages/Infrastructure/Sources/Public/Responses/CachedHTMLResponse.swift

@@ -0,0 +1,114 @@
+import Elementary
+import HTTPTypes
+import Hummingbird
+import NIOCore
+
+/// A pre-rendered HTTP response for a fully static HTML page.
+///
+/// The document is rendered to bytes once, at initialization, and every ``response(for:)`` reuses those bytes — along with a fixed status and
+/// precomputed headers — instead of re-rendering. This suits pages whose markup never changes between requests, such as the landing page and the
+/// not-found page, avoiding a per-request Elementary render on hot paths.
+///
+/// A successful page also revalidates cheaply: its headers carry a weak entity tag derived from the rendered bytes and a `Cache-Control` that asks
+/// clients to revalidate (`no-cache`), so a repeat visit costs a `304 Not Modified` instead of a full transfer — and a deploy that changes the page
+/// changes the tag, propagating immediately.
+///
+/// ``LocalizedHTMLCollectionResponse`` builds on this type, caching one instance per supported language.
+///
+/// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the response-compression middleware downstream
+/// treats it exactly as it would a freshly rendered page.
+public struct CachedHTMLResponse: Sendable {
+
+    // MARK: Properties
+
+    /// The page rendered to bytes once.
+    private let buffer: ByteBuffer
+
+    /// The weak entity tag of the rendered bytes, present on successful pages only.
+    private let eTag: String?
+
+    /// The headers applied to every response, precomputed once.
+    private let headers: HTTPFields
+
+    /// The status applied to every response.
+    private let status: HTTPResponse.Status
+
+    // MARK: Initializers
+
+    /// Renders the given document to bytes once.
+    ///
+    /// A `200 OK` page gets the revalidation headers (`ETag` and `Cache-Control`); an error page does not, since a `304 Not Modified` only
+    /// ever stands in for a success.
+    /// - Parameters:
+    ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - additionalHeaders: extra headers merged onto every response, alongside the content type.
+    ///     Used to carry per-language signals such as `Content-Language` and `Vary`.
+    ///   - document: the static HTML document to render and cache.
+    public init(
+        status: HTTPResponse.Status = .ok,
+        additionalHeaders: HTTPFields = [:],
+        document: some HTMLDocument
+    ) {
+        let buffer = ByteBuffer(string: document.render())
+        var headers: HTTPFields = [
+            .contentType: "text/html; charset=utf-8"
+        ]
+        var eTag: String?
+
+        if status == .ok {
+            var hash = FNV1aHash()
+
+            hash.combine(buffer.readableBytesView)
+
+            eTag = "W/\"\(hash.digest)\""
+
+            headers[.eTag] = eTag
+            headers[.cacheControl] = "public, no-cache"
+        }
+
+        for field in additionalHeaders {
+            headers[field.name] = field.value
+        }
+
+        self.buffer = buffer
+        self.eTag = eTag
+        self.headers = headers
+        self.status = status
+    }
+
+    // MARK: Methods
+
+    /// Builds a response from the cached, pre-rendered bytes.
+    ///
+    /// A conditional request whose `If-None-Match` names the page's entity tag is answered with a
+    /// bodyless `304 Not Modified`. Otherwise the full page is served, mirroring the
+    /// `text/html; charset=utf-8` content type `HTMLResponse` produces and leaving the
+    /// `Content-Length` unset so small pages remain eligible for compression.
+    /// - Parameter request: the request the response answers.
+    /// - Returns: the response carrying the cached HTML body, or its `304` revalidation.
+    public func response(
+        for request: Request
+    ) -> Response {
+        if
+            let eTag,
+            request.method == .get || request.method == .head,
+            let match = request.headers[.ifNoneMatch],
+            match == "*" || match.contains(eTag)
+        {
+            return Response(
+                status: .notModified,
+                headers: headers
+            )
+        }
+
+        return Response(
+            status: status,
+            headers: headers,
+            body: .init { [buffer] writer in
+                try await writer.write(buffer)
+                try await writer.finish(nil)
+            }
+        )
+    }
+
+}

Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift

@@ -0,0 +1,76 @@
+import Elementary
+import Foundation
+import HTTPTypes
+import Hummingbird
+import Localization
+
+/// A per-language collection of pre-rendered HTML responses.
+///
+/// At initialization it renders the document once for each language the bundle's ``LanguageList``
+/// reports and caches the bytes, mirroring ``CachedHTMLResponse``'s render-once model but keyed by
+/// language. Each cached response carries a `Content-Language` header and `Vary: Accept-Language`, so
+/// shared caches key on the negotiated language instead of serving one language to everyone.
+public struct LocalizedHTMLCollectionResponse: Sendable {
+
+    // MARK: Properties
+
+    /// The supported languages and default language, derived from the bundle's String Catalog.
+    private let list: LanguageList
+
+    /// The pre-rendered responses, keyed by language identifier.
+    private let responses: [String: CachedHTMLResponse]
+
+    // MARK: Initializers
+
+    /// Renders the document once per supported language.
+    /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog names the languages the document is rendered for.
+    ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - document: builds the document to render for a given locale.
+    public init<Document: HTMLDocument>(
+        bundle: Bundle,
+        status: HTTPResponse.Status = .ok,
+        document: (Locale) -> Document
+    ) {
+        self.list = .init(bundle: bundle)
+        self.responses = list.all
+            .reduce(into: [:]) { responses, language in
+                responses[language] = CachedHTMLResponse(
+                    status: status,
+                    additionalHeaders: [
+                        .contentLanguage: language,
+                        .vary: "Accept-Language",
+                    ],
+                    document: document(.init(
+                        identifier: language
+                    ))
+                )
+            }
+    }
+
+    // MARK: Methods
+
+    /// Builds the response for the given language, falling back to the default language.
+    /// - Parameters:
+    ///   - language: the negotiated language identifier.
+    ///   - request: the request the response answers, consulted for conditional revalidation.
+    /// - Returns: the cached response for the language, the default language's response when the
+    ///   language is unavailable, or a `500 Internal Server Error` if neither is cached.
+    public func response(
+        for language: String,
+        request: Request
+    ) -> Response {
+        guard
+            let response = responses[language] ?? responses[list.default]
+        else {
+            return .init(
+                status: .internalServerError
+            )
+        }
+
+        return response.response(
+            for: request
+        )
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift

@@ -0,0 +1,76 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("FNV1aHash type")
+struct FNV1aHashTests {
+
+    // MARK: Functional tests
+
+    @Test(arguments: [
+        ("", "cbf29ce484222325"),
+        ("a", "af63dc4c8601ec8c"),
+        ("b", "af63df4c8601f1a5"),
+        ("foobar", "85944171f73967e8"),
+    ])
+    func `matches the published FNV-1a 64-bit test vectors`(
+        input: String,
+        digest: String
+    ) {
+        var hash = FNV1aHash()
+
+        hash.combine(input.utf8)
+
+        #expect(hash.digest == digest)
+    }
+
+    @Test
+    func `pads the digest to sixteen characters`() {
+        var hash = FNV1aHash()
+
+        // "aa" hashes to 0x089c4307b54596b7, whose leading zero the digest must keep.
+        hash.combine("aa".utf8)
+
+        #expect(hash.digest == "089c4307b54596b7")
+        #expect(hash.digest.count == 16)
+    }
+
+    @Test
+    func `hashes incrementally combined bytes as one stream`() {
+        var combined = FNV1aHash()
+        var whole = FNV1aHash()
+
+        combined.combine("foo".utf8)
+        combined.combine("bar".utf8)
+        whole.combine("foobar".utf8)
+
+        #expect(combined.digest == whole.digest)
+    }
+
+    @Test
+    func `distinguishes the order of the combined bytes`() {
+        var forward = FNV1aHash()
+        var backward = FNV1aHash()
+
+        forward.combine("ab".utf8)
+        backward.combine("ba".utf8)
+
+        #expect(forward.digest != backward.digest)
+    }
+
+    @Test
+    func `digests without consuming the running hash`() {
+        var hash = FNV1aHash()
+
+        hash.combine("foo".utf8)
+
+        let first = hash.digest
+
+        #expect(hash.digest == first)
+
+        hash.combine("bar".utf8)
+
+        #expect(hash.digest != first)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift

@@ -0,0 +1,71 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("AssetExtension enumeration")
+struct AssetExtensionTests {
+
+    // MARK: Computed tests
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.contentTypes
+    ))
+    func `content type`(
+        for fileExtension: AssetExtension,
+        expects contentType: String
+    ) {
+        #expect(fileExtension.contentType == contentType)
+    }
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.subdirectories
+    ))
+    func `subdirectory`(
+        for fileExtension: AssetExtension,
+        expects subdirectory: String?
+    ) {
+        #expect(fileExtension.subdirectory == subdirectory)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension AssetExtensionTests {
+
+    // MARK: Constants
+
+    static let extensions: [AssetExtension] = [
+        .css,
+        .js,
+        .png,
+        .ico,
+        .svg,
+        .txt,
+        .webmanifest,
+        .xml
+    ]
+    static let contentTypes: [String] = [
+        "text/css",
+        "text/javascript",
+        "image/png",
+        "image/vnd.microsoft.icon",
+        "image/svg+xml",
+        "text/plain",
+        "application/manifest+json",
+        "application/xml"
+    ]
+    static let subdirectories: [String?] = [
+        "css",
+        "js",
+        nil,
+        nil,
+        nil,
+        nil,
+        nil,
+        nil
+    ]
+
+}

Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift

@@ -0,0 +1,171 @@
+import Foundation
+import Testing
+
+@testable import Infrastructure
+
+@Suite("FingerprintAssets method")
+struct FingerprintAssetsTests {
+
+    // MARK: Properties
+
+    private let fingerprint = FingerprintAssets()
+
+    // MARK: Functional tests
+
+    @Test
+    func `fingerprints the files under a directory`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }",
+            "robots.txt": "User-agent: *"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let token = try #require(fingerprint(directory.path))
+
+        #expect(token.count == 16)
+        #expect(token.allSatisfy { $0.isHexDigit })
+    }
+
+    @Test
+    func `agrees across directories with identical contents`() throws {
+        let files = [
+            "css/site.css": "body { margin: 0; }",
+            "js/site.js": "console.log(1);"
+        ]
+        let first = try makeDirectory(files: files)
+        let second = try makeDirectory(files: files)
+
+        defer {
+            removeDirectory(first)
+            removeDirectory(second)
+        }
+
+        #expect(fingerprint(first.path) == fingerprint(second.path))
+    }
+
+    @Test
+    func `changes the token when a file's contents change`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let before = fingerprint(directory.path)
+
+        try "body { margin: 1px; }".write(
+            to: directory.appendingPathComponent("css/site.css"),
+            atomically: true,
+            encoding: .utf8
+        )
+
+        #expect(fingerprint(directory.path) != before)
+    }
+
+    @Test
+    func `changes the token when a file is renamed`() throws {
+        let contents = "body { margin: 0; }"
+        let first = try makeDirectory(files: ["css/site.css": contents])
+        let second = try makeDirectory(files: ["css/main.css": contents])
+
+        defer {
+            removeDirectory(first)
+            removeDirectory(second)
+        }
+
+        #expect(fingerprint(first.path) != fingerprint(second.path))
+    }
+
+    @Test
+    func `changes the token when a file is added`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let before = fingerprint(directory.path)
+
+        try "console.log(1);".write(
+            to: directory.appendingPathComponent("site.js"),
+            atomically: true,
+            encoding: .utf8
+        )
+
+        #expect(fingerprint(directory.path) != before)
+    }
+
+    @Test
+    func `returns nil for a directory without files`() throws {
+        let directory = try makeDirectory(files: [:])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        #expect(fingerprint(directory.path) == nil)
+    }
+
+    @Test
+    func `returns nil for a missing directory`() {
+        let missing = FileManager.default.temporaryDirectory
+            .appendingPathComponent("FingerprintAssetsTests-missing-\(UUID().uuidString)")
+
+        #expect(fingerprint(missing.path) == nil)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension FingerprintAssetsTests {
+
+    // MARK: Methods
+
+    /// Creates a unique temporary directory holding the given files, keyed by relative path.
+    /// - Parameter files: the files to create, keyed by their path relative to the directory.
+    /// - Returns: the URL of the created directory.
+    func makeDirectory(
+        files: [String: String]
+    ) throws -> URL {
+        let directory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("FingerprintAssetsTests-\(UUID().uuidString)")
+
+        try FileManager.default.createDirectory(
+            at: directory,
+            withIntermediateDirectories: true
+        )
+
+        for (relativePath, contents) in files {
+            let file = directory.appendingPathComponent(relativePath)
+
+            try FileManager.default.createDirectory(
+                at: file.deletingLastPathComponent(),
+                withIntermediateDirectories: true
+            )
+            try contents.write(
+                to: file,
+                atomically: true,
+                encoding: .utf8
+            )
+        }
+
+        return directory
+    }
+
+    /// Removes a temporary directory created by ``makeDirectory(files:)``.
+    /// - Parameter directory: the URL of the directory to remove.
+    func removeDirectory(
+        _ directory: URL
+    ) {
+        try? FileManager.default.removeItem(at: directory)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift

@@ -0,0 +1,69 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import Infrastructure
+
+@Suite("LocalizationMiddleware middleware", .tags(.middleware))
+struct LocalizationMiddlewareTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+        }
+
+        router.get("language") { _, context in
+            context.language
+        }
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `negotiates a supported language from the header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get,
+                headers: [.acceptLanguage: "de-DE,de;q=0.9"]
+            ) { response in
+                #expect(String(buffer: response.body) == "de")
+            }
+        }
+    }
+
+    @Test
+    func `falls back to the default without a header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+    @Test
+    func `falls back to the default for an unsupported language`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get,
+                headers: [.acceptLanguage: "fr-FR,fr;q=0.9"]
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift

@@ -0,0 +1,191 @@
+import Foundation
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import Infrastructure
+
+@Suite("NotFoundMiddleware middleware", .tags(.middleware))
+struct NotFoundMiddlewareTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+            NotFoundMiddleware(bundle: .module) {
+                StubPage(locale: $0)
+            }
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get("boom") { _, _ -> String in
+            throw HTTPError(.badRequest)
+        }
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `renders the error page for an unmatched request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.headers[.contentLanguage] == "en")
+                #expect(response.headers[.vary] == "Accept-Language")
+                #expect(body.contains("Stub content"))
+            }
+        }
+    }
+
+    @Test
+    func `renders the error page in the negotiated language`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get,
+                headers: [.acceptLanguage: "de-DE,de;q=0.9"]
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentLanguage] == "de")
+            }
+        }
+    }
+
+    @Test
+    func `passes a matched response through untouched`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.body == ByteBuffer(string: "Hello!"))
+            }
+        }
+    }
+
+    @Test
+    func `rethrows a non-not-found error unchanged`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/boom",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .badRequest)
+                #expect(!body.contains("Stub content"))
+            }
+        }
+    }
+
+    @Test
+    func `renders versioned asset URLs when given a version`() async throws {
+        try await app(
+            assetVersion: "0123456789abcdef"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/stub.css?v=0123456789abcdef"))
+                #expect(body.contains("/js/stub.js?v=0123456789abcdef"))
+            }
+        }
+    }
+
+    @Test
+    func `renders unversioned asset URLs by default`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains(#"href="/css/stub.css""#))
+                #expect(!body.contains("?v="))
+            }
+        }
+    }
+
+    @Test
+    func `serves the error page without revalidation headers`() async throws {
+        // A `304 Not Modified` only ever stands in for a success, so the error page must not
+        // invite revalidation with an entity tag or a cache policy.
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.eTag] == nil)
+                #expect(response.headers[.cacheControl] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `serves the full error page to a conditional request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get,
+                headers: [.ifNoneMatch: "*"]
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(body.contains("Stub content"))
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension NotFoundMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose not-found middleware appends the given version token to the
+    /// error page's asset URLs.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
+    /// - Returns: the configured application.
+    func app(
+        assetVersion: String?
+    ) -> some ApplicationProtocol {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+            NotFoundMiddleware(bundle: .module) {
+                StubPage(
+                    locale: $0,
+                    assetVersion: assetVersion
+                )
+            }
+        }
+
+        return Application(router: router)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift

@@ -0,0 +1,170 @@
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite("RateLimitMiddleware middleware", .tags(.middleware))
+struct RateLimitMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `admits requests within the limit`() async throws {
+        try await app(
+            configuration: .init(limit: 3)
+        ).test(.router) { client in
+            for _ in 1 ... 3 {
+                try await client.execute(
+                    uri: "/hello",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                }
+            }
+        }
+    }
+
+    @Test
+    func `rejects a request over the limit with a retry-after header`() async throws {
+        try await app(
+            configuration: .init(limit: 2)
+        ).test(.router) { client in
+            for _ in 1 ... 2 {
+                try await client.execute(
+                    uri: "/hello",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                }
+            }
+
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+
+                let retryAfter = try #require(response.headers[.retryAfter])
+
+                #expect(try #require(Int(retryAfter)) >= 1)
+            }
+        }
+    }
+
+    @Test
+    func `admits requests again once the window resets`() async throws {
+        try await app(
+            configuration: .init(
+                limit: 1,
+                window: .milliseconds(50)
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+
+            try await Task.sleep(for: .milliseconds(100))
+
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+    @Test
+    func `separates clients by their forwarded address when trusted`() async throws {
+        try await app(
+            configuration: .init(
+                limit: 1,
+                trustForwardedFor: true
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.8"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            // The first entry names the client; the appended proxy hop must not change its key.
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7, 10.0.0.1"]
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+        }
+    }
+
+    @Test
+    func `ignores the forwarded address when not trusted`() async throws {
+        try await app(
+            configuration: .init(limit: 1)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            // Without trust (and without a connection address in router-only testing), every client
+            // shares one bucket, so a rotated header must not mint a fresh budget.
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.8"]
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RateLimitMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the rate-limit middleware ahead of a single
+    /// `/hello` route returning a plain body.
+    func app(
+        configuration: RateLimitMiddleware<BasicRequestContext>.Configuration
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            RateLimitMiddleware(configuration: configuration)
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        return Application(router: router)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift

@@ -0,0 +1,156 @@
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite("SecurityHeadersMiddleware middleware", .tags(.middleware))
+struct SecurityHeadersMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `applies the default security headers to a response`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentSecurityPolicy] == .Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == .Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == .Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == .Security.permissionsPolicy)
+            }
+        }
+    }
+
+    @Test
+    func `omits strict-transport-security by default`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.strictTransportSecurity] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `applies strict-transport-security when configured`() async throws {
+        let value = "max-age=31536000; includeSubDomains"
+
+        try await app(
+            configuration: .init(strictTransportSecurity: value)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.strictTransportSecurity] == value)
+            }
+        }
+    }
+
+    @Test
+    func `applies a custom header value`() async throws {
+        let value = "default-src 'none'"
+
+        try await app(
+            configuration: .init(contentSecurityPolicy: value)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.contentSecurityPolicy] == value)
+            }
+        }
+    }
+
+    @Test
+    func `omits a header whose configured value is nil`() async throws {
+        try await app(
+            configuration: .init(contentTypeOptions: nil)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.xContentTypeOptions] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `replaces an existing header value set downstream`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/weak",
+                method: .get
+            ) { response in
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+            }
+        }
+    }
+
+    @Test
+    func `applies the security headers to an error response`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/throws",
+                method: .get
+            ) { response in
+                #expect(response.status == .badRequest)
+                #expect(response.headers[.contentSecurityPolicy] == .Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == .Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == .Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == .Security.permissionsPolicy)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension SecurityHeadersMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the security-headers middleware ahead of three
+    /// routes: `/hello` returns a plain body, `/weak` returns a response that already carries a
+    /// deliberately weak `X-Content-Type-Options` value for the middleware to override, and
+    /// `/throws` fails with an `HTTPError` the way the controllers do on invalid input.
+    func app(
+        configuration: SecurityHeadersMiddleware<BasicRequestContext>.Configuration = .init()
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            SecurityHeadersMiddleware(configuration: configuration)
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get("weak") { _, _ -> Response in
+            var response = Response(status: .ok)
+
+            response.headers[.xContentTypeOptions] = "weak"
+
+            return response
+        }
+
+        router.get("throws") { _, _ -> Response in
+            throw HTTPError(.badRequest)
+        }
+
+        return Application(router: router)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift

@@ -0,0 +1,131 @@
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite("VaryMiddleware middleware", .tags(.middleware))
+struct VaryMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `adds the default field to a response without a vary header`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/plain",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.vary] == "Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `appends to an existing vary header`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/localized",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Language, Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `does not duplicate a name already present`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/encoded",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `matches an existing name regardless of its casing`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/lowercased",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "accept-encoding")
+            }
+        }
+    }
+
+    @Test
+    func `normalizes the whitespace of an existing list`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/spaced",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Language, User-Agent, Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `appends every configured field`() async throws {
+        try await app(
+            fields: [.acceptEncoding, .acceptLanguage]
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/plain",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Encoding, Accept-Language")
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension VaryMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the vary middleware ahead of routes whose
+    /// responses carry different `Vary` starting points: `/plain` none, `/localized` an
+    /// `Accept-Language`, `/encoded` an `Accept-Encoding` already, `/lowercased` a lowercase
+    /// `accept-encoding`, and `/spaced` a list with irregular whitespace.
+    func app(
+        fields: [HTTPField.Name] = [.acceptEncoding]
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            VaryMiddleware(fields: fields)
+        }
+
+        router.get("plain") { _, _ in
+            "Hello!"
+        }
+
+        for (path, vary) in [
+            ("localized", "Accept-Language"),
+            ("encoded", "Accept-Encoding"),
+            ("lowercased", "accept-encoding"),
+            ("spaced", "Accept-Language ,  User-Agent"),
+        ] {
+            router.get(RouterPath(path)) { _, _ -> Response in
+                var response = Response(status: .ok)
+
+                response.headers[.vary] = vary
+
+                return response
+            }
+        }
+
+        return Application(router: router)
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift

@@ -0,0 +1,79 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("Asset protocol")
+struct AssetTests {
+
+    // MARK: Properties
+
+    private let image = StubAsset(
+        fileExtensions: [.png],
+        fileName: "icon"
+    )
+    private let shared = StubAsset(
+        fileExtensions: [.css, .js],
+        fileName: "shared"
+    )
+
+    // MARK: Method tests
+
+    @Test
+    func `relative path nests the file inside its extension's sub-directory`() {
+        #expect(shared.relativePath(for: .css) == "css/shared.css")
+        #expect(shared.relativePath(for: .js) == "js/shared.js")
+    }
+
+    @Test
+    func `relative path keeps the file at the root without a sub-directory`() {
+        #expect(image.relativePath(for: .png) == "icon.png")
+    }
+
+    @Test
+    func `url path prefixes the relative path with a slash`() {
+        #expect(shared.urlPath(for: .css) == "/css/shared.css")
+        #expect(image.urlPath(for: .png) == "/icon.png")
+    }
+
+    @Test
+    func `url path appends a version token as a query parameter`() {
+        #expect(shared.urlPath(
+            for: .css,
+            version: "0123456789abcdef"
+        ) == "/css/shared.css?v=0123456789abcdef")
+    }
+
+    @Test(arguments: [nil, ""] as [String?])
+    func `url path without a version`(
+        version: String?
+    ) {
+        #expect(shared.urlPath(
+            for: .css,
+            version: version
+        ) == "/css/shared.css")
+    }
+
+    @Test(arguments: [
+        "",
+        ".",
+        "Resources/Static"
+    ])
+    func `path relative to`(
+        _ basePath: String
+    ) {
+        for fileExtension in shared.fileExtensions {
+            let pathRelativeToBasePath = shared.path(
+                relativeTo: basePath,
+                for: fileExtension
+            )
+            let relativePath = shared.relativePath(for: fileExtension)
+
+            if basePath.isEmpty {
+                #expect(pathRelativeToBasePath == relativePath)
+            } else {
+                #expect(pathRelativeToBasePath == "\(basePath)/\(relativePath)")
+            }
+        }
+    }
+
+}

Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift

@@ -0,0 +1,62 @@
+import Elementary
+import Foundation
+import Testing
+
+@testable import Infrastructure
+
+@Suite("Page protocol", .tags(.page))
+struct PageTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `assembles the document around the page's parts`() {
+        let html = StubPage().render()
+
+        #expect(html.contains("<title>Stub Page</title>"))
+        #expect(html.contains(#"lang="en""#))
+        #expect(html.contains(#"name="viewport""#))
+        #expect(html.contains(#"<meta name="stub" content="marker">"#))
+        #expect(html.contains(#"<link rel="stylesheet" href="/css/stub.css">"#))
+        #expect(html.contains(#"<script src="/js/stub.js"></script>"#))
+        #expect(html.contains("Stub content"))
+    }
+
+    @Test
+    func `places the metadata between the viewport and the stylesheets`() throws {
+        let html = StubPage().render()
+
+        let viewport = try #require(html.range(of: #"name="viewport""#))
+        let metadata = try #require(html.range(of: #"name="stub""#))
+        let stylesheet = try #require(html.range(of: "/css/stub.css"))
+
+        #expect(viewport.lowerBound < metadata.lowerBound)
+        #expect(metadata.lowerBound < stylesheet.lowerBound)
+    }
+
+    @Test
+    func `renders the scripts after the content`() throws {
+        let html = StubPage().render()
+
+        let content = try #require(html.range(of: "Stub content"))
+        let script = try #require(html.range(of: "/js/stub.js"))
+
+        #expect(content.lowerBound < script.lowerBound)
+    }
+
+    @Test
+    func `appends the version token to the asset URLs`() {
+        let html = StubPage(assetVersion: "0123456789abcdef").render()
+
+        #expect(html.contains("/css/stub.css?v=0123456789abcdef"))
+        #expect(html.contains("/js/stub.js?v=0123456789abcdef"))
+    }
+
+    @Test
+    func `derives the document language from the locale`() {
+        let html = StubPage(locale: .init(identifier: "de-DE")).render()
+
+        #expect(html.contains(#"lang="de""#))
+    }
+
+}

Packages/Infrastructure/Tests/Catalogs/Localizable.xcstrings

@@ -0,0 +1,23 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "test.greeting" : {
+      "comment" : "Fixture string used by the Infrastructure test suite.",
+      "localizations" : {
+        "de" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hallo"
+          }
+        },
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hello"
+          }
+        }
+      }
+    }
+  },
+  "version" : "1.0"
+}

Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift

@@ -0,0 +1,11 @@
+import Infrastructure
+
+/// An ``Asset`` with a fixed file name and set of extensions.
+struct StubAsset: Asset {
+
+    // MARK: Properties
+
+    let fileExtensions: [AssetExtension]
+    let fileName: String
+
+}

Packages/Infrastructure/Tests/Utils/Contexts/StubRequestContext.swift

@@ -0,0 +1,26 @@
+import Hummingbird
+import Infrastructure
+
+/// A ``LocalizedRequestContext`` carrying the core storage and the negotiated language only.
+struct StubRequestContext: LocalizedRequestContext {
+
+    // MARK: Properties
+
+    /// The core request context storage Hummingbird requires.
+    var coreContext: CoreRequestContextStorage
+
+    /// The language identifier negotiated for the request.
+    var language: String
+
+    // MARK: Initializers
+
+    /// Creates a request context for the given source.
+    /// - Parameter source: the source the context is initialized from.
+    init(
+        source: Source
+    ) {
+        self.coreContext = .init(source: source)
+        self.language = ""
+    }
+
+}

Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift

@@ -0,0 +1,8 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising a middleware of the Infrastructure package.
+    @Tag static var middleware: Tag
+    /// Tests exercising the page scaffolding of the Infrastructure package.
+    @Tag static var page: Tag
+}

Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift

@@ -0,0 +1,66 @@
+import Elementary
+import Foundation
+import Infrastructure
+
+/// A ``Page`` with fixed content, metadata, and stub assets.
+struct StubPage: Page {
+
+    // MARK: Properties
+
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    let assetVersion: String?
+
+    /// The locale the page content is localized to.
+    let locale: Locale
+
+    // MARK: Initializers
+
+    /// Creates a stub page.
+    /// - Parameters:
+    ///   - locale: the locale the page content is localized to. Defaults to `en`.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
+    ///     default) to leave them unversioned.
+    init(
+        locale: Locale = .init(identifier: "en"),
+        assetVersion: String? = nil
+    ) {
+        self.assetVersion = assetVersion
+        self.locale = locale
+    }
+
+    // MARK: Computed
+
+    var content: some HTML {
+        p { "Stub content" }
+    }
+
+    var lang: String {
+        locale.language.languageCode?.identifier ?? "en"
+    }
+
+    var metadata: some HTML {
+        meta(
+            .name("stub"),
+            .content("marker")
+        )
+    }
+
+    var scripts: [any Asset] {
+        [StubAsset(
+            fileExtensions: [.css, .js],
+            fileName: "stub"
+        )]
+    }
+
+    var stylesheets: [any Asset] {
+        [StubAsset(
+            fileExtensions: [.css, .js],
+            fileName: "stub"
+        )]
+    }
+
+    var title: String {
+        "Stub Page"
+    }
+
+}