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

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

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

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

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