Hummingbird routing and requests – The.Swift.Dev.

Routing on the server aspect means the server goes to ship a response based mostly on the URL path that the consumer referred to as when firing up the HTTP request. After all the server can verify extra parameters and headers to construct the ultimate response, however once we speak about routing on the whole, we often discuss with the trail elements. Hummingbird makes use of a trie-based router, which is a quick and environment friendly manner of trying up routes. It is fairly easy to reply to HTTP request utilizing the built-in router, you may merely add your primary route handlers like this:

 
router.on("foo", technique: .HEAD) { _ -> HTTPResponseStatus in .okay }
router.on("foo", technique: .GET) { _ -> HTTPResponseStatus in .okay }
router.on("foo", technique: .POST) { _ -> HTTPResponseStatus in .okay }
router.on("foo", technique: .PUT) { _ -> HTTPResponseStatus in .okay }
router.on("foo", technique: .PATCH) { _ -> HTTPResponseStatus in .okay }
router.on("foo", technique: .DELETE) { _ -> HTTPResponseStatus in .okay }


router.head("foo") { _ -> HTTPResponseStatus in .okay }
router.get("foo") { _ -> HTTPResponseStatus in .okay }
router.put("foo") { _ -> HTTPResponseStatus in .okay }
router.put up("foo") { _ -> HTTPResponseStatus in .okay }
router.patch("foo") { _ -> HTTPResponseStatus in .okay }
router.delete("foo") { _ -> HTTPResponseStatus in .okay }

In Hummingbird it’s also doable to register use a perform as a substitute of a block. Handler features might be async and throwing too, so you may mark the blocks with these key phrases or use asynchronous Swift features when registering route handlers. When you do not present the primary parameter, the trail as a string, the route handler goes to be hooked up to the bottom group. ?

You may as well prefix a path part with a colon, this may flip that part right into a dynamic route parameter. The parameter goes to be named after the trail part, by merely dropping the colon prefix. You’ll be able to entry parameters inside your route handler by the req.parameters property. It’s also doable to register a number of elements utilizing a / character.

public extension HBApplication {
    
    func configure() throws {

        router.get { _ async throws in "Hiya, world!" }

        router.get("good day/:title") { req throws in
            guard let title = req.parameters.get("title") else {
                throw HBHTTPError(
                    .badRequest,
                    message: "Invalid title parameter."
                )
            }
            return "Hiya, (title)!"
        }

        let group = router.group("todos")
        group.get(use: record)
        group.put up(use: create)
        
        let idGroup = group.group(":todoId")
        idGroup.head(use: verify)
        idGroup.get(use: fetch)
        idGroup.put(use: replace)
        idGroup.patch(use: patch)
        idGroup.delete(use: delete)

        
        router.group("todos")
            .get(use: record)
            .put up(use: create)
            .group(":todoId")
                .head(use: verify)
                .get(use: fetch)
                .put(use: replace)
                .patch(use: patch)
                .delete(use: delete)

    }

