From 0b3ef2890ecabc89bf81f7a53198a2c027724070 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Mon, 31 Aug 2026 21:56:09 +0200 Subject: [PATCH] Updated the Localized HTML Collection response in the Infrastructure package to make `Vary: Accept-Language` opt-in for localized responses. --- Packages/Infrastructure/README.md | 4 ++-- .../Middlewares/LocalizationMiddleware.swift | 8 ++++--- .../Middlewares/NotFoundMiddleware.swift | 4 ++++ .../LocalizedHTMLCollectionResponse.swift | 22 ++++++++++++++----- 4 files changed, 27 insertions(+), 11 deletions(-) diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md index 8fd2d8d..1fd1a04 100644 --- a/Packages/Infrastructure/README.md +++ b/Packages/Infrastructure/README.md @@ -10,13 +10,13 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too | Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives | | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair | | Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets | -| Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` | +| Responses | `CachedHTMLResponse`, and `LocalizedHTMLCollectionResponse` rendering one of them per catalog language | | Contexts | `LocalizedRequestContext` | | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to | ## 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. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page. +- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page. The same holds for request semantics: only the caller knows whether it negotiates the language or pins it by route, so `variesOnAcceptLanguage:` declares whether the responses carry `Vary: Accept-Language`. - **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready form — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — which `Page` applies without knowing the vocabulary. A page's `scripts` and the tracker render as `defer`red head tags, the tracker preceded by a `preconnect` to its cross-origin host. - **Nodes are joined by `@id`, not repetition.** A node another page must point at gets its identifier from a helper rather than a hand-spelled fragment — `organizationID(forSiteURL:)` names the node the site-wide initializer builds, and that initializer's `founder` takes such an identifier back. A service adds the helper for any node it owns, so neither side can drift. - **Services fill the gaps once, via extensions.** A service restores its convenient call sites retroactively — the Website's `*+Defaults` are the pattern. The open schema.org vocabularies work the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, a service adds its own. diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift index c7adec7..f8bb021 100644 --- a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift +++ b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift @@ -9,9 +9,11 @@ import Localization /// `Accept-Language` header, negotiates the best supported match (falling back to the default language), and stores it on the context's /// ``LocalizedRequestContext/language``. /// -/// The query parameter is the deliberate override a language switcher links to; failing that, a leading path segment naming a supported language -/// pins it, so an unrouted path under a language's prefix — its not-found page — answers in that language. Values naming no supported language -/// are ignored, leaving the header. The request is passed through untouched — the path and routing are unaffected. +/// The query parameter is a deliberate override; failing that, a leading path segment naming a supported language pins it, so an unrouted path under +/// a language's prefix — its not-found page — answers in that language. Values naming no supported language are ignored, leaving the header. The +/// request is passed through untouched — the path and routing are unaffected. +/// +/// A site whose page routes pin their language by URL consults this only for responses that belong to no URL — in practice, its not-found page. public struct LocalizationMiddleware { // MARK: Properties diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift index b5f51e6..e1ba556 100644 --- a/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift +++ b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift @@ -7,6 +7,9 @@ import Hummingbird /// 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. +/// +/// Its responses declare `Vary: Accept-Language`: where the page routes pin their language by URL, this is the one responder that negotiates. +/// An unrouted path names no edition, so no canonical URL contradicts the header. public struct NotFoundMiddleware { // MARK: Properties @@ -27,6 +30,7 @@ public struct NotFoundMiddleware { self.responses = .init( bundle: bundle, status: .notFound, + variesOnAcceptLanguage: true, document: document ) } diff --git a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift index b497105..9a635c8 100644 --- a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift +++ b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift @@ -7,8 +7,12 @@ 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. +/// ``CachedHTMLResponse``'s render-once model but keyed by language. Each cached response carries a `Content-Language` header naming the +/// language it was rendered in. +/// +/// `Vary: Accept-Language` is the caller's to declare, since only the caller knows how it picks the language: a responder that negotiates the +/// header sets it, so shared caches key on the language rather than serving one to everyone; a responder that pins the language by route does +/// not, since the header would announce a negotiation that never happens. public struct LocalizedHTMLCollectionResponse: Sendable { // MARK: Properties @@ -25,21 +29,27 @@ public struct LocalizedHTMLCollectionResponse: Sendable { /// - 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`. + /// - variesOnAcceptLanguage: whether the responses declare `Vary: Accept-Language`. Defaults to `false`; a responder that + /// negotiates the header passes `true`. /// - document: builds the document to render for a given locale. public init( bundle: Bundle, status: HTTPResponse.Status = .ok, + variesOnAcceptLanguage: Bool = false, document: (Locale) -> Document ) { self.list = .init(bundle: bundle) self.responses = list.all .reduce(into: [:]) { responses, language in + var headers: HTTPFields = [.contentLanguage: language] + + if variesOnAcceptLanguage { + headers[.vary] = "Accept-Language" + } + responses[language] = CachedHTMLResponse( status: status, - additionalHeaders: [ - .contentLanguage: language, - .vary: "Accept-Language", - ], + additionalHeaders: headers, document: document(.init( identifier: language ))