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

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

Browse Source 
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>
This commit was merged in pull request #4.
This commit is contained in:
Javier Cicchelli
2025-09-30 15:38:12 +00:00
committed by Javier Cicchelli
parent 3a9e3d176f
commit 1382f33ae6
49 changed files with 1095 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift
-127
View File
@@ -1,127 +0,0 @@
// ===----------------------------------------------------------------------===
//
// 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/DocCMiddleware/Public/Configurations/DoccMiddlewareConfiguration.swift
-52
View File
@@ -1,52 +0,0 @@
// ===----------------------------------------------------------------------===
//
// 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
extension DocCMiddleware {
/// A type that contains all the parameters to configure the ``DocCMiddleware`` middleware.
public struct Configuration: 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/DocCMiddleware/Catalogs/DocCMiddleware.docc/Library.md → Sources/HummingbirdDocC/Catalogs/HummingbirdDocC.docc/Library.md
+1 -1
View File
@@ -1,4 +1,4 @@
# ``DocCMiddleware``
# ``HummingbirdDocC``
<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
Sources/DocCMiddleware/Internal/Enumerations/AssetFile.swift → Sources/HummingbirdDocC/Internal/Enumerations/AssetFile.swift
View File
Sources/DocCMiddleware/Internal/Enumerations/AssetFolder.swift → Sources/HummingbirdDocC/Internal/Enumerations/AssetFolder.swift
View File
Sources/DocCMiddleware/Internal/Enumerations/DocumentationFolder.swift → Sources/HummingbirdDocC/Internal/Enumerations/DocumentationFolder.swift
View File
Sources/DocCMiddleware/Internal/Extensions/LoggerMetadata+Helpers.swift → Sources/HummingbirdDocC/Internal/Extensions/LoggerMetadata+Helpers.swift
View File
Sources/DocCMiddleware/Internal/Extensions/String+Constants.swift → Sources/HummingbirdDocC/Internal/Extensions/String+Constants.swift
View File
Sources/DocCMiddleware/Internal/Extensions/String+Formats.swift → Sources/HummingbirdDocC/Internal/Extensions/String+Formats.swift
View File
Sources/HummingbirdDocC/Internal/Extensions/String+Helpers.swift
+46
View File
@@ -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
+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
//
// ===----------------------------------------------------------------------===
/// 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/DocCMiddleware/Internal/Protocols/Pathable.swift → Sources/HummingbirdDocC/Internal/Protocols/Pathable.swift
View File
Sources/DocCMiddleware/Internal/Pseudo Types/ContextualInfo.swift → Sources/HummingbirdDocC/Internal/Pseudo Types/ContextualInfo.swift
View File
Sources/DocCMiddleware/Internal/Use Cases/CheckURIUseCase.swift → Sources/HummingbirdDocC/Internal/Use Cases/CheckURIUseCase.swift
+18 -2
View File
@@ -14,6 +14,22 @@ 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
@@ -23,8 +39,8 @@ struct CheckURIUseCase {
func callAsFunction(_ uri: URI) -> String? {
guard
let uriPath = uri.path.removingPercentEncoding,
!uriPath.contains(.Path.previousFolder),
uriPath.hasPrefix(.Path.forwardSlash)
uriPath.hasPrefix(uriRoot),
!uriPath.contains(.Path.previousFolder)
else {
return nil
}
Sources/HummingbirdDocC/Internal/Use Cases/PrepareURIPathUseCase.swift
+124
View File
@@ -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/DocCMiddleware/Internal/Use Cases/RedirectURIUseCase.swift → Sources/HummingbirdDocC/Internal/Use Cases/RedirectURIUseCase.swift
View File
Sources/DocCMiddleware/Internal/Use Cases/ServeURIUseCase.swift → Sources/HummingbirdDocC/Internal/Use Cases/ServeURIUseCase.swift
View File
Sources/HummingbirdDocC/Public/Configurations/DoccConfiguration.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 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/DocCMiddleware/Public/Middlewares/DocCMiddleware.swift → Sources/HummingbirdDocC/Public/Middlewares/DocCMiddleware.swift
+77 -75
View File
@@ -23,32 +23,31 @@ import struct Logging.Logger
///
/// 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>` to the path `/<ArchiveName>/`*;
/// 2. *Redirects the URI path `/<ArchiveName>/` to the path `/<ArchiveName>/documentation`*
/// 3. *Redirects the URI path `/<ArchiveName>/documentation` to the path `/<ArchiveName>/documentation/`*
/// 4. *Redirects the URI path `/<ArchiveName>/tutorials` to the path `/<ArchiveName>/tutorials/`*
/// 5. *Redirects the URI path `/<ArchiveName>/documentation/` to the resource on `/<ArchiveName>.doccarchive/documentation/<ArchiveReference>/index.html`*
/// 6. *Redirects the URI path `/<ArchiveName>/tutorials/` to the resource on `/<ArchiveName>.doccarchive/tutorials/<ArchiveReference>/index.html`*
/// 7. *Redirects the URI path `/<ArchiveName>/data/documentation.json` to the resource on `/<ArchiveName>.doccarchive/data/documentation/<ArchiveReference>.json`*
/// 8. *Redirects the URI path `/<ArchiveName>/favicon.ico` to the resource on `/<ArchiveName>.doccarchive/favicon.ico`*
/// 9. *Redirects the URI path `/<ArchiveName>/favicon.svg` to the resource on `/<ArchiveName>.doccarchive/favicon.svg`*
/// 10. *Redirects the URI path `/<ArchiveName>/theme-settings.json` to the resource on `/<ArchiveName>.doccarchive/theme-settings.json`*
/// 11. *Redirects the URI path `/<ArchiveName>/css/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/css/<path/to/file>`*
/// 12. *Redirects the URI path `/<ArchiveName>/data/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/data/<path/to/file>`*
/// 13. *Redirects the URI path `/<ArchiveName>/downloads/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/downloads/<path/to/file>`*
/// 14. *Redirects the URI path `/<ArchiveName>/images/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/images/<path/to/file>`*
/// 15. *Redirects the URI path `/<ArchiveName>/img/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/img/<path/to/file>`*
/// 16. *Redirects the URI path `/<ArchiveName>/index/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/index/<path/to/file>`*
/// 17. *Redirects the URI path `/<ArchiveName>/js/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/js/<path/to/file>`*
/// 18. *Redirects the URI path `/<ArchiveName>/videos/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/videos/<path/to/file>`*
/// 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<FileSystemProvider: FileProvider> {
public struct DocCMiddleware<
Context: RequestContext,
FileSystemProvider: FileProvider
> {
// MARK: Properties
/// A type that contains the parameters to configure the middleware.
let configuration: Configuration
/// A type that conforms to a protocol that defines file system interactions.
let fileProvider: FileSystemProvider
@@ -56,7 +55,7 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
let logger: Logger
/// A use case that checks whether a received URI could be processed or not.
private let checkURI: CheckURIUseCase = .init()
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
@@ -74,7 +73,7 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
/// - configuration: A type that contains the parameters to configure the middleware.
/// - logger: A type that interacts with the logging system.
public init(
configuration: Configuration,
configuration: DocCConfiguration,
logger: Logger
) where FileSystemProvider == LocalFileSystem {
self.init(
@@ -94,13 +93,13 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
/// - fileProvider: A type that conforms to the protocol that defines file system interactions.
/// - logger: A type that interacts with the logging system.
init(
configuration: Configuration,
configuration: DocCConfiguration,
fileProvider: FileSystemProvider,
logger: Logger,
) {
self.logger = logger
self.configuration = configuration
self.fileProvider = fileProvider
self.checkURI = .init(uriRoot: configuration.uriRoot)
self.prepareURIPath = .init(uriRoot: configuration.uriRoot)
self.redirectURI = .init(logger: logger)
self.serveURI = .init(
@@ -109,95 +108,98 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
)
}
// 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: Type aliases
public typealias Context = RequestContext
public typealias Input = Request
public typealias Output = Response
// MARK: Functions
public func handle(
_ request: Input,
context: any Context,
next: (Input, any Context) async throws -> Output
_ request: Request,
context: Context,
next: (Request, Context) async throws -> Response
) async throws -> Output {
guard
let uriPath = checkURI(request.uri),
let uriData = prepareURIPath(uriPath)
let resource = prepareURIPath(uriPath)
else {
return try await next(request, context)
}
let rootPaths: [String] = [
String(format: .Format.Path.root, uriData.archiveName),
String(format: .Format.Path.folder, uriData.archiveName)
]
// Root URI Paths matching.
if rootPaths.contains(resource.relativePath) {
let uriRoot: String = if resource.relativePath.isEmpty {
.init(format: .Format.Path.forwardSlash, uriPath)
} else {
uriPath
}
if rootPaths.contains(uriData.resourcePath) {
// Rule #1: Redirects the URI path /<ArchiveName> or /<ArchiveName>/ to the path /<ArchiveName>/documentation
return redirectURI(
uriPath.hasSuffix(.Path.forwardSlash)
// Rule #2: Redirects the URI path /<ArchiveName>/ to the path /<ArchiveName>/documentation
? String(format: .Format.Path.documentation, uriPath)
// Rule #1: Redirects the URI path /<ArchiveName> to the path /<ArchiveName>/
: String(format: .Format.Path.forwardSlash, uriPath),
String(format: .Format.Path.documentation, uriRoot),
with: (request, context)
)
}
// Asset files matching.
for assetFile in AssetFile.allCases {
if uriData.resourcePath.contains(assetFile.path) {
if resource.relativePath.hasPrefix(assetFile.path) {
return try await serveURI(
assetFile == .documentation
// Rule #7: Redirects the URI path /<ArchiveName>/data/documentation.json to the resource on /<ArchiveName>.doccarchive/data/documentation/<ArchiveReference>.json
? String(format: .Format.Path.documentationJSON, uriData.archiveReference)
// Rule #8: Redirects the URI path `/<ArchiveName>/favicon.ico` to the resource on `/<ArchiveName>.doccarchive/favicon.ico`
// Rule #9: Redirects the URI path `/<ArchiveName>/favicon.svg` to the resource on `/<ArchiveName>.doccarchive/favicon.svg`
// Rule #10: Redirects the URI path `/<ArchiveName>/theme-settings.json` to the resource on `/<ArchiveName>.doccarchive/theme-settings.json`
: uriData.resourcePath,
at: uriData.archivePath,
// 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 uriData.resourcePath.contains(assetFolder.path) {
// Rule #11: Redirects the URI path `/<ArchiveName>/css/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/css/<path/to/file>`
// Rule #12: Redirects the URI path `/<ArchiveName>/data/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/data/<path/to/file>`
// Rule #13: Redirects the URI path `/<ArchiveName>/downloads/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/downloads/<path/to/file>`
// Rule #14: Redirects the URI path `/<ArchiveName>/images/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/images/<path/to/file>`
// Rule #15: Redirects the URI path `/<ArchiveName>/img/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/img/<path/to/file>`
// Rule #16: Redirects the URI path `/<ArchiveName>/index/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/index/<path/to/file>`
// Rule #17: Redirects the URI path `/<ArchiveName>/js/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/js/<path/to/file>`
// Rule #18: Redirects the URI path `/<ArchiveName>/videos/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/videos/<path/to/file>`
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(
uriData.resourcePath,
at: uriData.archivePath,
resource.relativePath,
at: resource.archivePath,
with: (request, context)
)
}
}
for documentationFolder in DocumentationFolder.allCases {
if uriData.resourcePath.contains(documentationFolder.path) {
if uriData.resourcePath.hasSuffix(.Path.forwardSlash) {
// Rule #5: Redirects the URI path /<ArchiveName>/documentation/ to the resource on /<ArchiveName>.doccarchive/documentation/<ArchiveReference>/index.html
// Rule #6: Redirects the URI path /<ArchiveName>/tutorials/ to the resource on /<ArchiveName>.doccarchive/tutorials/<ArchiveReference>/index.html
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, uriData.archiveReference),
at: uriData.archivePath,
String(format: .Format.Path.index, documentationFolder.path, resource.archiveReference),
at: resource.archivePath,
with: (request, context)
)
} else {
// Rule #3: Redirects the URI path /<ArchiveName>/documentation to the path /<ArchiveName>/documentation/
// Rule #4: Redirects the URI path /<ArchiveName>/tutorials to the path /<ArchiveName>/tutorials/
// 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)