rock-n-code/hummingbird-docc
1
0
Fork 0
Code Issues Pull Requests Releases 3 Activity

Updated the names of the targets in the Package file to "HummingbirdDocC".

Browse Source
This commit is contained in:
Javier Cicchelli
2025-09-28 23:09:02 +02:00
parent 90c4033a49
commit efedff51d1
40 changed files with 99 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/HummingbirdDocC/Internal/Enumerations/AssetFile.swift
+38
View File
@@ -0,0 +1,38 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
/// An enumeration that represents the essential static files that could be generated by the `DocC` building process.
enum AssetFile: String, CaseIterable {
/// A file defining all the documentation available, which will be used to redirect to the root of the documentation's root article.
case documentation = "documentation.json"
/// A file containing the icon in `.ico` format within the documentation generated by the `DocC` building process.
case faviconICO = "favicon.ico"
/// A file containing the icon in `.svg` format within the documentation generated by the `DocC` building process.
case faviconSVG = "favicon.svg"
/// A file containing the theme settings within the documentation generated by the `DocC` building process.
case themeSettings = "theme-settings.json"
}
// MARK: - Pathable
extension AssetFile: Pathable {
// MARK: Computed
var path: String {
switch self {
case .documentation: .init(format: .Format.Path.data, rawValue)
default: .init(format: .Format.Path.root, rawValue)
}
}
}
Sources/HummingbirdDocC/Internal/Enumerations/AssetFolder.swift
+43
View File
@@ -0,0 +1,43 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
/// An enumeration that represents all possible asset folders that could be generated by the `DocC` building process.
enum AssetFolder: String, CaseIterable {
/// A folder that contains all CSS style sheets.
case css
/// A folder that contains all documentation data.
case data
/// A folder that contains all other resources.
case downloads
/// A folder that contains all image resources.
case images
/// A folder that contains all image resources.
case img
/// A folder that contains all generated `HTML` code.
case index
/// A folder that contains all generated `Javascript` code.
case js
/// A folder that contains all video resources.
case videos
}
// MARK: - Pathable
extension AssetFolder: Pathable {
// MARK: Computed
var path: String {
.init(format: .Format.Path.folder, rawValue)
}
}
Sources/HummingbirdDocC/Internal/Enumerations/DocumentationFolder.swift
+31
View File
@@ -0,0 +1,31 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
/// An enumeration that represents the documentation folders that could be generated by the `DocC` building process.
enum DocumentationFolder: String, CaseIterable {
/// An article document, which can also be used for (source code generated) technical documentation as well.
case article = "documentation"
/// A tutorial document.
case tutorial = "tutorials"
}
// MARK: - Pathable
extension DocumentationFolder: Pathable {
// MARK: Computed
var path: String {
.init(format: .Format.Path.root, rawValue)
}
}
Sources/HummingbirdDocC/Internal/Extensions/LoggerMetadata+Helpers.swift
+50
View File
@@ -0,0 +1,50 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import protocol Hummingbird.RequestContext
import struct Hummingbird.HTTPResponse
import struct Hummingbird.Request
import struct Logging.Logger
extension Logger.Metadata {
// MARK: Functions
/// Generates a dictionary to use as metadata for events to log into the logging system.
/// - Parameters:
/// - context: A type that contains all the parameters associated with a given request, and that conforms to the `RequestContext` protocol.
/// - request: A type that contains all the parameters to process as a request.
/// - statusCode: A representation of a response status to provide as a response.
/// - redirect: A URI path to use in a redirection event, if any.
/// - Returns: A generated metadata dictionary for an event to log into the logging system.
static func metadata(
context: any RequestContext,
request: Request,
statusCode: HTTPResponse.Status,
redirect: String? = nil
) -> Self {
var metadata: Logger.Metadata = [
"hb.request.id": "\(context.id)",
"hb.request.method": "\(request.method.rawValue)",
"hb.request.path": "\(request.uri.path)",
"hb.request.status": "\(statusCode.code)"
]
if let redirect {
metadata["hb.request.redirect"] = "\(redirect)"
}
return metadata
}
}
Sources/HummingbirdDocC/Internal/Extensions/String+Constants.swift
+30
View File
@@ -0,0 +1,30 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
extension String {
/// An empty string.
static let empty = ""
/// A namespace that defines logging values.
enum Logging {
/// A name of the middleware that triggered a logging event.
static let source = "DocCMiddleware"
}
/// A namespace that defines relative path values.
enum Path {
/// A forwarding slash.
static let forwardSlash = "/"
/// An indication of a previous folder in a path component.
static let previousFolder = ".."
}
}
Sources/HummingbirdDocC/Internal/Extensions/String+Formats.swift
+38
View File
@@ -0,0 +1,38 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
extension String {
/// A namespace that defines the format patterns used to generate strings.
enum Format {
/// A namespace that defines the format patterns used to generate relative path representations.
enum Path {
/// A format pattern used to generate relative paths that starts with the `/` string and finishes with the `.doccarchive` string.
static let archive = "/%@.doccarchive"
/// A format pattern used to generate relative paths that starts with the `/data` string.
static let data = "/data/%@"
/// A format pattern used to generate relative paths that starts with the `/docs` string.
static let docs = "/docs/%@"
/// A format pattern used to generate relative paths that finishes with the `/documentation` string.
static let documentation = "%@documentation"
/// A format pattern used to generate relative paths for JSON documentation files.
static let documentationJSON = "/data/documentation/%@.json"
/// A format pattern used to generate relative paths that starts and finishes with the `/` string.
static let folder = "/%@/"
///A format pattern used to generate relative paths that finishes with the `/` string.
static let forwardSlash = "%@/"
/// A format pattern used to generate relative paths for index files.
static let index = "%@/%@/index.html"
/// A format pattern used to generate relative paths that starts with the `/` string.
static let root = "/%@"
}
}
}
Sources/HummingbirdDocC/Internal/Protocols/Pathable.swift
+21
View File
@@ -0,0 +1,21 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
/// A protocol that provides a relative path representation.
protocol Pathable {
// MARK: Properties
/// A (relative) path to a resource.
var path: String { get }
}
Sources/HummingbirdDocC/Internal/Pseudo Types/ContextualInfo.swift
+18
View File
@@ -0,0 +1,18 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import protocol Hummingbird.RequestContext
import struct Hummingbird.Request
/// A pseudo-type that contains data about a request and its related context.
typealias ContextualInfo = (request: Request, context: any RequestContext)
Sources/HummingbirdDocC/Internal/Use Cases/CheckURIUseCase.swift
+35
View File
@@ -0,0 +1,35 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import struct HummingbirdCore.URI
/// A use case that checks whether a given URI against a set of conditions, to determine whether the URI could be used by the middleware or not.
struct CheckURIUseCase {
// MARK: Functions
/// Checks whether a provided URI against a set of conditions, so it could be used by the middleware.
/// - Parameter uri: A URI to check.
/// - Returns: A non-encoded URI, which is ready to be used by the middleware.
func callAsFunction(_ uri: URI) -> String? {
guard
let uriPath = uri.path.removingPercentEncoding,
!uriPath.contains(.Path.previousFolder),
uriPath.hasPrefix(.Path.forwardSlash)
else {
return nil
}
return uriPath
}
}
Sources/HummingbirdDocC/Internal/Use Cases/PrepareURIPathUseCase.swift
+127
View File
@@ -0,0 +1,127 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import Foundation
import RegexBuilder
/// A use case that extracts data from a given URI path, essential for routing the documentation contents.
struct PrepareURIPathUseCase {
// MARK: Type aliases
/// A pseudo-type that contains the archive name, reference and URI path, plus the resource URI and relative paths used for routing the documentation contents.
typealias PreparedURIPaths = (archiveName: String, archiveReference: String, archivePath: String, resourcePath: String)
// MARK: Properties
/// A root path that suffixes the documentation resource.
private let uriRoot: String
// MARK: Initializers
/// Initializes this use case.
///
/// > important: It is assumed that the `uriRoot` parameter is not empty and that it is prefixed by the `/` character.
///
/// - Parameter uriRoot: A root path that prefixes the documentation resource.
init(uriRoot: String) {
self.uriRoot = uriRoot
}
// MARK: Functions
/// Extracts some necessary data essential for documentation contents routing from a given URI path.
///
/// The necessary data to extract from a given URI path is:
/// 1. the `DocC` documentation archive name;
/// 2. the `DocC` documentation archive reference;
/// 3. the `DocC` documentation archive URI path;
/// 4. the `DocC` documentation resource URI path.
///
/// > important: It is assumed that the `uriPath` parameter is a URI path that does not contain any percent encoded strings.
///
/// - Parameter uriPath: A URI path to extract the data from.
/// - Returns: A pseudo-type that contains the archive' name, reference and URI path, plus the resource URI paths.
func callAsFunction(_ uriPath: String) -> PreparedURIPaths? {
guard let uriRest = restOfURIPath(from: uriPath) else {
return nil
}
let archiveName = uriRest
.split(separator: .Path.forwardSlash)
.map(String.init)
.first
let archiveReference: String = if let archiveName {
archiveName.lowercased()
} else {
.empty
}
let archivePath: String = if let archiveName {
.init(format: .Format.Path.archive, archiveName)
} else {
.empty
}
return (
archiveName ?? .empty,
archiveReference,
archivePath,
uriRest
)
}
}
// MARK: - Helpers
private extension PrepareURIPathUseCase {
// MARK: Functions
/// Extracts the rest of the URI path from a given URI path against a defined URI root path.
///
/// A given URI path is matched against a regular expression, which is generated from a provided URI root path.
/// So this function would return either a string that represents a partial URI path, or a `nil` instance depending the result of the match between
/// the URI path and the regular expression:
/// * A `nil` instance in case there is no match;
/// * A `/` string in case there is a perfect match;
/// * A partial URI path prefixed with the `/` character in case there is an offset in the match.
///
/// - Parameter uriPath: A URI path to get the rest of the URI path from.
/// - Returns: A rest of the URI path prefixed by the `/`character in case where there is any offset path after extracting the root path from the given URI path or not. Otherwise, a `nil` value is returned.
func restOfURIPath(from uriPath: String) -> String? {
let restReference = Reference(String.self)
let uriPattern = Regex {
uriRoot
Optionally {
Capture(as: restReference) {
OneOrMore(.anyNonNewline)
} transform: { output in
String(output)
}
}
}
guard let matches = uriPath.prefixMatch(of: uriPattern) else {
return nil
}
guard let uriRest = matches.output.1 else {
return .Path.forwardSlash
}
guard uriRest.hasPrefix(.Path.forwardSlash) else {
return .init(format: .Format.Path.root, uriRest)
}
return uriRest
}
}
Sources/HummingbirdDocC/Internal/Use Cases/RedirectURIUseCase.swift
+63
View File
@@ -0,0 +1,63 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import struct Hummingbird.Response
import struct Logging.Logger
/// A use case that produces a redirect response based on a given URI path.
struct RedirectURIUseCase {
// MARK: Properties
/// A type that interacts with the logging system.
private let logger: Logger
// MARK: Initializers
/// Initializes this use case.
/// - Parameter logger: A type that interacts with the logging system.
init(logger: Logger) {
self.logger = logger
}
// MARK: Functions
/// Produces a redirect response based on a given URI path
/// - Parameters:
/// - uriPath: A URI path to use in the redirection.
/// - contextualInfo: A pseudo-type that contains data about a request and its related context.
/// - Returns: A redirection response created out of a given URI path plus contextual information.
func callAsFunction(
_ uriPath: String,
with contextualInfo: ContextualInfo
) -> Response {
defer {
logger.log(
level: .debug,
"The URI path is redirected to this path: \(uriPath)",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .movedPermanently,
redirect: uriPath
),
source: .Logging.source
)
}
return .redirect(
to: uriPath,
type: .permanent
)
}
}
Sources/HummingbirdDocC/Internal/Use Cases/ServeURIUseCase.swift
+100
View File
@@ -0,0 +1,100 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import protocol Hummingbird.FileProvider
import struct Hummingbird.Response
import struct Logging.Logger
/// A use case that serves a resource, defined by its URI path, from a physical location.
struct ServeURIUseCase<Provider: FileProvider> {
// MARK: Properties
/// A type that conforms to a protocol that defines file system interactions.
private let fileProvider: Provider
/// A type that interacts with the logging system.
private let logger: Logger
// MARK: Initializers
/// Initializes this use case.
/// - Parameters:
/// - fileProvider: A type that conforms to a protocol that defines file system interactions.
/// - logger: A type that interacts with the logging system.
init(
fileProvider: Provider,
logger: Logger
) {
self.fileProvider = fileProvider
self.logger = logger
}
// MARK: Functions
/// Serves a certain resource based on a given URI path from a physical location.
/// - Parameters:
/// - uriPath: A URI path that represents a resource to be served.
/// - folderPath: A URI path to a physical folder that contains the resource.
/// - contextualInfo: A pseudo-type that contains data about a request and its related context.
/// - Returns: A response that either contains the data of the resource in its body in case the resource is found, or a not found otherwise.
/// - Throws: An error in case an issue is encountered while serving the resource.
func callAsFunction(
_ uriPath: String,
at folderPath: String,
with contextualInfo: ContextualInfo
) async throws -> Response {
let filePath = folderPath + uriPath
guard let fileIdentifier = fileProvider.getFileIdentifier(filePath) else {
defer {
logger.log(
level: .error,
"The resource \(filePath) has not been found.",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .notFound
),
source: .Logging.source
)
}
return .init(status: .notFound)
}
let body = try await fileProvider.loadFile(
id: fileIdentifier,
context: contextualInfo.context
)
defer {
logger.log(
level: .debug,
"The body of the resource \(filePath) has \(body.contentLength ?? 0) bytes.",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .ok
),
source: .Logging.source
)
}
return .init(
status: .ok,
body: body
)
}
}