rock-n-code/ccn
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

Initial commit.

Browse Source
This commit is contained in:
javier
2026-08-19 23:19:08 +02:00
commit 22e737d9c2
153 changed files with 11680 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
+87
View File
@@ -0,0 +1,87 @@
/// 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. Each file lands in its extension's own
/// folder unless the asset names a ``folder`` of its own.
public protocol Asset: Sendable {
// MARK: Properties
/// The folder within the static files root that holds the asset's files, or `nil` (the default) to use each extension's own folder.
var folder: String? { get }
/// 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: Computed
/// The asset's files live in each extension's own folder by default.
var folder: String? { nil }
// 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 (folder ?? fileExtension.folder)
.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)"
}
}
Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
+14
View File
@@ -0,0 +1,14 @@
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 }
}
Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+207
View File
@@ -0,0 +1,207 @@
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, the summary, canonical, and social card tags, the structured data script, the analytics
/// tracker script, and the metadata followed by the stylesheet links and the deferred script tags in the head, and the content as 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 analytics tracker embedded as a deferred script in the document head, or `nil` (the default) to omit it.
var analytics: Analytics? { get }
/// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
var assetVersion: String? { get }
/// The canonical URL the page is served at, rendered as a `link rel="canonical"` tag in the document head, or `nil` (the default) to omit the tag.
var canonicalURL: String? { get }
/// The page's markup, rendered as the document body.
@HTMLBuilder
var content: Content { get }
/// The locale the page content is localized to.
var locale: Locale { get }
/// The markup placed in the document head before the ``stylesheets`` links: icon and manifest links, extra meta tags, and the like.
@HTMLBuilder
var metadata: Metadata { get }
/// The scripts loaded from the document head, in order.
///
/// Rendered as `defer`red tags: the downloads start while the head is parsed, and the scripts still execute in order only after the
/// document is fully parsed — the same semantics end-of-body tags would give, minus the late download start.
var scripts: [any Asset] { get }
/// The card controlling the page's link previews, rendered as Open Graph and Twitter meta tags in the document head, or `nil` (the default)
/// to omit them.
var socialCard: SocialCard? { get }
/// The page's structured data, rendered as a JSON-LD script in the document head, or `nil` (the default) to omit it.
var structuredData: StructuredData? { get }
/// The stylesheets linked in the document head, in order.
var stylesheets: [any Asset] { get }
/// The page's summary, rendered as a `meta name="description"` tag in the document head, or `nil` (the default) to omit the tag.
var summary: String? { get }
}
// MARK: - Implementations
public extension Page {
// MARK: Computed
/// The canonical URL is omitted unless the page provides one.
var canonicalURL: String? {
nil
}
/// The page ``content``; the ``scripts`` load deferred from the ``head``.
@HTMLBuilder
var body: some HTML {
content
}
/// The viewport declaration, the ``analytics`` origin preconnect hint, the ``summary``, ``canonicalURL``, and ``socialCard``
/// tags, the ``structuredData`` script and the ``analytics`` tracker script (when provided), and the ``metadata`` followed by the
/// ``stylesheets`` links and the deferred ``scripts`` tags, 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.
///
/// The structured data is an inert data block — browsers never execute it, so a site's `Content-Security-Policy` does not apply to it —
/// that search engines read for the organization's name, logo, and profiles. The analytics tracker, by contrast, is an executable script the
/// policy must allow, and it is `defer`red so it never delays the page render; each behavior flag renders its `data-` attribute only when enabled.
/// When recorder mode is on, the session recorder script follows the tracker script, deferred as well and carrying only the website id.
@HTMLBuilder
var head: some HTML {
meta(
.name(.viewport),
.content("width=device-width, initial-scale=1")
)
// Rendered first so the cross-origin handshake starts before the parser reaches the tracker script tag.
if let origin = analytics?.origin {
link(
.rel("preconnect"),
.href(origin)
)
}
if let summary {
meta(
.name(.description),
.content(summary)
)
}
if let canonicalURL {
link(
.rel("canonical"),
.href(canonicalURL)
)
}
if let socialCard {
for tag in socialCard.tags {
meta(
.custom(
name: tag.attribute.rawValue,
value: tag.name.rawValue
),
.content(tag.content)
)
}
}
if let structuredData {
script(.custom(
name: "type",
value: "application/ld+json"
)) {
HTMLRaw(structuredData.payload)
}
}
if let analytics {
script(
.defer,
.src(analytics.scriptURL)
) {}
.attributes(contentsOf: analytics.attributes.map {
.custom(
name: $0.name,
value: $0.value
)
})
if let recorderScriptURL = analytics.recorderScriptURL {
script(
.defer,
.src(recorderScriptURL),
.custom(
name: "data-website-id",
value: analytics.websiteID
)
) {}
}
}
metadata
for file in stylesheets {
link(
.rel(.stylesheet),
.href(file.urlPath(
for: .css,
version: assetVersion
))
)
}
for file in scripts {
script(
.defer,
.src(file.urlPath(
for: .js,
version: assetVersion
))
) {}
}
}
/// The analytics tracker is omitted unless the page provides one.
var analytics: Analytics? {
nil
}
/// The social card is omitted unless the page provides one.
var socialCard: SocialCard? {
nil
}
/// The structured data is omitted unless the page provides one.
var structuredData: StructuredData? {
nil
}
/// The summary is omitted unless the page provides one.
var summary: String? {
nil
}
}
Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
+32
View File
@@ -0,0 +1,32 @@
import Hummingbird
/// A type exposing its endpoints as a route collection ready to be added to a router.
///
/// Conforming controllers group related endpoints behind a single ``routes`` property, so the application composes them declaratively with
/// ``Hummingbird/RouterMethods/addController(_:)``:
///
/// ```swift
/// struct HealthController<Context: RequestContext>: RouterController {
/// var routes: RouteCollection<Context> {
/// RouteCollection(context: Context.self)
/// .get("health") { _, _ in HTTPResponse.Status.ok }
/// }
/// }
///
/// router.addController {
/// HealthController<AppRequestContext>()
/// }
/// ```
public protocol RouterController<Context>: Sendable {
// MARK: Associated types
/// The request context the controller's routes operate on.
associatedtype Context: RequestContext
// MARK: Properties
/// The collection of routes the controller exposes.
var routes: RouteCollection<Context> { get }
}