Added (first version of) sample Hummingbird app. (#4)

This PR contains the work done to:
* Implemented a basic `Hummingbird` application in which to integrate the `HummingbirdDocC` library.
* Added the *ArgumentParser* package dependency to the `Package.swift` file;
* Added a new *sample* target to the `Package.swift` file;
* Added library and documentation tasks to the `Makefile` file.

Reviewed-on: #4
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Sources/HummingbirdDocC/Catalogs/HummingbirdDocC.docc/Library.md

@@ -0,0 +1,13 @@
+# ``HummingbirdDocC``
+
+<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
+
+## Overview
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+
+## Topics
+
+### <!--@START_MENU_TOKEN@-->Group<!--@END_MENU_TOKEN@-->
+
+- <!--@START_MENU_TOKEN@-->``Symbol``<!--@END_MENU_TOKEN@-->

Sources/HummingbirdDocC/Internal/Enumerations/AssetFile.swift

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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/Extensions/String+Helpers.swift

@@ -0,0 +1,46 @@
+// ===----------------------------------------------------------------------===
+//
+// 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 RegexBuilder
+
+extension String {
+    
+    /// Subtracts a prefix from a string.
+    /// - Parameters:
+    ///   - prefix: A prefix to remove from a string.
+    /// - Returns: A new string with a prefix removed, if any.
+    func subtract(
+        _ prefix: String
+    ) -> String? {
+        let reference = Reference(String.self)
+        let pattern = Regex {
+            prefix
+            Optionally {
+                Capture(as: reference) {
+                    OneOrMore(.anyNonNewline)
+                } transform: { output in
+                    String(output)
+                }
+            }
+        }
+        
+        guard let matches = self.prefixMatch(of: pattern) else {
+            return nil
+        }
+        guard let subtracted = matches.output.1 else {
+            return .empty
+        }
+
+        return subtracted
+    }
+    
+}

Sources/HummingbirdDocC/Internal/Models/Resource.swift

@@ -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
+//
+// ===----------------------------------------------------------------------===
+
+/// A model that encapsulates the information related to a resource in a given `DocC` documentation archive.
+struct Resource: Equatable {
+    
+    // MARK: Properties
+    
+    /// An archive name in which the resource belongs to.
+    let archiveName: String
+    
+    /// A relative URI path to the resource.
+    let relativePath: String
+    
+    // MARK: Initializers
+    
+    /// Initializes this resource.
+    /// - Parameters:
+    ///   - archiveName: An archive name in which the resource belongs to.
+    ///   - relativePath: A relative URI path to the resource.
+    init(
+        archiveName: String,
+        relativePath: String
+    ) {
+        self.archiveName = archiveName
+        self.relativePath = relativePath
+    }
+    
+    // MARK: Computed
+    
+    /// A relative URI path to a documentation archive the resource belongs to.
+    var archivePath: String {
+        .init(format: .Format.Path.archive, archiveName)
+    }
+    
+    /// A reference name for the documentation archive the resource belongs to.
+    var archiveReference: String {
+        archiveName.lowercased()
+    }
+    
+}

Sources/HummingbirdDocC/Internal/Protocols/Pathable.swift

@@ -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

@@ -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

@@ -0,0 +1,51 @@
+// ===----------------------------------------------------------------------===
+//
+// 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: Properties
+    
+    /// A root path that prefixes 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
+    
+    /// 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.hasPrefix(uriRoot),
+            !uriPath.contains(.Path.previousFolder)
+        else {
+            return nil
+        }
+        
+        return uriPath
+    }
+    
+}

Sources/HummingbirdDocC/Internal/Use Cases/PrepareURIPathUseCase.swift

