ccn/Packages/Infrastructure/README.md

Infrastructure

The shared Hummingbird toolkit the platform's services build on: declarative routing, hardened HTTP middlewares, pre-rendered and pre-compressed localized responses, and page and asset scaffolding.

Overview

Role	Types
Routing	RouterController, RouteCollectionBuilder, the addController extension on RouterMethods
Middlewares	SecurityHeadersMiddleware, HTTPSRedirectMiddleware, TrailingSlashRedirectMiddleware, VaryMiddleware, CompressionMiddleware, RateLimitMiddleware, NotFoundMiddleware
Pages and assets	Page, Asset, AssetExtension, FingerprintAssets
Link previews	SocialCard, its locale and the alternateLocales of its other language editions, its Image and Style, and the Tag meta tags it derives
Structured data	Opt-in StructuredData trait: StructuredData, its graph types (Node, Property, Value, Address, Organization), the open Name and Kind vocabularies, and the site-wide Organization/WebSite initializer
Analytics	Opt-in Analytics trait: Analytics, the Events a page reports (with reporting(_:on:) to tag an element, for a click or a view), the tracker script Attributes it derives, the optional session recorder script paired with it, and the origin its preconnect hint targets
Responses	CachedHTMLResponse (rendered and gzipped once), LocalizedHTMLCollectionResponse (one of those per language)
Localization	The Negotiate extension resolving a request's language from its lang override, path prefix, and Accept-Language
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. 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 deferred head tags, the tracker preceded by a preconnect to its cross-origin host.
• Nodes are joined by @id, not repetition. Identifiers come from helpers, never hand-spelled: organizationID(forSiteURL:) and websiteID(forSiteURL:) name the site-wide nodes, and Organization.founder takes one back. A service adds a helper for each node it owns.
• 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.
• Method structs. Single-operation types such as FingerprintAssets take lifetime-fixed configuration in init and per-call inputs in callAsFunction.
• Wrap upstream, do not restate it. Where a Hummingbird middleware is almost right, the package delegates to it and adds only the missing decision — CompressionMiddleware passes everything to ResponseCompressionMiddleware except responses that already name an encoding, which it would otherwise compress twice.
• Ask where the answer is used. Work every request pays for must be work every request needs. The request's language is negotiated by the responders that read it, not stamped onto a context on the way past.

Layout

Sources are split by visibility, then by kind, one type per file:

Sources/
├── Public/                public API
│   ├── Builders/          RouteCollectionBuilder
│   ├── Enumerations/      AssetExtension
│   ├── Extensions/        addController, Analytics.Event tagging and reporting, and the request-language negotiation, plus the default header names, rate limits, and header values
│   ├── Methods/           FingerprintAssets
│   ├── Middlewares/       the seven HTTP middlewares
│   ├── Protocols/         Asset, Page, RouterController
│   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
│   └── Types/             Analytics, SocialCard, StructuredData — each nesting its own types in a folder of that name
└── Internal/
    ├── Extensions/        implementation details (the String separators)
    └── Types/             implementation details (FNV1aHash)
Tests/
├── Cases/                 the test suites, mirroring the Sources/ layout
├── Catalogs/              the String Catalog fixture, copied verbatim so it loads on Linux
└── Utils/                 stubs (StubAsset, StubPage, …) and the suite Tag constants

Testing

Every suite carries a tag for the kind of API it exercises — .asset, .extension, .middleware, .protocol, .type — declared in Tests/Utils/Extensions/Tag+Constants.swift, so a run can be sliced by kind. A new suite takes the tag matching its subject, or adds one when none fits.

Run swift test --traits Analytics,StructuredData to include the trait-gated suites.

Requirements

• Swift 6.4 toolchain (swift-tools-version:6.4).
• macOS 15, matching the sibling packages. The services deploy to Linux containers; the packages declare no UI platforms.
• Package dependencies: the local Localization package, elementary, hummingbird, and — for CompressionMiddleware and the responses' gzip — hummingbird-compression and compress-nio.