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:
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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")!
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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=()"
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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)"
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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 }
|
||||
|
||||
}
|
||||
@@ -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
|
||||
))
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
)
|
||||
}
|
||||
|
||||
}
|
||||
+76
@@ -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
|
||||
)
|
||||
}
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user