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