Add a recommendations document by Joannis · Pull Request #98 · hummingbird-project/hummingbird-docs

Joannis · 2025-08-31T10:55:22Z

We should expand this later to include databases (Valkey, Postgres) and Deployment. Though those can very well be separate guides

Hummingbird.docc/Articles/Recommendations.md

thoven87 · 2025-08-31T14:03:34Z

Hummingbird.docc/Articles/Recommendations.md

+    public init() {}
+
+    public func handle(_ request: Request, context: Context, next: (Request, Context) async throws -> Response) async throws -> Response {
+        guard context.identity != nil else {


This can be simplified to try context.requireIndentity()

In this example I'm not interested in the value behind the user's identity, just if they're authenticated. Should I add a comment for that?

thoven87 · 2025-08-31T14:06:14Z

Hummingbird.docc/Articles/Recommendations.md

+```swift
+protocol RateLimitedRequestContext {
+    var rateLimitStatus: RateLimitStatus { get }
+    var ipAddress: String { get }


Should we elaborate a little more here because using the NIO channel to extract the ip address will not wield the desired data (ie a user's ip if the service is behind and load balancer or proxy.

I guess so, though this was really intended as a reference of what RequestContext could potentially be used for, not a full example. Should I clarify the intent here more?

@thoven87 I'm not sure getting into details about how to retrieve ip addresses is needed here

@thoven87 I'm not sure getting into details about how to retrieve ip addresses is needed here

Understood, I think this should be documented somewhere though.

Hummingbird.docc/Articles/Recommendations.md

adam-fowler

Some initial comments

adam-fowler · 2025-09-01T09:42:23Z

Hummingbird.docc/Articles/Recommendations.md

@@ -0,0 +1,342 @@
+## Dependencies


We need a top level heading for the documentation to link correctly eg Recommendations, a byline and an overview

We should then have some general text saying something of the sort

# Development Guidelines Recommendations for building applications with Hummingbird The Hummingbird web framework has been designed to be as flexible as possible. We try to impose as little structure on how it should be used. But some people like structure. This document provides some direction on how you can organise and implement good practices when developing your Hummingbird application.

adam-fowler · 2025-09-01T09:59:00Z

Hummingbird.docc/Articles/Recommendations.md

+
+## Project Structure
+
+The project structure is a recommended project layout, defining what modules are recommended to create and how these modules are structured in terms of folders and files.


Mention the template providing a degree of initial structure

Hummingbird.docc/Articles/Recommendations.md

adam-fowler · 2025-09-01T10:10:43Z

Hummingbird.docc/Articles/Recommendations.md

+
+### Handling Bodies
+
+If you're using standard libraries like Foundation's `JSONDecoder`, limit the body size to "reasonable" sizes. What is considered reasonable depends per application, but lower is generally better.


A lot of this is covered in the router documentation.
Recommendations about not collecting response in middleware, setting realistic limits when collecting into a single buffer, although preferring to stick to streamed version if possible.

I'll make things a little more bullet-pointy here

adam-fowler · 2025-09-01T10:15:10Z

Hummingbird.docc/Articles/Recommendations.md

+}
+```
+
+### Child Request Contexts


What are actual guidelines here?

Oops, forgot to add that bit

Hummingbird.docc/Articles/Recommendations.md

Co-authored-by: Moritz Lang <16192401+slashmo@users.noreply.github.com>

…t a bit more

zunda-pixel · 2025-09-07T10:58:44Z

Hummingbird.docc/Articles/Recommendations.md

+- [IkigaJSON](https://github.com/orlandos-nl/ikigajson) supports streaming JSON lines or JSON arrays.
+- [Server Sent Events](https://github.com/orlandos-nl/ssekit) supports streaming Server Sent Events.
+- [Swift-WebSocket](https://github.com/hummingbird-project/swift-websocket) and [Hummingbird-WebSocket](https://github.com/hummingbird-project/hummingbird-websocket) support streaming over WebSocket connections.
+- [PostgreNIO](https://github.com/vapor/posrtgresnio), [Valkey-Swift](https://github.com/valkey-io/valkey-swift) and [MongoKitten](https://github.com/orlandos-nl/mongokitten) all support streaming in their database operations.


correct link: https://github.com/vapor/postgres-nio

adam-fowler

Some more comments. I'm going to add a few additions to the docs based off what this PR has revealed is missing

Hummingbird.docc/Articles/Recommendations.md

adam-fowler · 2025-09-13T09:14:07Z

Hummingbird.docc/Articles/Recommendations.md

@@ -0,0 +1,392 @@
+# Tips for Building Hummingbird Apps
+
+When you start a new app, especially with a new framework, you will find many useful tips and tools. Here are lessons we learned from building Hummingbird and from our community. Please send us feedback or suggestions for this document anytime!


This feels too informal. Prefer something like

Hummingbird was built to be flexible as possible, so you can use it as you feel is suitable. This document though provides some recommendations on how to structure a Hummingbird app. Many of these come from lessons we learned while building applications using Hummingbird and from the experience of our community.

adam-fowler · 2025-09-13T09:15:22Z

Hummingbird.docc/Articles/Recommendations.md

+
+When you start a new app, especially with a new framework, you will find many useful tips and tools. Here are lessons we learned from building Hummingbird and from our community. Please send us feedback or suggestions for this document anytime!
+
+## Dependencies


I assume by dependencies you mean things like Postgres, redis/valkey etc if so I think this should be part of a different article. I feel this should concentrate on how to structure applications

adam-fowler · 2025-09-13T09:19:06Z

Hummingbird.docc/Articles/Recommendations.md

+}
+```
+
+Controllers can specify dependencies on services they need, like a database connection. To do so, add these properties on the controller:


Can we get a subheading here, something like

Dependencies

adam-fowler · 2025-09-13T09:20:30Z

Hummingbird.docc/Articles/Recommendations.md

+```
+
+
+If a route needs something special, like authentication, use _protocol composition_ to refine the RequestContext.


Mention hummingbird-auth here, as this provides a lot of the framework for being authenticated services

adam-fowler · 2025-09-13T09:30:02Z

Hummingbird.docc/Articles/Recommendations.md

+let router = Router(context: MyContext.self)
+router.add("users", routes: UserController().routes)
+```
+


Add a link to the general documentation here <doc:RouterGuide>

adam-fowler · 2025-09-13T09:31:18Z

Hummingbird.docc/Articles/Recommendations.md

+        return try await next(request, context)
+    }
+}
+```


Add a link to general documentation <doc:MiddlewareGuide>

adam-fowler · 2025-09-13T09:35:37Z

Hummingbird.docc/Articles/Recommendations.md

+- Avoid collecting the data into a single buffer, whenever possible. Use streaming APIs instead.
+- Try to move the CPU and RAM intensive work of providing the correct format to the client if possible.
+    - This means your API only needs to validate the data before processing/saving.
+- Use libraries that support streaming data if your dataset is large.


Add

Use your RequestContext to define an in-memory size when decoding requests. I was going to say add a link to the relevant docs, but apparently we only have reference documentation for that

adam-fowler · 2025-09-13T09:35:58Z

Hummingbird.docc/Articles/Recommendations.md

+    - This means your API only needs to validate the data before processing/saving.
+- Use libraries that support streaming data if your dataset is large.
+
+Some libraries that play well into this:


This should be in a separate document

adam-fowler · 2025-09-13T09:37:08Z

Hummingbird.docc/Articles/Recommendations.md

+- [Swift-WebSocket](https://github.com/hummingbird-project/swift-websocket) and [Hummingbird-WebSocket](https://github.com/hummingbird-project/hummingbird-websocket) support streaming over WebSocket connections.
+- [PostgreNIO](https://github.com/vapor/posrtgresnio), [Valkey-Swift](https://github.com/valkey-io/valkey-swift) and [MongoKitten](https://github.com/orlandos-nl/mongokitten) all support streaming in their database operations.
+
+You can handle the request and response bodies as an `AsyncSequence`.


This is repeating what is already in the documentation https://docs.hummingbird.codes/2.0/documentation/hummingbird/routerguide#Request-Body

Co-authored-by: Adam Fowler <adamfowler71@gmail.com>

Add a recommendations document

2742d15

Joannis requested a review from adam-fowler August 31, 2025 10:55

Joannis force-pushed the jo/hummingbird-recommendations branch from 3288be8 to 2742d15 Compare August 31, 2025 10:55

thoven87 reviewed Aug 31, 2025

View reviewed changes

Fix a remnant of a past life (Abort -> HTTPError)

a019b83

slashmo reviewed Aug 31, 2025

View reviewed changes

Hummingbird.docc/Articles/Recommendations.md Outdated Show resolved Hide resolved

adam-fowler reviewed Sep 1, 2025

View reviewed changes

Joannis and others added 4 commits September 2, 2025 13:35

Update Hummingbird.docc/Articles/Recommendations.md

28cf771

Co-authored-by: Moritz Lang <16192401+slashmo@users.noreply.github.com>

Update recommendations to add ChildRequestContext and clarify the tex…

5478b80

…t a bit more

Fix spelling issues

86ee6eb

Update the text to be authorative

e0591a6

zunda-pixel reviewed Sep 7, 2025

View reviewed changes

adam-fowler reviewed Sep 13, 2025

View reviewed changes

Update Hummingbird.docc/Articles/Recommendations.md

7027557

Co-authored-by: Adam Fowler <adamfowler71@gmail.com>


		## Project Structure

		The project structure is a recommended project layout, defining what modules are recommended to create and how these modules are structured in terms of folders and files.


		### Handling Bodies

		If you're using standard libraries like Foundation's `JSONDecoder`, limit the body size to "reasonable" sizes. What is considered reasonable depends per application, but lower is generally better.

		@@ -0,0 +1,392 @@
		# Tips for Building Hummingbird Apps

		When you start a new app, especially with a new framework, you will find many useful tips and tools. Here are lessons we learned from building Hummingbird and from our community. Please send us feedback or suggestions for this document anytime!


		When you start a new app, especially with a new framework, you will find many useful tips and tools. Here are lessons we learned from building Hummingbird and from our community. Please send us feedback or suggestions for this document anytime!

		## Dependencies

		```


		If a route needs something special, like authentication, use _protocol composition_ to refine the RequestContext.

Conversation

Joannis commented Aug 31, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Joannis Aug 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adam-fowler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adam-fowler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Dependencies

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Joannis Aug 31, 2025 •

edited

Loading