From 5e0312c3ca85549f4214eef7a78d80c6dd07b7a0 Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Sun, 19 Nov 2023 14:41:20 +0000 Subject: [PATCH 1/2] Update README and comments --- README.md | 23 ++++++++++---------- Sources/Hummingbird/Application.swift | 16 ++++++-------- Sources/HummingbirdXCT/Application+XCT.swift | 9 ++++---- 3 files changed, 23 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7b4a855ec..bafeb281b 100644 --- a/README.md +++ b/README.md @@ -14,33 +14,32 @@

-Lightweight, flexible server framework written in Swift. - -Hummingbird consists of three main components, the core HTTP server, a minimal web application framework and the extension modules. +Lightweight, flexible, modern server framework written in Swift. ## HummingbirdCore -HummingbirdCore contains a Swift NIO based HTTP server. You will find the code for it in the [hummingbird-core](https://github.com/hummingbird-project/hummingbird-core) repository. The HTTP server is initialized with a object conforming to protocol `HBHTTPResponder` which defines how your server responds to an HTTP request. The HTTP server can be extended to support TLS and HTTP2 via the `HummingbirdTLS` and `HummingbirdHTTP2` libraries also available in the hummingbird-core repository. +HummingbirdCore contains a Swift NIO based server framework. The server framework `HBServer` can be used to support many protocols but is primarily designed to support HTTP. By default it is setup to be an HTTP/1.1 server, but it can support TLS and HTTP2 via the `HummingbirdTLS` and `HummingbirdHTTP2` libraries. HummingbirdCore can be used separately from Hummingbird if you want to write your own web application framework. ## Hummingbird -Hummingbird is a lightweight and flexible web application framework that runs on top of HummingbirdCore. It is designed to require the minimum number of dependencies: `swift-backtrace`, `swift-log`, `swift-nio`, `swift-nio-extras`, `swift-service-lifecycle` and `swift-metrics` and makes no use of Foundation. - -It provides a router for directing different endpoints to their handlers, middleware for processing requests before they reach your handlers and processing the responses returned, support for adding channel handlers to extend the HTTP server, extending the core `HBApplication`, `HBRequest` and `HBResponse` classes and providing custom encoding/decoding of `Codable` objects. +Hummingbird is a lightweight and flexible web application framework that runs on top of HummingbirdCore. It is designed to require the minimum number of dependencies and makes no use of Foundation. -The interface is fairly standard. Anyone who has had experience of Vapor, Express.js etc will recognise most of the APIs. Simple setup is as follows +It provides a router for directing different endpoints to their handlers, middleware for processing requests before they reach your handlers and processing the responses returned, support for adding channel handlers to extend the HTTP server and providing custom encoding/decoding of `Codable` objects. ```swift import Hummingbird -let app = HBApplication(configuration: .init(address: .hostname("127.0.0.1", port: 8080))) -app.router.get("hello") { request -> String in +let router = HBRouterBuilder() +router.get("hello") { request -> String in return "Hello" } -try app.start() -app.wait() +let app = HBApplication( + responder: router.buildResponder(), + configuration: .init(address: .hostname("127.0.0.1", port: 8080)) +) +try await app.runService() ``` ## Hummingbird Extensions diff --git a/Sources/Hummingbird/Application.swift b/Sources/Hummingbird/Application.swift index f2c73622f..c41e450c3 100644 --- a/Sources/Hummingbird/Application.swift +++ b/Sources/Hummingbird/Application.swift @@ -71,20 +71,18 @@ public final class HBApplicationContext: Sendable { } } -/// Application builder class. Brings together all the components of Hummingbird together +/// Application class. Brings together all the components of Hummingbird together /// -/// Setup an HBApplicationBuilder, setup your application middleware, encoders, routes etc and then either -/// add call `build` to create an `HBApplication` which you add to your ServiceLifecycle `ServiceGroup` or -/// run separately with `buildAndRun`. /// ``` -/// let app = HBApplicationBuilder() -/// app.middleware.add(MyMiddleware()) -/// app.router.get("hello") { _ in +/// let router = HBRouterBuilder() +/// router.middleware.add(MyMiddleware()) +/// router.get("hello") { _ in /// return "hello" /// } -/// try await app.buildAndRun() +/// let app = HBApplication(responder: router.buildResponder()) +/// try await app.runService() /// ``` -/// Editing the application builder setup after calling `build` will produce undefined behaviour. +/// Editing the application setup after calling `runService` will produce undefined behaviour. public struct HBApplication { // MARK: Member variables diff --git a/Sources/HummingbirdXCT/Application+XCT.swift b/Sources/HummingbirdXCT/Application+XCT.swift index c07088d5c..33a04d956 100644 --- a/Sources/HummingbirdXCT/Application+XCT.swift +++ b/Sources/HummingbirdXCT/Application+XCT.swift @@ -28,7 +28,7 @@ public enum XCTRouterTestingSetup { case router } -/// Extends `HBApplicationBuilder` to support testing of applications +/// Extends `HBApplicationB` to support testing of applications /// /// You use `buildAndTest` and `XCTExecute` to test applications. You can either create an /// `.router` application which send request directly to the router for testing your code or a @@ -37,11 +37,12 @@ public enum XCTRouterTestingSetup { /// /// The example below is using the `.router` framework to test /// ``` -/// let app = HBApplicationBuilder() -/// app.router.get("/hello") { _ in +/// let router = HBRouterBuilder() +/// router.get("/hello") { _ in /// return "hello" /// } -/// app.buildAndTest(.router) { client in +/// let app = HBApplication(responder: router.buildResponder()) +/// app.test(.router) { client in /// // does my app return "hello" in the body for this route /// client.XCTExecute(uri: "/hello", method: .GET) { response in /// let body = try XCTUnwrap(response.body) From 802ed3ff6263e42154a7998c520749a3d3302a35 Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Mon, 20 Nov 2023 11:53:24 +0000 Subject: [PATCH 2/2] Updates from PR comments --- README.md | 2 +- Sources/HummingbirdXCT/Application+XCT.swift | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bafeb281b..adaee6f55 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Lightweight, flexible, modern server framework written in Swift. ## HummingbirdCore -HummingbirdCore contains a Swift NIO based server framework. The server framework `HBServer` can be used to support many protocols but is primarily designed to support HTTP. By default it is setup to be an HTTP/1.1 server, but it can support TLS and HTTP2 via the `HummingbirdTLS` and `HummingbirdHTTP2` libraries. +HummingbirdCore contains a Swift NIO based server framework. The server framework `HBServer` can be used to support many protocols but is primarily designed to support HTTP. By default it is setup to be an HTTP/1.1 server, but it can support TLS and HTTP2 via the `HummingbirdTLS` and `HummingbirdHTTP2` modules. HummingbirdCore can be used separately from Hummingbird if you want to write your own web application framework. diff --git a/Sources/HummingbirdXCT/Application+XCT.swift b/Sources/HummingbirdXCT/Application+XCT.swift index 33a04d956..b4e321fd1 100644 --- a/Sources/HummingbirdXCT/Application+XCT.swift +++ b/Sources/HummingbirdXCT/Application+XCT.swift @@ -28,7 +28,7 @@ public enum XCTRouterTestingSetup { case router } -/// Extends `HBApplicationB` to support testing of applications +/// Extends `HBApplication` to support testing of applications /// /// You use `buildAndTest` and `XCTExecute` to test applications. You can either create an /// `.router` application which send request directly to the router for testing your code or a