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/HummingbirdDocC/Internal/Use Cases/CheckURIUseCase.swift
+51
View File
@@ -0,0 +1,51 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import struct HummingbirdCore.URI
/// A use case that checks whether a given URI against a set of conditions, to determine whether the URI could be used by the middleware or not.
struct CheckURIUseCase {
// MARK: Properties
/// A root path that prefixes the documentation resource.
private let uriRoot: String
// MARK: Initializers
/// Initializes this use case.
///
/// > important: It is assumed that the `uriRoot` parameter is not empty and that it is prefixed by the `/` character.
///
/// - Parameter uriRoot: A root path that prefixes the documentation resource.
init(uriRoot: String) {
self.uriRoot = uriRoot
}
// MARK: Functions
/// Checks whether a provided URI against a set of conditions, so it could be used by the middleware.
/// - Parameter uri: A URI to check.
/// - Returns: A non-encoded URI, which is ready to be used by the middleware.
func callAsFunction(_ uri: URI) -> String? {
guard
let uriPath = uri.path.removingPercentEncoding,
uriPath.hasPrefix(uriRoot),
!uriPath.contains(.Path.previousFolder)
else {
return nil
}
return uriPath
}
}
Sources/HummingbirdDocC/Internal/Use Cases/PrepareURIPathUseCase.swift
+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/HummingbirdDocC/Internal/Use Cases/RedirectURIUseCase.swift
+63
View File
@@ -0,0 +1,63 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import struct Hummingbird.Response
import struct Logging.Logger
/// A use case that produces a redirect response based on a given URI path.
struct RedirectURIUseCase {
// MARK: Properties
/// A type that interacts with the logging system.
private let logger: Logger
// MARK: Initializers
/// Initializes this use case.
/// - Parameter logger: A type that interacts with the logging system.
init(logger: Logger) {
self.logger = logger
}
// MARK: Functions
/// Produces a redirect response based on a given URI path
/// - Parameters:
/// - uriPath: A URI path to use in the redirection.
/// - contextualInfo: A pseudo-type that contains data about a request and its related context.
/// - Returns: A redirection response created out of a given URI path plus contextual information.
func callAsFunction(
_ uriPath: String,
with contextualInfo: ContextualInfo
) -> Response {
defer {
logger.log(
level: .debug,
"The URI path is redirected to this path: \(uriPath)",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .movedPermanently,
redirect: uriPath
),
source: .Logging.source
)
}
return .redirect(
to: uriPath,
type: .permanent
)
}
}
Sources/HummingbirdDocC/Internal/Use Cases/ServeURIUseCase.swift
+100
View File
@@ -0,0 +1,100 @@
// ===----------------------------------------------------------------------===
//
// This source file is part of the Hummingbird DocC Middleware open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
//
// ===----------------------------------------------------------------------===
import protocol Hummingbird.FileProvider
import struct Hummingbird.Response
import struct Logging.Logger
/// A use case that serves a resource, defined by its URI path, from a physical location.
struct ServeURIUseCase<Provider: FileProvider> {
// MARK: Properties
/// A type that conforms to a protocol that defines file system interactions.
private let fileProvider: Provider
/// A type that interacts with the logging system.
private let logger: Logger
// MARK: Initializers
/// Initializes this use case.
/// - Parameters:
/// - fileProvider: A type that conforms to a protocol that defines file system interactions.
/// - logger: A type that interacts with the logging system.
init(
fileProvider: Provider,
logger: Logger
) {
self.fileProvider = fileProvider
self.logger = logger
}
// MARK: Functions
/// Serves a certain resource based on a given URI path from a physical location.
/// - Parameters:
/// - uriPath: A URI path that represents a resource to be served.
/// - folderPath: A URI path to a physical folder that contains the resource.
/// - contextualInfo: A pseudo-type that contains data about a request and its related context.
/// - Returns: A response that either contains the data of the resource in its body in case the resource is found, or a not found otherwise.
/// - Throws: An error in case an issue is encountered while serving the resource.
func callAsFunction(
_ uriPath: String,
at folderPath: String,
with contextualInfo: ContextualInfo
) async throws -> Response {
let filePath = folderPath + uriPath
guard let fileIdentifier = fileProvider.getFileIdentifier(filePath) else {
defer {
logger.log(
level: .error,
"The resource \(filePath) has not been found.",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .notFound
),
source: .Logging.source
)
}
return .init(status: .notFound)
}
let body = try await fileProvider.loadFile(
id: fileIdentifier,
context: contextualInfo.context
)
defer {
logger.log(
level: .debug,
"The body of the resource \(filePath) has \(body.contentLength ?? 0) bytes.",
metadata: .metadata(
context: contextualInfo.context,
request: contextualInfo.request,
statusCode: .ok
),
source: .Logging.source
)
}
return .init(
status: .ok,
body: body
)
}
}