@@ -0,0 +1,124 @@
+// ===----------------------------------------------------------------------===
+//
+// 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 a resource's information from a given URI path, essential for routing the documentation contents.
+struct PrepareURIPathUseCase {
+    
+    // MARK: Properties
+    
+    /// A root path that prefixes 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 resource's information that is essential for documentation contents routing from a given 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 resource type containing all the relevant information
+    func callAsFunction(_ uriPath: String) -> Resource? {
+        guard let uriRest = uriRest(from: uriPath) else {
+            return nil
+        }
+        
+        let archiveName = archiveName(from: uriRest)
+
+        guard let relativePath = relativePath(from: uriRest, at: archiveName) else {
+            return nil
+        }
+
+        return .init(
+            archiveName: archiveName,
+            relativePath: relativePath
+        )
+    }
+    
+}
+
+// MARK: - Helpers
+
+private extension PrepareURIPathUseCase {
+    
+    // MARK: Functions
+    
+    /// Extracts the archive name from a given URI path.
+    ///
+    /// > important: It is assumed that a given URI path is a relative URI path is prefixed with the `/` character and that contains the name of a `DocC`
+    /// documentation archive in its first component.
+    ///
+    /// - Parameter uriPath: A relative URI path to extract the archive name from.
+    /// - Returns: An archive named extracted from a given URI path.
+    func archiveName(from uriPath: String) -> String {
+        uriPath
+            .split(separator: .Path.forwardSlash)
+            .map(String.init)
+            .first ?? .empty
+    }
+    
+    /// Extracts the rest of the URI path from a given URI path against a defined URI root path.
+    /// - 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 uriRest(from uriPath: String) -> String? {
+        guard let uriRest = uriPath.subtract(uriRoot) else {
+            return nil
+        }
+        guard !uriRest.isEmpty else {
+            return uriRest
+        }
+        guard uriRest.hasPrefix(.Path.forwardSlash) else {
+            return .init(format: .Format.Path.root, uriRest)
+        }
+        
+        return uriRest
+    }
+    
+    /// Extracts the relative URI path from a given URI path against the name of a documentation archive.
+    /// - Parameters:
+    ///   - uriPath: A URI path to get the relative URI path from.
+    ///   - archive: An archive name to subtract from a URI path.
+    /// - Returns: A relative 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 relativePath(
+        from uriPath: String,
+        at archive: String
+    ) -> String? {
+        guard !archive.isEmpty else {
+            return .Path.forwardSlash
+        }
+        
+        let archivePath: String = .init(format: .Format.Path.root, archive)
+
+        guard let relativePath = uriPath.subtract(archivePath) else {
+            return nil
+        }
+        guard relativePath != .empty else {
+            return .empty
+        }
+        
+        return relativePath
+    }
+
+}

Sources/HummingbirdDocC/Internal/Use Cases/RedirectURIUseCase.swift

@@ -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

@@ -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
+        )
+    }
+    
+}

Sources/HummingbirdDocC/Public/Configurations/DoccConfiguration.swift

@@ -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 class NIOPosix.NIOThreadPool
+
+/// A type that contains all the parameters to configure the ``DocCMiddleware`` middleware.
+public struct DocCConfiguration: Sendable {
+    
+    // MARK: Properties
+    
+    /// A path to the physical location where the `DocC` documentation containers are stored.
+    let folderRoot: String
+    
+    /// A URI path that prefixes the `DocC` documentation resources.
+    let uriRoot: String
+    
+    /// A type that define a mechanism to use in case some blocking work needs to be performed for which no non-blocking API exists.
+    let threadPool: NIOThreadPool
+    
+    // MARK: Initializers
+    
+    /// Initializes this configuration type.
+    ///
+    /// > important: It is assumed that both the `uriRoot` and the `folderRoot` parameters should not be empty, and that they should be prefixed
+    /// with the `/` forward slash character.
+    ///
+    /// - Parameters:
+    ///   - uriRoot: A URI path that prefixes the `DocC` documentation resources.
+    ///   - folderRoot: A path to the physical location where the `DocC` documentation containers are stored.
+    ///   - threadPool: A type that define a mechanism to use in case some blocking work needs to be performed for which no non-blocking API exists.
+    public init(
+        uriRoot: String,
+        folderRoot: String,
+        threadPool: NIOThreadPool = .singleton
+    ) {
+        self.folderRoot = folderRoot
+        self.uriRoot = uriRoot
+        self.threadPool = threadPool
+    }
+    
+}

Sources/HummingbirdDocC/Public/Middlewares/DocCMiddleware.swift

