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
+104 -96
2 changed files with 104 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 4dd7e62560 - Show all commits
Sources/HummingbirdDocC/Public/Middlewares/DocCMiddleware.swift
+73 -67
View File
@@ -23,26 +23,28 @@ import struct Logging.Logger
/// ///
/// This middleware routes the contents of a `DocC` documentation container, defined by its resource URI paths, following these rules: /// 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>/`*; /// 1. *Redirects the URI path `/<ArchiveName>` or `/<ArchiveName>` to the path `/<ArchiveName>/`*;
/// 2. *Redirects the URI path `/<ArchiveName>/` to the path `/<ArchiveName>/documentation`* /// 2. *Redirects the URI path `/<ArchiveName>/documentation` to the path `/<ArchiveName>/documentation/`*
/// 3. *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>/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>/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>/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>/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.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>/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>/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>/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>/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>/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>/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>/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>/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>/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>`*
/// 18. *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 // MARK: Properties
@@ -53,7 +55,7 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
let logger: Logger let logger: Logger
/// A use case that checks whether a received URI could be processed or not. /// 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. /// A use case that extracts data from a given URI path, essential for routing the documentation contents.
private let prepareURIPath: PrepareURIPathUseCase private let prepareURIPath: PrepareURIPathUseCase
@@ -97,6 +99,7 @@ public struct DocCMiddleware<FileSystemProvider: FileProvider> {
) { ) {
self.logger = logger self.logger = logger
self.fileProvider = fileProvider self.fileProvider = fileProvider
self.checkURI = .init(uriRoot: configuration.uriRoot)
self.prepareURIPath = .init(uriRoot: configuration.uriRoot) self.prepareURIPath = .init(uriRoot: configuration.uriRoot)
self.redirectURI = .init(logger: logger) self.redirectURI = .init(logger: logger)
self.serveURI = .init( self.serveURI = .init(
@@ -105,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 // MARK: - RouterMiddleware
extension DocCMiddleware: RouterMiddleware { extension DocCMiddleware: RouterMiddleware {
// MARK: Type aliases
public typealias Context = RequestContext
public typealias Input = Request
public typealias Output = Response
// MARK: Functions // MARK: Functions
public func handle( public func handle(
_ request: Input, _ request: Request,
context: any Context, context: Context,
next: (Input, any Context) async throws -> Output next: (Request, Context) async throws -> Response
) async throws -> Output { ) async throws -> Output {
guard guard
let uriPath = checkURI(request.uri), let uriPath = checkURI(request.uri),
let uriData = prepareURIPath(uriPath) let resource = prepareURIPath(uriPath)
else { else {
return try await next(request, context) return try await next(request, context)
} }
let rootPaths: [String] = [ // Root URI Paths matching.
String(format: .Format.Path.root, uriData.archiveName), if rootPaths.contains(resource.relativePath) {
String(format: .Format.Path.folder, uriData.archiveName) 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( return redirectURI(
uriPath.hasSuffix(.Path.forwardSlash) String(format: .Format.Path.documentation, uriRoot),
// 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),
with: (request, context) with: (request, context)
) )
} }
// Asset files matching.
for assetFile in AssetFile.allCases { for assetFile in AssetFile.allCases {
if uriData.resourcePath.contains(assetFile.path) { if resource.relativePath.hasPrefix(assetFile.path) {
return try await serveURI( return try await serveURI(
assetFile == .documentation assetFile == .documentation
// Rule #7: Redirects the URI path /<ArchiveName>/data/documentation.json to the resource on /<ArchiveName>.doccarchive/data/documentation/<ArchiveReference>.json // 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, uriData.archiveReference) ? String(format: .Format.Path.documentationJSON, resource.archiveReference)
// Rule #8: Redirects the URI path `/<ArchiveName>/favicon.ico` to the resource on `/<ArchiveName>.doccarchive/favicon.ico` // Rule #7: 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 #8: 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` // Rule #9: Redirects the URI path `/<ArchiveName>/theme-settings.json` to the resource on `/<ArchiveName>.doccarchive/theme-settings.json`
: uriData.resourcePath, : resource.relativePath,
at: uriData.archivePath, at: resource.archivePath,
with: (request, context) with: (request, context)
) )
} }
} }
for assetFolder in AssetFolder.allCases { for assetFolder in AssetFolder.allCases {
if uriData.resourcePath.contains(assetFolder.path) { if resource.relativePath.hasPrefix(assetFolder.path) {
// Rule #11: Redirects the URI path `/<ArchiveName>/css/<path/to/file>` to the resource on `/<ArchiveName>.doccarchive/css/<path/to/file>` // Rule #10: 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 #11: 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 #12: 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 #13: 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 #14: 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 #15: 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 #16: 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>` // 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( return try await serveURI(
uriData.resourcePath, resource.relativePath,
at: uriData.archivePath, at: resource.archivePath,
with: (request, context) with: (request, context)
) )
} }
} }
for documentationFolder in DocumentationFolder.allCases { for documentationFolder in DocumentationFolder.allCases {
if uriData.resourcePath.contains(documentationFolder.path) { if resource.relativePath.hasPrefix(documentationFolder.path) {
if uriData.resourcePath.hasSuffix(.Path.forwardSlash) { let pathSuffix: String = .init(format: .Format.Path.forwardSlash, documentationFolder.path)
// 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 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( return try await serveURI(
String(format: .Format.Path.index, documentationFolder.path, uriData.archiveReference), String(format: .Format.Path.index, documentationFolder.path, resource.archiveReference),
at: uriData.archivePath, at: resource.archivePath,
with: (request, context) with: (request, context)
) )
} else { } else {
// Rule #3: Redirects the URI path /<ArchiveName>/documentation to the path /<ArchiveName>/documentation/ // Rule #2: 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 #3: Redirects the URI path /<ArchiveName>/tutorials to the path /<ArchiveName>/tutorials/
return redirectURI( return redirectURI(
String(format: .Format.Path.forwardSlash, uriPath), String(format: .Format.Path.forwardSlash, uriPath),
with: (request, context) with: (request, context)
Tests/HummingbirdDocC/Tests/Public/Middlewares/DocCMiddlewareTests.swift
+29 -27
View File
@@ -296,16 +296,12 @@ private extension DocCMiddlewareTests {
) { ) {
// GIVEN // GIVEN
// WHEN // WHEN
let middleware = DocCMiddleware( let middleware = DocCMiddleware<RequestContextMock, LocalFileSystem>(
configuration: configuration, configuration: configuration,
logger: logger logger: logger
) )
// THEN // 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.label == logger.label)
#expect(middleware.logger.logLevel == logger.logLevel) #expect(middleware.logger.logLevel == logger.logLevel)
#expect(middleware.logger.metadataProvider == nil) #expect(middleware.logger.metadataProvider == nil)
@@ -325,17 +321,13 @@ private extension DocCMiddlewareTests {
) { ) {
// GIVEN // GIVEN
// WHEN // WHEN
let middleware = DocCMiddleware( let middleware = DocCMiddleware<RequestContextMock, FileSystemProvider>(
configuration: configuration, configuration: configuration,
fileProvider: fileProvider, fileProvider: fileProvider,
logger: logger logger: logger
) )
// THEN // 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.label == logger.label)
#expect(middleware.logger.logLevel == logger.logLevel) #expect(middleware.logger.logLevel == logger.logLevel)
#expect(middleware.logger.metadataProvider == nil) #expect(middleware.logger.metadataProvider == nil)
@@ -363,13 +355,13 @@ private extension DocCMiddlewareTests {
handler: logHandler handler: logHandler
) )
let context: any RequestContext = RequestContextMock(logger: logger) let context: RequestContextMock = .init(logger: logger)
let request: Request = .test( let request: Request = .test(
method: .get, method: .get,
path: uriPath path: uriPath
) )
let middleware = DocCMiddleware( let middleware = DocCMiddleware<RequestContextMock, FileProviderMock>(
configuration: .init( configuration: .init(
uriRoot: .Sample.uriRoot, uriRoot: .Sample.uriRoot,
folderRoot: .Sample.uriFolder folderRoot: .Sample.uriFolder
@@ -455,7 +447,7 @@ private extension DocCMiddlewareTests {
path: uriPath path: uriPath
) )
let middleware = DocCMiddleware( let middleware = DocCMiddleware<RequestContextMock, FileProviderMock>(
configuration: .init( configuration: .init(
uriRoot: .Sample.uriRoot, uriRoot: .Sample.uriRoot,
folderRoot: .Sample.uriFolder folderRoot: .Sample.uriFolder
@@ -476,7 +468,7 @@ private extension DocCMiddlewareTests {
.contentLength: (statusCode == .ok ? "36" : "0") .contentLength: (statusCode == .ok ? "36" : "0")
]) ])
let contentLength = #require(result.body.contentLength) let contentLength = try #require(result.body.contentLength)
if statusCode == .ok { if statusCode == .ok {
#expect(contentLength > 0) #expect(contentLength > 0)
@@ -553,7 +545,12 @@ private extension DocCMiddlewareTests {
private extension Input { private extension Input {
/// A list of relative URI paths to match against the URI path redirections done by the middleware. /// 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. /// A list of relative URI paths to match against the URI path servings done by the middleware.
static let serveURIPaths: [String] = [ static let serveURIPaths: [String] = [
"/documentation/", "/documentation/",
@@ -575,22 +572,27 @@ private extension Input {
private extension Output { private extension Output {
/// A list of expected relative URI path redirections outputs coming out of the URI path redirections done by the middleware. /// 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. /// 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] = [ static let serveURIFilePaths: [String] = [
"/SomeDocument.doccarchive/documentation/somedocument/index.html", "/SomeDocument.doccarchive/documentation/somedocument/index.html",
"/SomeDocument.doccarchive/tutorials/somedocument/index.html", "/SomeDocument.doccarchive/tutorials/somedocument/index.html",
"/SomeDocument.doccarchive/data/documentation/somedocument.json", "/SomeDocument.doccarchive/data/documentation/somedocument.json",
"/SomeDocument.doccarchive/SomeDocument/favicon.ico", "/SomeDocument.doccarchive/favicon.ico",
"/SomeDocument.doccarchive/SomeDocument/favicon.svg", "/SomeDocument.doccarchive/favicon.svg",
"/SomeDocument.doccarchive/SomeDocument/theme-settings.json", "/SomeDocument.doccarchive/theme-settings.json",
"/SomeDocument.doccarchive/SomeDocument/css/file.css", "/SomeDocument.doccarchive/css/file.css",
"/SomeDocument.doccarchive/SomeDocument/data/data.bin", "/SomeDocument.doccarchive/data/data.bin",
"/SomeDocument.doccarchive/SomeDocument/downloads/file.txt", "/SomeDocument.doccarchive/downloads/file.txt",
"/SomeDocument.doccarchive/SomeDocument/images/image.png", "/SomeDocument.doccarchive/images/image.png",
"/SomeDocument.doccarchive/SomeDocument/img/image.jpg", "/SomeDocument.doccarchive/img/image.jpg",
"/SomeDocument.doccarchive/SomeDocument/index/file", "/SomeDocument.doccarchive/index/file",
"/SomeDocument.doccarchive/SomeDocument/js/file.js", "/SomeDocument.doccarchive/js/file.js",
"/SomeDocument.doccarchive/SomeDocument/videos/video.mp4" "/SomeDocument.doccarchive/videos/video.mp4"
] ]
} }