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>
2026-07-23 01:04:37 +00:00
parent a868275347
commit cdded06ba3
58 changed files with 2844 additions and 519 deletions
@@ -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
+                ))
+            )
+        }
+    }
+
+}