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

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

Closed
javier wants to merge 24 commits from middleware/sample into main
pull from: middleware/sample
merge into: rock-n-code:main
Conversation 0 Commits 24 Files Changed 49
+1095 -488
49 changed files with 1095 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env
+8 -4
View File
@@ -12,11 +12,15 @@
# --- DOCUMENTATION ---
DOCC_ARCHIVE_BASE_PATH=archives/${SPM_LIBRARY_TARGET}
DOCC_ARCHIVE_OUTPUT=./${SPM_LIBRARY_TARGET}.doccarchive
DOCC_ARCHIVE_REFERENCE=hummingbirddocc
DOCC_CONFIG_MINIMUM_ACCESS_LEVEL=public
DOCC_CONFIG_PREVIEW_URL=http://localhost:8080/documentation/${DOCC_ARCHIVE_REFERENCE}
DOCC_GITHUB_BASE_PATH=hummingbird-docc
DOCC_GITHUB_OUTPUT=./docs
DOCC_GITHUB_BASE_PATH=hummingbird-docc-middleware
DOCC_PREVIEW_URL=http://localhost:8080/documentation/doccmiddleware
DOCC_XCODE_OUTPUT=./${SPM_LIBRARY_TARGET}.doccarchive
# -- SWIFT PACKAGE MANAGER ---
SPM_LIBRARY_TARGET=DocCMiddleware
SPM_LIBRARY_TARGET=HummingbirdDocC
SPM_SAMPLE_TARGET=HummingbirdDocCSample
Makefile
+32 -14
View File
@@ -20,10 +20,18 @@ export $(shell sed 's/=.*//' $(environment))
# LIBRARY
lib-build: ## Builds the library
@swift build
@swift build \
--target $(SPM_LIBRARY_TARGET)
lib-release: ## Releases the library
@swift build -c release
@swift build \
--target $(SPM_LIBRARY_TARGET) \
--configuration release
lib-sample: ## Runs the sample app of the library
@swift run \
--configuration release \
--disable-sandbox
lib-test: ## Runs the unit tests for the library
@swift test \
@@ -41,8 +49,8 @@ pkg-reset: ## Resets the complete SPM cache/build folder of the package
@swift package reset
pkg-pristine: pkg-clean pkg-reset ## Deletes all built artifacts, caches, and documentations of the package
@rm -drf $(DOCC_ARCHIVE_OUTPUT)
@rm -drf $(DOCC_GITHUB_OUTPUT)
@rm -drf $(DOCC_XCODE_OUTPUT)
pkg-outdated: ## Lists the SPM package dependencies that can be updated
@swift package update --dry-run
@@ -52,7 +60,18 @@ pkg-update: ## Updates the SPM package dependencies
# DOCUMENTATION
doc-generate: doc-generate-xcode doc-generate-github ## Generates the library documentation for both Github and Xcode
doc-generate: doc-generate-archive doc-generate-github ## Generates the library documentation for both Github and Xcode
doc-generate-archive: ## Generates the library documentation archive for Xcode
@swift package \
--allow-writing-to-directory $(DOCC_ARCHIVE_OUTPUT) \
generate-documentation \
--target $(SPM_LIBRARY_TARGET) \
--hosting-base-path $(DOCC_ARCHIVE_BASE_PATH) \
--output-path $(DOCC_ARCHIVE_OUTPUT) \
--symbol-graph-minimum-access-level $(DOCC_CONFIG_MINIMUM_ACCESS_LEVEL) \
--include-extended-types \
--enable-inherited-docs
doc-generate-github: ## Generates the library documentation for Github
@swift package \
@@ -62,21 +81,20 @@ doc-generate-github: ## Generates the library documentation for Github
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path $(DOCC_GITHUB_BASE_PATH) \
--output-path $(DOCC_GITHUB_OUTPUT)
doc-generate-xcode: ## Generates the library documentation for Xcode
@swift package \
--allow-writing-to-directory $(DOCC_XCODE_OUTPUT) \
generate-documentation \
--target $(SPM_LIBRARY_TARGET) \
--output-path $(DOCC_XCODE_OUTPUT)
--output-path $(DOCC_GITHUB_OUTPUT) \
--symbol-graph-minimum-access-level $(DOCC_CONFIG_MINIMUM_ACCESS_LEVEL) \
--include-extended-types \
--enable-inherited-docs
doc-preview: ## Previews the library documentation in Safari
@open -a safari $(DOCC_PREVIEW_URL)
@open -a safari $(DOCC_CONFIG_PREVIEW_URL)
@swift package \
--disable-sandbox \
preview-documentation \
--target $(SPM_LIBRARY_TARGET)
--target $(SPM_LIBRARY_TARGET) \
--symbol-graph-minimum-access-level $(DOCC_CONFIG_MINIMUM_ACCESS_LEVEL) \
--include-extended-types \
--enable-inherited-docs
# IDE
Package.swift
+28 -12
View File
@@ -3,7 +3,7 @@
import PackageDescription
let package = Package(
name: DocCMiddleware.package,
name: HummingbirdDocC.package,
platforms: [
.iOS(.v17),
.macCatalyst(.v17),
@@ -13,38 +13,54 @@ let package = Package(
],
products: [
.library(
name: DocCMiddleware.package,
targets: [DocCMiddleware.target]
name: HummingbirdDocC.package,
targets: [HummingbirdDocC.target]
),
],
dependencies: [
.package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.4.0"),
.package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"),
.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
],
targets: [
.executableTarget(
name: HummingbirdDocC.sample,
dependencies: [
.byName(name: HummingbirdDocC.target),
.product(name: "ArgumentParser", package: "swift-argument-parser"),
],
path: "Samples/HummingbirdDocC",
swiftSettings: [
// Enable better optimizations when building in Release configuration. Despite the use of
// the `.unsafeFlags` construct required by SwiftPM, this flag is recommended for Release
// builds. See <https://github.com/swift-server/guides#building-for-production> for details.
.unsafeFlags(["-cross-module-optimization"], .when(configuration: .release)),
]
),
.target(
name: DocCMiddleware.target,
name: HummingbirdDocC.target,
dependencies: [
.product(name: "Hummingbird", package: "hummingbird"),
],
path: "Sources/DocCMiddleware",
path: "Sources/HummingbirdDocC",
swiftSettings: [.enableExperimentalFeature("StrictConcurrency=complete")]
),
.testTarget(
name: DocCMiddleware.test,
name: HummingbirdDocC.test,
dependencies: [
.product(name: "HummingbirdTesting", package: "hummingbird"),
.byName(name: DocCMiddleware.target)
.byName(name: HummingbirdDocC.target)
],
path: "Tests/DocCMiddleware"
path: "Tests/HummingbirdDocC"
),
]
)
// MARK: - Constants
enum DocCMiddleware {
static let package = "hummingbird-docc-middleware"
static let target = "DocCMiddleware"
static let test = "\(DocCMiddleware.target)Tests"
enum HummingbirdDocC {
static let package = "hummingbird-docc"
static let sample = "\(HummingbirdDocC.target)Sample"
static let target = "HummingbirdDocC"
static let test = "\(HummingbirdDocC.target)Test"
}
Samples/HummingbirdDocC/App/Builders/AppBuilder.swift
+86
View File
@@ -0,0 +1,86 @@
// ===----------------------------------------------------------------------===
//
// 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 Hummingbird.Router
import protocol Hummingbird.ApplicationProtocol
import struct Hummingbird.Application
import struct Hummingbird.BasicRequestContext
import struct Hummingbird.BindAddress
import struct Hummingbird.LogRequestsMiddleware
import struct HummingbirdDocC.DocCConfiguration
import struct HummingbirdDocC.DocCMiddleware
import struct Logging.Logger
struct AppBuilder {
// MARK: Properties
/// A type that interacts with the logging system.
private let logger: Logger
// MARK: Initializers
/// Initializes this builder.
/// - Parameter logger: A type that interacts with the logging system.
init(logger: Logger) {
self.logger = logger
}
// MARK: Functions
func callAsFunction(
_ arguments: AppArguments
) -> some ApplicationProtocol {
return Application(
router: router(),
configuration: .init(
address: .hostname(
arguments.hostname,
port: arguments.port
)
),
logger: logger
)
}
}
// MARK: - Helpers
private extension AppBuilder {
// MARK: Type aliases
typealias AppRequestContext = BasicRequestContext
// MARK: Functions
func router() -> Router<AppRequestContext> {
let router = Router()
router.addMiddleware {
LogRequestsMiddleware(logger.logLevel)
DocCMiddleware (
configuration: DocCConfiguration(
uriRoot: "/archives",
folderRoot: "Samples/HummingbirdDocC/Archives"
),
logger: logger
)
}
return router
}
}
Samples/HummingbirdDocC/App/Parameters/SampleAppArguments.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
//
// ===----------------------------------------------------------------------===
import protocol ArgumentParser.ParsableArguments
import struct ArgumentParser.Option
import struct Logging.Logger
extension SampleApp {
/// A type that conforms to the ``AppArguments`` and the `ParsableArguments` protocols, which contains the input parameters required for the
/// execution of the sample executable.
struct Arguments: AppArguments, ParsableArguments {
// MARK: Properties
@Option(
name: .shortAndLong,
help: "A label given to the sample app for the sole purpose of identification within a communications channel."
)
var hostname: String = "127.0.0.1"
@Option(
name: .shortAndLong,
help: "A port number assigned to the sample app from where the app either sends or receives data."
)
var port: Int = 8080
@Option(
name: .long,
help: "A log level to configure in a type that interacts with the logging system."
)
var logLevel: Logger.Level = .trace
}
}
Samples/HummingbirdDocC/App/Protocols/AppArguments.swift
+40
View File
@@ -0,0 +1,40 @@
// ===----------------------------------------------------------------------===
//
// 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 ArgumentParser.ExpressibleByArgument
import struct Logging.Logger
/// A protocol that defines the input arguments the sample executable requires to run.
protocol AppArguments {
// MARK: Properties
/// A label given to the sample app to identify it within a communications channel.
var hostname: String { get }
/// A port number assigned to the sample app from where the app either sends or receives data.
var port: Int { get }
/// A log level to configure in a type that interacts with the logging system.
var logLevel: Logger.Level { get }
}
// MARK: - Conformances
/// Extends the `Logger.Level` type so it can be used as an argument.
#if hasFeature(RetroactiveAttribute)
extension Logger.Level: @retroactive ExpressibleByArgument {}
#else
extension Logger.Level: ExpressibleByArgument {}
#endif
Samples/HummingbirdDocC/App/SampleApp.swift
+48
View File
@@ -0,0 +1,48 @@
// ===----------------------------------------------------------------------===
//
// 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 ArgumentParser.AsyncParsableCommand
import struct ArgumentParser.OptionGroup
import struct Logging.Logger
/// A type that implements and runs the sample executable that showcases the `Hummingbird-DocC` middleware.
@main struct SampleApp {
// MARK: Properties
/// A type that contains all the necessary input parameters to run the sample executable.
@OptionGroup var arguments: Arguments
}
// MARK: - AsyncParsableCommand
extension SampleApp: AsyncParsableCommand {
// MARK: Functions
func run() async throws {
let builder = AppBuilder(logger: {
var logger = Logger(label: "sample.hummingbird-docc.logger")
logger.logLevel = arguments.logLevel
return logger
}())
let application = builder(arguments)
try await application.run()
}
}
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)
Tests/DocCMiddleware/Tests/Internal/Use Cases/CheckURIUseCaseTests.swift
-116
View File
@@ -1,116 +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 Testing
import struct HummingbirdCore.URI
@testable import struct DocCMiddleware.CheckURIUseCase
@Suite("Check URI use case", .tags(.useCase))
struct CheckURIUseCaseTests {
// MARK: Properties
private let useCase: CheckURIUseCase = .init()
// MARK: Use case tests
#if swift(>=6.2)
@Test(arguments: zip(
Input.nonEncodedURIs,
Output.nonEncodedURIs
))
func `check non encoded URIs`(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
@Test(arguments: zip(
Input.percentEncodedURIs,
Output.percentEncodedURIs
))
func `check percent-encoded URIs`(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
#else
@Test("check non-encoded URIs", arguments: zip(
Input.nonEncodedURIs,
Output.nonEncodedURIs
))
func check_nonEncodedURIs(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
@Test("check percent-encoded URIs", arguments: zip(
Input.percentEncodedURIs,
Output.percentEncodedURIs
))
func check_percentEncodedURIs(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
#endif
}
// MARK: - Assertions
private extension CheckURIUseCaseTests {
// MARK: Functions
/// Asserts a URI path provided by the ``CheckURIPathUseCase`` use case based on a given path and an expected result.
/// - Parameters:
/// - uriPath: A URI path to use with a URI type.
/// - result: An expected result coming out of the use case.
func assertURI(
_ uriPath: String,
expects result: String?
) {
// GIVEN
let uri = URI(uriPath)
// WHEN
let output = useCase(uri)
// THEN
#expect(output == result)
}
}
// MARK: - Constants
private extension Input {
/// A list of non-encoded URI samples.
static let nonEncodedURIs: [String] = ["/", "/some/known/path", "", "/some/../path", "some/other/path"]
/// A list of percent-encoded URI samples.
static let percentEncodedURIs: [String] = ["%2F", "/some%2Fknown%3Fpath", "%20", "/some/%2E%2E/path", "some%2Fother%3Fpath"]
}
private extension Output {
/// A list of expected outputs for the non-encoded URI samples.
static let nonEncodedURIs: [String?] = ["/", "/some/known/path", "/", nil, nil]
/// A list of expected outputs for the percent-encoded URI samples.
static let percentEncodedURIs: [String?] = ["/", "/some/known?path", nil, nil, nil]
}
Tests/DocCMiddleware/Tests/Internal/Enumerations/AssetFileTests.swift → Tests/HummingbirdDocC/Tests/Internal/Enumerations/AssetFileTests.swift
+1 -1
View File
@@ -12,7 +12,7 @@
import Testing
@testable import enum DocCMiddleware.AssetFile
@testable import enum HummingbirdDocC.AssetFile
@Suite("Asset File", .tags(.enumeration))
struct AssetFileTests {
Tests/DocCMiddleware/Tests/Internal/Enumerations/AssetFolderTests.swift → Tests/HummingbirdDocC/Tests/Internal/Enumerations/AssetFolderTests.swift
+1 -1
View File
@@ -12,7 +12,7 @@
import Testing
@testable import enum DocCMiddleware.AssetFolder
@testable import enum HummingbirdDocC.AssetFolder
@Suite("Asset Folder", .tags(.enumeration))
struct AssetFolderTests {
Tests/DocCMiddleware/Tests/Internal/Enumerations/DocumentationFolderTests.swift → Tests/HummingbirdDocC/Tests/Internal/Enumerations/DocumentationFolderTests.swift
+1 -1
View File
@@ -12,7 +12,7 @@
import Testing
@testable import enum DocCMiddleware.DocumentationFolder
@testable import enum HummingbirdDocC.DocumentationFolder
@Suite("Documentation Type", .tags(.enumeration))
struct DocumentationTypeTests {
Tests/DocCMiddleware/Tests/Internal/Extensions/LoggerMetadata+HelpersTests.swift → Tests/HummingbirdDocC/Tests/Internal/Extensions/LoggerMetadata+HelpersTests.swift
+1 -1
View File
@@ -17,7 +17,7 @@ import struct Hummingbird.HTTPResponse
import struct Hummingbird.Request
import struct Logging.Logger
@testable import DocCMiddleware
@testable import HummingbirdDocC
@Suite("Logger Metadata Helpers", .tags(.extension))
struct LoggerMetadata_HelpersTests {
Tests/HummingbirdDocC/Tests/Internal/Extensions/String_HelpersTests.swift
+97
View File
@@ -0,0 +1,97 @@
// ===----------------------------------------------------------------------===
//
// 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 Testing
@testable import HummingbirdDocC
@Suite("String Helpers", .tags(.extension))
struct String_HelpersTests {
// MARK: Functions tests
#if swift(>=6.2)
@Test(arguments: zip(
Input.prefixesToSubtract,
Output.prefixesToSubtract
))
func `subtract`(
prefix: String,
expects newString: String?
) {
assertSubtract(
string: .sample,
prefix: prefix,
expects: newString
)
}
#else
@Test("subtract", arguments: zip(
Input.prefixesToSubtract,
Output.prefixesToSubtract
))
func subtract(
prefix: String,
expects newString: String?
) {
assertSubtract(
string: .sample,
prefix: prefix,
expects: newString
)
}
#endif
}
// MARK: - Assertions
private extension String_HelpersTests {
// MARK: Functions
/// Asserts a string subtraction.
/// - Parameters:
/// - string: A string from where the subtraction will occur.
/// - prefix: A prefix to subtract from a string.
/// - newString: An expected new string created out of the subtraction, if any.
func assertSubtract(
string: String,
prefix: String,
expects newString: String?
) {
// GIVEN
// WHEN
let result = string.subtract(prefix)
// THEN
#expect(result == newString)
}
}
// MARK: - Constants
private extension Input {
/// A list of prefix strings.
static let prefixesToSubtract: [String] = ["Some", .sample, "some", "Else"]
}
private extension Output {
/// A list of outcomes that are expected from subtracting the prefix substrings out of the sample string.
static let prefixesToSubtract: [String?] = ["thing", .empty, nil, nil]
}
private extension String {
/// A sample string.
static let sample = "Something"
}
Tests/HummingbirdDocC/Tests/Internal/Models/ResourceTests.swift
+106
View File
@@ -0,0 +1,106 @@
// ===----------------------------------------------------------------------===
//
// 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 Testing
@testable import struct HummingbirdDocC.Resource
@Suite("Resource", .tags(.model))
struct ResourceTests {
// MARK: Properties tests
#if swift(>=6.2)
@Test
func `archive path`() {
assertArchivePath(
archiveName: "SomeDocument",
expects: "/SomeDocument.doccarchive"
)
}
@Test
func `archive reference`() {
assertArchiveReference(
archiveName: "SomeDocument",
expects: "somedocument"
)
}
#else
@Test("archive path")
func archivePath() {
assertArchivePath(
archiveName: "SomeDocument",
expects: "/SomeDocument.doccarchive"
)
}
@Test("archive reference")
func archiveReference() {
assertArchiveReference(
archiveName: "SomeDocument",
expects: "somedocument"
)
}
#endif
}
// MARK: - Assertions
private extension ResourceTests {
// MARK: Functions
/// Asserts the `archivePath` computed property of a resource.
/// - Parameters:
/// - archiveName: A name of the archive the resource belongs to.
/// - archivePath: An expected path to a documentation archive related to a given archive name.
func assertArchivePath(
archiveName: String,
expects archivePath: String
) {
// GIVEN
var resource = Resource(
archiveName: archiveName,
relativePath: .empty
)
// WHEN
let result = resource.archivePath
// THEN
#expect(result == archivePath)
}
/// Asserts the `archiveReference` computed property of a resource.
/// - Parameters:
/// - archiveName: A name of the archive the resource belongs to.
/// - archiveReference: An expected reference related to a given archive name.
func assertArchiveReference(
archiveName: String,
expects archiveReference: String
) {
// GIVEN
var resource = Resource(
archiveName: archiveName,
relativePath: .empty
)
// WHEN
let result = resource.archiveReference
// THEN
#expect(result == archiveReference)
}
}
Tests/HummingbirdDocC/Tests/Internal/Use Cases/CheckURIUseCaseTests.swift
+147
View File
@@ -0,0 +1,147 @@
// ===----------------------------------------------------------------------===
//
// 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 Testing
import struct HummingbirdCore.URI
@testable import struct HummingbirdDocC.CheckURIUseCase
@Suite("Check URI use case", .tags(.useCase))
struct CheckURIUseCaseTests {
// MARK: Use case tests
#if swift(>=6.2)
@Test(
arguments: zip(
Input.nonEncodedURIs,
Output.nonEncodedURIs
)
)
func `check non encoded URIs`(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
@Test(
arguments: zip(
Input.percentEncodedURIs,
Output.percentEncodedURIs
)
)
func `check percent-encoded URIs`(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
#else
@Test(
"check non-encoded URIs",
arguments: zip(
Input.nonEncodedURIs,
Output.nonEncodedURIs
)
)
func check_nonEncodedURIs(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
@Test(
"check percent-encoded URIs",
arguments: zip(
Input.percentEncodedURIs,
Output.percentEncodedURIs
)
)
func check_percentEncodedURIs(
uri uriPath: String,
expects result: String?
) {
assertURI(uriPath, expects: result)
}
#endif
}
// MARK: - Assertions
extension CheckURIUseCaseTests {
// MARK: Functions
/// Asserts a URI path provided by the ``CheckURIPathUseCase`` use case based on a given path and an expected result.
/// - Parameters:
/// - uriPath: A URI path to use with a URI type.
/// - uriRoot: A URI path that prefixes the `DocC` documentation resources.
/// - result: An expected result coming out of the use case.
fileprivate func assertURI(
_ uriPath: String,
uriRoot: String = .Sample.uriRoot,
expects result: String?
) {
// GIVEN
let useCase = CheckURIUseCase(uriRoot: uriRoot)
let uri = URI(uriPath)
// WHEN
let output = useCase(uri)
// THEN
#expect(output == result)
}
}
// MARK: - Constants
extension Input {
/// A list of non-encoded URI samples.
fileprivate static let nonEncodedURIs: [String] = [
.Sample.uriRoot + .empty,
.Sample.uriRoot + .Path.forwardSlash,
.Sample.uriRoot + "/some/known/path",
.Sample.uriRoot + "/some/../path",
"some/other/root/some/known/path",
]
/// A list of percent-encoded URI samples.
fileprivate static let percentEncodedURIs: [String] = [
.Sample.uriRoot + "%2F",
.Sample.uriRoot + "/some%2Fknown%3Fpath",
.Sample.uriRoot + "/some/%2E%2E/path",
"some/other%2Froot/some%2Fknown%3Fpath",
]
}
extension Output {
/// A list of expected outputs for the non-encoded URI samples.
fileprivate static let nonEncodedURIs: [String?] = [
.Sample.uriRoot,
.Sample.uriRoot + .Path.forwardSlash,
.Sample.uriRoot + "/some/known/path",
nil,
nil,
]
/// A list of expected outputs for the percent-encoded URI samples.
fileprivate static let percentEncodedURIs: [String?] = [
.Sample.uriRoot + .Path.forwardSlash,
.Sample.uriRoot + "/some/known?path",
nil,
nil,
]
}
Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift → Tests/HummingbirdDocC/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift
+21 -29
View File
@@ -12,7 +12,9 @@
import Testing
@testable import struct DocCMiddleware.PrepareURIPathUseCase
import struct HummingbirdDocC.Resource
@testable import struct HummingbirdDocC.PrepareURIPathUseCase
@Suite("Prepare URI Path Use Case", .tags(.useCase))
struct PrepareURIPathUseCaseTests {
@@ -26,7 +28,7 @@ struct PrepareURIPathUseCaseTests {
))
func `extract data with URI root not suffixed with forward slash`(
uri uriPath: String,
expects result: PrepareURIPathUseCase.PreparedURIPaths?
expects result: Resource?
) throws {
try assertData(
uriRoot: .uriRoot,
@@ -41,7 +43,7 @@ struct PrepareURIPathUseCaseTests {
))
func `extract data with URI root suffixed with forward slash`(
uri uriPath: String,
expects result: PrepareURIPathUseCase.PreparedURIPaths?
expects result: Resource?
) throws {
try assertData(
uriRoot: .uriRootSlashed,
@@ -56,7 +58,7 @@ struct PrepareURIPathUseCaseTests {
))
func data_withURIRoot_notSuffixed_withForwardSlash(
uri uriPath: String,
expects result: PrepareURIPathUseCase.PreparedURIPaths?
expects result: Resource?
) throws {
try assertData(
uriRoot: .uriRoot,
@@ -71,7 +73,7 @@ struct PrepareURIPathUseCaseTests {
))
func data_withURIRoot_suffixed_withForwardSlash(
uri uriPath: String,
expects result: PrepareURIPathUseCase.PreparedURIPaths?
expects result: Resource?
) throws {
try assertData(
uriRoot: .uriRootSlashed,
@@ -94,30 +96,20 @@ private extension PrepareURIPathUseCaseTests {
/// - Parameters:
/// - uriRoot: A URI path to initialize the use case with.
/// - uriPath: A URI path to use with the use case.
/// - result: An expected result coming out of the use case.
/// - resource: An expected resource coming out of the use case, if any.
func assertData(
uriRoot: String,
uriPath: String,
expects result: PrepareURIPathUseCase.PreparedURIPaths?
expects resource: Resource?
) throws {
// GIVEN
let useCase = PrepareURIPathUseCase(uriRoot: uriRoot)
// WHEN
let output = useCase(uriPath)
let result = useCase(uriPath)
// THEN
if !uriPath.contains(uriRoot) {
#expect(output == nil)
} else {
#expect(output != nil)
let data = try #require(output)
#expect(data.archiveName == result?.archiveName)
#expect(data.archivePath == result?.archivePath)
#expect(data.resourcePath == result?.resourcePath)
}
#expect(result == resource)
}
}
@@ -126,29 +118,29 @@ private extension PrepareURIPathUseCaseTests {
private extension Input {
/// A list of URI paths to match against the root URI path not suffixed with a forward slash.
static let prepareURIPaths: [String] = [.uriOffset, .uriRoot, .uriOther]
static let prepareURIPaths: [String] = [.uriRoot, .uriOffset, .uriOther]
/// A list of URI paths to match against the root URI path suffixed with a forward slash.
static let prepareURIPathsSlashed: [String] = [.uriOffsetSlashed, .uriRootSlashed, .uriOther]
static let prepareURIPathsSlashed: [String] = [.uriRootSlashed, .uriOffsetSlashed, .uriOther]
}
private extension Output {
/// A list of expected outputs for the URI path samples, regardless their match against suffixed or not suffixed root URI paths.
static let prepareURIPaths: [PrepareURIPathUseCase.PreparedURIPaths?] = [
("SomeArchive", "somearchive", "/SomeArchive.doccarchive", "/SomeArchive/some/content/path"),
(.empty, .empty, .empty, .Path.forwardSlash),
static let prepareURIPaths: [Resource?] = [
.init(archiveName: .empty, relativePath: .Path.forwardSlash),
.init(archiveName: "SomeArchive", relativePath: "/some/content/path"),
nil
]
}
private extension String {
/// A root URI path to initialize the use case with.
static let uriRoot: Self = "/some/path"
static let uriRoot = "/some/path"
/// A root URI path suffixed with a forward slash to initialize the use case with.
static let uriRootSlashed: Self = "/some/path/"
static let uriRootSlashed = "/some/path/"
/// A URI path prefixed with a root URI path not suffixed with a forward slash.
static let uriOffset: Self = .uriRoot + "/SomeArchive/some/content/path"
static let uriOffset = .uriRoot + "/SomeArchive/some/content/path"
/// A URI path prefixed with a root URI path suffixed with a forward slash.
static let uriOffsetSlashed: Self = .uriRootSlashed + "SomeArchive/some/content/path"
static let uriOffsetSlashed = .uriRootSlashed + "SomeArchive/some/content/path"
/// A URI path not related to any root URI path.
static let uriOther: Self = "/some/other/path"
static let uriOther = "/some/other/path"
}
Tests/DocCMiddleware/Tests/Internal/Use Cases/RedirectURIUseCaseTests.swift → Tests/HummingbirdDocC/Tests/Internal/Use Cases/RedirectURIUseCaseTests.swift
+2 -2
View File
@@ -18,7 +18,7 @@ import struct Hummingbird.HTTPResponse
import struct Hummingbird.Request
import struct Logging.Logger
@testable import struct DocCMiddleware.RedirectURIUseCase
@testable import struct HummingbirdDocC.RedirectURIUseCase
@Suite("Redirect URI Use Case", .tags(.useCase))
struct RedirectURIUseCaseTests {
@@ -107,7 +107,7 @@ private extension RedirectURIUseCaseTests {
.contentLength: "0"
])
let events = await logHandler.entries
let events = logHandler.entries
if shouldEventBeLogged(logLevel) {
#expect(!events.isEmpty)
Tests/DocCMiddleware/Tests/Internal/Use Cases/ServeURIUseCaseTests.swift → Tests/HummingbirdDocC/Tests/Internal/Use Cases/ServeURIUseCaseTests.swift
+2 -2
View File
@@ -18,7 +18,7 @@ import struct Hummingbird.HTTPResponse
import struct Hummingbird.Request
import struct Logging.Logger
@testable import struct DocCMiddleware.ServeURIUseCase
@testable import struct HummingbirdDocC.ServeURIUseCase
@Suite("Serve URI Use Case", .tags(.useCase))
struct ServeURIUseCaseTests {
@@ -190,7 +190,7 @@ private extension ServeURIUseCaseTests {
#expect(contentLength == 0)
}
let events = await logHandler.entries
let events = logHandler.entries
if shouldEventBeLogged(
logLevel: logLevel,
Tests/DocCMiddleware/Tests/Public/Middlewares/DocCMiddlewareTests.swift → Tests/HummingbirdDocC/Tests/Public/Middlewares/DocCMiddlewareTests.swift
+35 -32
View File
@@ -20,7 +20,8 @@ import struct Hummingbird.LocalFileSystem
import struct Hummingbird.Request
import struct Logging.Logger
@testable import struct DocCMiddleware.DocCMiddleware
@testable import struct HummingbirdDocC.DocCConfiguration
@testable import struct HummingbirdDocC.DocCMiddleware
@Suite("DocC Middleware", .tags(.middleware))
struct DocCMiddlewareTests {
@@ -290,21 +291,17 @@ private extension DocCMiddlewareTests {
/// - configuration: A type that contains the parameters to configure the middleware.
/// - logger: A type that interacts with the logging system.
func assertInit(
configuration: DocCMiddleware<LocalFileSystem>.Configuration,
configuration: DocCConfiguration,
logger: Logger = .test()
) {
// GIVEN
// WHEN
let middleware = DocCMiddleware(
let middleware = DocCMiddleware<RequestContextMock, LocalFileSystem>(
configuration: configuration,
logger: logger
)
// THEN
#expect(middleware.configuration.folderRoot == configuration.folderRoot)
#expect(middleware.configuration.uriRoot == configuration.uriRoot)
#expect(middleware.configuration.threadPool === configuration.threadPool)
#expect(middleware.logger.label == logger.label)
#expect(middleware.logger.logLevel == logger.logLevel)
#expect(middleware.logger.metadataProvider == nil)
@@ -318,23 +315,19 @@ private extension DocCMiddlewareTests {
/// - logger: A type that interacts with the logging system.
/// - fileProvider: A type that conforms to the protocol that defines file system interactions, if any.
func assertInit<FileSystemProvider: FileProvider>(
configuration: DocCMiddleware<FileSystemProvider>.Configuration,
configuration: DocCConfiguration,
logger: Logger = .test(),
fileProvider: FileSystemProvider
) {
// GIVEN
// WHEN
let middleware = DocCMiddleware(
let middleware = DocCMiddleware<RequestContextMock, FileSystemProvider>(
configuration: configuration,
fileProvider: fileProvider,
logger: logger
)
// THEN
#expect(middleware.configuration.folderRoot == configuration.folderRoot)
#expect(middleware.configuration.uriRoot == configuration.uriRoot)
#expect(middleware.configuration.threadPool === configuration.threadPool)
#expect(middleware.logger.label == logger.label)
#expect(middleware.logger.logLevel == logger.logLevel)
#expect(middleware.logger.metadataProvider == nil)
@@ -362,13 +355,13 @@ private extension DocCMiddlewareTests {
handler: logHandler
)
let context: any RequestContext = RequestContextMock(logger: logger)
let context: RequestContextMock = .init(logger: logger)
let request: Request = .test(
method: .get,
path: uriPath
)
let middleware = DocCMiddleware(
let middleware = DocCMiddleware<RequestContextMock, FileProviderMock>(
configuration: .init(
uriRoot: .Sample.uriRoot,
folderRoot: .Sample.uriFolder
@@ -385,7 +378,7 @@ private extension DocCMiddlewareTests {
// THEN
#expect(result.status == statusCode)
let events = await logHandler.entries
let events = logHandler.entries
if statusCode == .movedPermanently, let uriRedirect {
#expect(result.body.contentLength == 0)
@@ -448,13 +441,13 @@ private extension DocCMiddlewareTests {
default: .init(fileIdentifier: .init(), shouldLoadFile: false)
}
let context: any RequestContext = RequestContextMock(logger: logger)
let context: RequestContextMock = .init(logger: logger)
let request: Request = .test(
method: .get,
path: uriPath
)
let middleware = DocCMiddleware(
let middleware = DocCMiddleware<RequestContextMock, FileProviderMock>(
configuration: .init(
uriRoot: .Sample.uriRoot,
folderRoot: .Sample.uriFolder
@@ -483,7 +476,7 @@ private extension DocCMiddlewareTests {
#expect(contentLength == 0)
}
let events = await logHandler.entries
let events = logHandler.entries
if shouldEventBeLogged(
logLevel: logLevel,
@@ -552,7 +545,12 @@ private extension DocCMiddlewareTests {
private extension Input {
/// A list of relative URI paths to match against the URI path redirections done by the middleware.
static let redirectURIPaths: [String] = [.empty, .Path.forwardSlash, "/documentation", "/tutorials"]
static let redirectURIPaths: [String] = [
.empty,
.Path.forwardSlash,
"/documentation",
"/tutorials"
]
/// A list of relative URI paths to match against the URI path servings done by the middleware.
static let serveURIPaths: [String] = [
"/documentation/",
@@ -574,22 +572,27 @@ private extension Input {
private extension Output {
/// A list of expected relative URI path redirections outputs coming out of the URI path redirections done by the middleware.
static let redirectURIPaths: [String] = [.Path.forwardSlash, "/documentation", "/documentation/", "/tutorials/"]
static let redirectURIPaths: [String] = [
"/documentation",
"/documentation",
"/documentation/",
"/tutorials/"
]
/// A list of expected relative file URI paths of the logged messages coming out of the URI path servings done by the middleware.
static let serveURIFilePaths: [String] = [
"/SomeDocument.doccarchive/documentation/somedocument/index.html",
"/SomeDocument.doccarchive/tutorials/somedocument/index.html",
"/SomeDocument.doccarchive/data/documentation/somedocument.json",
"/SomeDocument.doccarchive/SomeDocument/favicon.ico",
"/SomeDocument.doccarchive/SomeDocument/favicon.svg",
"/SomeDocument.doccarchive/SomeDocument/theme-settings.json",
"/SomeDocument.doccarchive/SomeDocument/css/file.css",
"/SomeDocument.doccarchive/SomeDocument/data/data.bin",
"/SomeDocument.doccarchive/SomeDocument/downloads/file.txt",
"/SomeDocument.doccarchive/SomeDocument/images/image.png",
"/SomeDocument.doccarchive/SomeDocument/img/image.jpg",
"/SomeDocument.doccarchive/SomeDocument/index/file",
"/SomeDocument.doccarchive/SomeDocument/js/file.js",
"/SomeDocument.doccarchive/SomeDocument/videos/video.mp4"
"/SomeDocument.doccarchive/favicon.ico",
"/SomeDocument.doccarchive/favicon.svg",
"/SomeDocument.doccarchive/theme-settings.json",
"/SomeDocument.doccarchive/css/file.css",
"/SomeDocument.doccarchive/data/data.bin",
"/SomeDocument.doccarchive/downloads/file.txt",
"/SomeDocument.doccarchive/images/image.png",
"/SomeDocument.doccarchive/img/image.jpg",
"/SomeDocument.doccarchive/index/file",
"/SomeDocument.doccarchive/js/file.js",
"/SomeDocument.doccarchive/videos/video.mp4"
]
}
Tests/DocCMiddleware/Types/Extensions/Logger+Helpers.swift → Tests/HummingbirdDocC/Types/Extensions/Logger+Helpers.swift
+1 -1
View File
@@ -53,5 +53,5 @@ extension Logger {
private extension String {
/// A label to assign to a test logger instance.
static let loggerLabel = "test.hummingbird-docc-middleware.logger"
static let loggerLabel = "test.hummingbird-docc.logger"
}
Tests/DocCMiddleware/Types/Extensions/LoggerLevel+Helpers.swift → Tests/HummingbirdDocC/Types/Extensions/LoggerLevel+Helpers.swift
View File
Tests/DocCMiddleware/Types/Extensions/Request+Helpers.swift → Tests/HummingbirdDocC/Types/Extensions/Request+Helpers.swift
View File
Tests/DocCMiddleware/Types/Extensions/String+Constants.swift → Tests/HummingbirdDocC/Types/Extensions/String+Constants.swift
View File
Tests/DocCMiddleware/Types/Extensions/Tag+Constants.swift → Tests/HummingbirdDocC/Types/Extensions/Tag+Constants.swift
+2
View File
@@ -22,6 +22,8 @@ extension Tag {
@Tag static var `extension`: Self
/// Tag that indicate a test case for a middleware type.
@Tag static var middleware: Self
/// Tag that indicate a test case for a model type.
@Tag static var model: Self
/// Tag that indicate a test case for a use case type.
@Tag static var useCase: Self
Tests/DocCMiddleware/Types/Mocks/FileProviderMock.swift → Tests/HummingbirdDocC/Types/Mocks/FileProviderMock.swift
View File
Tests/DocCMiddleware/Types/Mocks/LogHandlerMock.swift → Tests/HummingbirdDocC/Types/Mocks/LogHandlerMock.swift
+27 -15
View File
@@ -33,9 +33,7 @@ struct LogHandlerMock {
// MARK: Computed
/// A list of all the logged events that are being persisted in the recorder.
var entries: [LogEntry] {
get async { await recorder.entries }
}
var entries: [LogEntry] { recorder.entries }
}
@@ -63,13 +61,25 @@ struct LogEntry: Equatable {
// MARK: - LogRecorder
extension LogHandlerMock {
/// An actor that persists all the events logged by the ``LogHandlerMock`` mock handler.
actor LogRecorder {
/// A class that records all the events logged by the ``LogHandlerMock`` mock handler.
///
/// This class conforms to the `Sendable` protocol by using the `@unchecked` modifier because a `NSLock`type is used to handle the access to the logged events in a thread-safe way.
final class LogRecorder: @unchecked Sendable {
// MARK: Properties
/// A list of all the logged events persisted in a thread-safe way.
private(set) var _entries: [LogEntry] = []
/// A type that coordinates the access to the persisted logged events in a thread-safe way.
private let lock: NSLock = .init()
// MARK: Computed
/// A list of all the logged events.
private(set) var entries: [LogEntry] = []
var entries: [LogEntry] {
lock.withLock { _entries }
}
// MARK: Functions
@@ -84,13 +94,15 @@ extension LogHandlerMock {
metadata: Logger.Metadata?,
message: Logger.Message,
source: String
) async {
entries += [.init(
level: level,
metadata: metadata,
message: message,
source: source
)]
) {
lock.withLock {
_entries += [.init(
level: level,
metadata: metadata,
message: message,
source: source
)]
}
}
}
@@ -130,12 +142,12 @@ extension LogHandlerMock: LogHandler {
function: String,
line: UInt
) {
Task { await recorder.record(
recorder.record(
level: level,
metadata: metadata,
message: message,
source: source
)}
)
}
}
Tests/DocCMiddleware/Types/Mocks/RequestContextMock.swift → Tests/HummingbirdDocC/Types/Mocks/RequestContextMock.swift
View File
Tests/DocCMiddleware/Types/Namespaces/Input.swift → Tests/HummingbirdDocC/Types/Namespaces/Input.swift
View File
Tests/DocCMiddleware/Types/Namespaces/Output.swift → Tests/HummingbirdDocC/Types/Namespaces/Output.swift
View File
Tests/DocCMiddleware/Types/Stubs/FileProviderStub.swift → Tests/HummingbirdDocC/Types/Stubs/FileProviderStub.swift
View File