    func record(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func verify(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func fetch(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func create(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func replace(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func patch(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
    func delete(_ req: HBRequest) async throws -> HTTPResponseStatus { .okay }
}

It’s doable to make use of a wildcard character () when detecting path elements and the recursive model (*) to catch every thing. Additionally you should utilize the ${title} syntax to catch a named request parameter even with a prefix or suffix, however you may’t insert this in the course of a path part. (e.g. “prefix-${title}.jpg” will not work, however “${title}.jpg” is simply superb) ?

import Hummingbird
import HummingbirdFoundation

extension HBApplication {

    func configure(_ args: AppArguments) throws {

        router.get("foo-${title}", use: catchPrefix)
        router.get("${title}.jpg", use: catchSuffix)
        
        router.get("*", use: catchOne)
        router.get("*/*", use: catchTwo)

        router.get("**", use: catchAll)
        
    }
    
    
    func catchOne(_ req: HBRequest) async throws -> String {
        "one"
    }

    
    func catchTwo(_ req: HBRequest) async throws -> String {
        "two"
    }
    
    
    func catchAll(_ req: HBRequest) async throws -> String {
        "all: " + req.parameters.getCatchAll().joined(separator: ", ")
    }
    
    
    func catchPrefix(_ req: HBRequest) async throws -> String {
        "prefix: " + (req.parameters.get("title") ?? "n/a")
    }
    
    
    func catchSuffix(_ req: HBRequest) async throws -> String {
        "suffix: " + (req.parameters.get("title") ?? "n/a")
    }
}

It’s also doable to edit the auto-generated response should you specify the .editResponse choice.

router.get("foo", choices: .editResponse) { req -> String in
    req.response.standing = .okay
    req.response.headers.replaceOrAdd(
        title: "Content material-Kind", 
        worth: "utility/json"
    )
    return #"{"foo": "bar"}"#
}

Hummingbird help for physique streaming is wonderful, you may stream a HTTP request physique by utilizing the .streamBody choice. The physique stream has a sequence property, which you should utilize to iterate by the incoming ByteBuffer chunks when dealing with the request. ?

func configure() throws { 
    router.put up("foo", choices: .streamBody) { req async throws -> String in
        guard
            let rawLength = req.headers["Content-Length"].first,
            let size = Int(rawLength),
            let stream = req.physique.stream
        else {
            throw HBHTTPError(
                .badRequest,
                message: "Lacking or invalid physique stream."
            )
        }
        var depend: Int = 0
        for attempt await chunk in stream.sequence {
            depend += chunk.readableBytes
        }
        return String("(size) / (depend)")
    }
}


let app = HBApplication(
    configuration: .init(
        handle: .hostname(hostname, port: port),
        serverName: "Hummingbird",
        maxUploadSize: 1 * 1024 * 1024 * 1024 
    )
)

As you may see you may simply entry all of the incoming headers by way of the req.headers container, it’s best to observe that this technique will return header values in a case-insensitive manner. If you wish to stream bigger information, you additionally need to set a customized maxUploadSize utilizing the configuration object when initializing the HBApplication occasion.

curl -X POST http://localhost:8080/foo 
    -H "Content material-Size: 3" 
    --data-raw 'foo'

curl -X POST http://localhost:8080/foo 
    -H "content-Size: 5242880" 
    -T ~/take a look at

You’ll be able to check out streaming with a easy cURL script, be happy to experiment with these.

One other factor I would like to point out you is tips on how to entry question parameters and different properties utilizing the request object. Right here is an all-in-one instance, which you should utilize as a cheatsheet… ?

router.get("bar") { req async throws -> String in
            
    struct Foo: Codable {
        var a: String
    }

    print(req.technique)
    print(req.headers)
    print(req.headers["accept"])
    print(req.uri.queryParameters.get("q") ?? "n/a")
    print(req.uri.queryParameters.get("key", as: Int.self) ?? 0)

    if let buffer = req.physique.buffer {
        let foo = attempt? JSONDecoder().decode(Foo.self, from: buffer)
        print(foo ?? "n/a")
    }
    return "Hiya, world!"
}

Anyway, there may be one extra tremendous cool function in Hummingbird that I would like to point out you. It’s doable to outline a route handler, this fashion you may encapsulate every thing right into a single object. There may be an async model of the route handler protocol, should you do not want async, you may merely drop the key phrase each from the protocol title & the tactic. I like this method loads. ?

struct MyRouteHandler: HBAsyncRouteHandler {

    struct Enter: Decodable {
        let foo: String
    }

    struct Output: HBResponseEncodable {
        let id: String
        let foo: String
    }
    
    let enter: Enter

    init(from request: HBRequest) throws {
        self.enter = attempt request.decode(as: Enter.self)
    }

    func deal with(request: HBRequest) async throws -> Output {
        .init(
            id: "id-1",
            foo: enter.foo
        )
    }
}

The request.decode technique makes use of the built-in decoder, which you must explicitly set for the applying, since we’ll talk utilizing JSON knowledge, we are able to use the JSON encoder / decoder from Basis to mechanically remodel the information.

To be able to make use of the customized route handler, you may merely register the thing kind.

import Hummingbird
import HummingbirdFoundation

public extension HBApplication {

    func configure() throws {
        
        encoder = JSONEncoder()
        decoder = JSONDecoder()
                
        
        router.put up("foo", use: MyRouteHandler.self)
    }
}

You’ll be able to learn extra about how the encoding and decoding works in Hummingbird, however possibly that subject deserves its personal weblog put up. When you have questions or recommendations, be happy to contact me. ?