Updated the Localized HTML Collection response in the Infrastructure package to make Vary: Accept-Language opt-in for localized responses.

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.

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<Context: LocalizedRequestContext> {
 
     // MARK: Properties

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<Context: LocalizedRequestContext> {
 
     // MARK: Properties
@@ -27,6 +30,7 @@ public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
         self.responses = .init(
             bundle: bundle,
             status: .notFound,
+            variesOnAcceptLanguage: true,
             document: document
         )
     }

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<Document: HTMLDocument>(
         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
                     ))