@@ -0,0 +1,215 @@
+// ===----------------------------------------------------------------------===
+//
+// 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 protocol Hummingbird.RequestContext
+import protocol Hummingbird.RouterMiddleware
+
+import struct Hummingbird.LocalFileSystem
+import struct Hummingbird.Request
+import struct Hummingbird.Response
+import struct Logging.Logger
+
+/// A middleware that proxies requests to `DocC` documentation containers within a hosting app.
+///
+/// This middleware routes the contents of a `DocC` documentation container, defined by its resource URI paths, following these rules:
+///
+/// 1. *Redirects the URI path `/<ArchiveName>` or `/<ArchiveName>` to the path `/<ArchiveName>/`*;
+/// 2. *Redirects the URI path `/<ArchiveName>/documentation` to the path `/<ArchiveName>/documentation/`*
+/// 3. *Redirects the URI path `/<ArchiveName>/tutorials` to the path `/<ArchiveName>/tutorials/`*
+/// 4. *Redirects the URI path `/<ArchiveName>/documentation/` to the resource on `/<ArchiveName>.doccarchive/documentation/<ArchiveReference>/index.html`*
+/// 5. *Redirects the URI path `/<ArchiveName>/tutorials/` to the resource on `/<ArchiveName>.doccarchive/tutorials/<ArchiveReference>/index.html`*
+/// 6. *Redirects the URI path `/<ArchiveName>/data/documentation.json` to the resource on `/<ArchiveName>.doccarchive/data/documentation/<ArchiveReference>.json`*
+/// 7. *Redirects the URI path `/<ArchiveName>/favicon.ico` to the resource on `/<ArchiveName>.doccarchive/favicon.ico`*
+/// 8. *Redirects the URI path `/<ArchiveName>/favicon.svg` to the resource on `/<ArchiveName>.doccarchive/favicon.svg`*
+/// 9. *Redirects the URI path `/<ArchiveName>/theme-settings.json` to the resource on `/<ArchiveName>.doccarchive/theme-settings.json`*
+/// 10. *Redirects the URI path `/<ArchiveName>/css/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/css/<path/to/file>`*
+/// 11. *Redirects the URI path `/<ArchiveName>/data/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/data/<path/to/file>`*
+/// 12. *Redirects the URI path `/<ArchiveName>/downloads/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/downloads/<path/to/file>`*
+/// 13. *Redirects the URI path `/<ArchiveName>/images/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/images/<path/to/file>`*
+/// 14. *Redirects the URI path `/<ArchiveName>/img/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/img/<path/to/file>`*
+/// 15. *Redirects the URI path `/<ArchiveName>/index/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/index/<path/to/file>`*
+/// 16. *Redirects the URI path `/<ArchiveName>/js/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/js/<path/to/file>`*
+/// 17. *Redirects the URI path `/<ArchiveName>/videos/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/videos/<path/to/file>`*
+///
+public struct DocCMiddleware<
+    Context: RequestContext,
+    FileSystemProvider: FileProvider
+> {
+    
+    // MARK: Properties
+    
+    /// A type that conforms to a protocol that defines file system interactions.
+    let fileProvider: FileSystemProvider
+    
+    /// A type that interacts with the logging system.
+    let logger: Logger
+    
+    /// A use case that checks whether a received URI could be processed or not.
+    private let checkURI: CheckURIUseCase
+    
+    /// A use case that extracts data from a given URI path, essential for routing the documentation contents.
+    private let prepareURIPath: PrepareURIPathUseCase
+    
+    /// A use case that produces a redirect response based on a given URI path.
+    private let redirectURI: RedirectURIUseCase
+    
+    /// A use case that serves a resource, defined by its URI path, from a physical location.
+    private let serveURI: ServeURIUseCase<FileSystemProvider>
+    
+    // MARK: Initializers
+    
+    /// Initializes this middleware.
+    /// - Parameters:
+    ///   - configuration: A type that contains the parameters to configure the middleware.
+    ///   - logger: A type that interacts with the logging system.
+    public init(
+        configuration: DocCConfiguration,
+        logger: Logger
+    ) where FileSystemProvider == LocalFileSystem {
+        self.init(
+            configuration: configuration,
+            fileProvider: LocalFileSystem(
+                rootFolder: configuration.folderRoot,
+                threadPool: configuration.threadPool,
+                logger: logger
+            ),
+            logger: logger,
+        )
+    }
+    
+    /// Initializes this middleware with a concrete file provider type.
+    /// - Parameters:
+    ///   - configuration: A type that contains the parameters to configure the middleware.
+    ///   - fileProvider: A type that conforms to the protocol that defines file system interactions.
+    ///   - logger: A type that interacts with the logging system.
+    init(
+        configuration: DocCConfiguration,
+        fileProvider: FileSystemProvider,
+        logger: Logger,
+    ) {
+        self.logger = logger
+        self.fileProvider = fileProvider
+        self.checkURI = .init(uriRoot: configuration.uriRoot)
+        self.prepareURIPath = .init(uriRoot: configuration.uriRoot)
+        self.redirectURI = .init(logger: logger)
+        self.serveURI = .init(
+            fileProvider: fileProvider,
+            logger: logger
+        )
+    }
+    
+    // MARK: Computed
+    
+    /// A list of relative root URI paths to match against the relative path of a resource.
+    var rootPaths: [String] {[
+        .empty, .Path.forwardSlash
+    ]}
+    
+}
+
+// MARK: - RouterMiddleware
+
+extension DocCMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+    
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Output {
+        guard
+            let uriPath = checkURI(request.uri),
+            let resource = prepareURIPath(uriPath)
+        else {
+            return try await next(request, context)
+        }
+        
+        // Root URI Paths matching.
+        if rootPaths.contains(resource.relativePath) {
+            let uriRoot: String = if resource.relativePath.isEmpty {
+                .init(format: .Format.Path.forwardSlash, uriPath)
+            } else {
+                uriPath
+            }
+
+            // Rule #1: Redirects the URI path /<ArchiveName> or /<ArchiveName>/ to the path /<ArchiveName>/documentation
+            return redirectURI(
+                String(format: .Format.Path.documentation, uriRoot),
+                with: (request, context)
+            )
+        }
+
+        // Asset files matching.
+        for assetFile in AssetFile.allCases {
+            if resource.relativePath.hasPrefix(assetFile.path) {
+                return try await serveURI(
+                    assetFile == .documentation
+                        // Rule #6: Redirects the URI path /<ArchiveName>/data/documentation.json to the resource on /<ArchiveName>.doccarchive/data/documentation/<ArchiveReference>.json
+                        ? String(format: .Format.Path.documentationJSON, resource.archiveReference)
+                        // Rule #7: Redirects the URI path `/<ArchiveName>/favicon.ico` to the resource on `/<ArchiveName>.doccarchive/favicon.ico`
+                        // Rule #8: Redirects the URI path `/<ArchiveName>/favicon.svg` to the resource on `/<ArchiveName>.doccarchive/favicon.svg`
+                        // Rule #9: Redirects the URI path `/<ArchiveName>/theme-settings.json` to the resource on `/<ArchiveName>.doccarchive/theme-settings.json`
+                        : resource.relativePath,
+                    at: resource.archivePath,
+                    with: (request, context)
+                )
+            }
+        }
+        
+        for assetFolder in AssetFolder.allCases {
+            if resource.relativePath.hasPrefix(assetFolder.path) {
+                // Rule #10: Redirects the URI path `/<ArchiveName>/css/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/css/<path/to/file>`
+                // Rule #11: Redirects the URI path `/<ArchiveName>/data/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/data/<path/to/file>`
+                // Rule #12: Redirects the URI path `/<ArchiveName>/downloads/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/downloads/<path/to/file>`
+                // Rule #13: Redirects the URI path `/<ArchiveName>/images/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/images/<path/to/file>`
+                // Rule #14: Redirects the URI path `/<ArchiveName>/img/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/img/<path/to/file>`
+                // Rule #15: Redirects the URI path `/<ArchiveName>/index/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/index/<path/to/file>`
+                // Rule #16: Redirects the URI path `/<ArchiveName>/js/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/js/<path/to/file>`
+                // Rule #17: Redirects the URI path `/<ArchiveName>/videos/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/videos/<path/to/file>`
+                return try await serveURI(
+                    resource.relativePath,
+                    at: resource.archivePath,
+                    with: (request, context)
+                )
+            }
+        }
+
+        for documentationFolder in DocumentationFolder.allCases {
+            if resource.relativePath.hasPrefix(documentationFolder.path) {
+                let pathSuffix: String = .init(format: .Format.Path.forwardSlash, documentationFolder.path)
+                
+                if uriPath.hasSuffix(pathSuffix) {
+                    // Rule #4: Redirects the URI path /<ArchiveName>/documentation/ to the resource on /<ArchiveName>.doccarchive/documentation/<ArchiveReference>/index.html
+                    // Rule #5: Redirects the URI path /<ArchiveName>/tutorials/ to the resource on /<ArchiveName>.doccarchive/tutorials/<ArchiveReference>/index.html
+                    return try await serveURI(
+                        String(format: .Format.Path.index, documentationFolder.path, resource.archiveReference),
+                        at: resource.archivePath,
+                        with: (request, context)
+                    )
+                } else {
+                    // Rule #2: Redirects the URI path /<ArchiveName>/documentation to the path /<ArchiveName>/documentation/
+                    // Rule #3: Redirects the URI path /<ArchiveName>/tutorials to the path /<ArchiveName>/tutorials/
+                    return redirectURI(
+                        String(format: .Format.Path.forwardSlash, uriPath),
+                        with: (request, context)
+                    )
+                }
+            }
+        }
+
+        return try await next(request, context)
+    }
+    
+}
+