hummingbird-project/hummingbird

This system is the Hummingbird framework, a high-performance HTTP server and web application toolkit for Swift. It provides a complete stack for building network services, featuring a modern router with trie-based path matching, middleware for security and observability, and robust support for JSON and form data serialization. The framework handles low-level HTTP/1.1 and HTTP/2 protocols with TLS encryption, while offering utilities for persistent storage, file serving, and comprehensive testing across live and in-process environments.

19 changes.

This period focused on the comprehensive rewrite of the Hummingbird framework for version 2.0, introducing a new application architecture, router, and server-side request handling model. The work included migrating to Swift 6.2, adding support for HTTP/2 and TLS, and implementing new middleware for security and observability. Extensive test coverage and utility scripts were added to support the new modular structure and CI workflows.

17 changes.

This period focused on a comprehensive rewrite of the Hummingbird framework, introducing a new NIOAsyncChannel-based server architecture with robust connection management and streaming support. The update replaced the router with a high-performance trie-based implementation and modernized the API with result builders, extensible middleware, and native JSON and form data handling. These changes were accompanied by a new testing module and performance benchmarks to ensure stability and efficiency.

The Hummingbird framework now includes built-in support for JSON serialization via new extensions on JSONEncoder and JSONDecoder. JSONEncoder implements the ResponseEncoder protocol, allowing encodable values to be automatically converted into HTTP responses with appropriate JSON content-type headers. JSONDecoder implements the RequestDecoder protocol, enabling the decoding of incoming request bodies into typed Swift objects, respecting configured upload size limits.

Sources/Hummingbird/Codable/JSON · high confidence

New benchmark suites have been added to measure the performance of the Hummingbird framework, including HTTP URI decoding, cookie parsing, router handling (GET, PUT, POST, case-insensitive routing), trie-based routing, and URL-encoded form encoding/decoding. These benchmarks are available for macOS 14 and later and provide metrics on CPU usage, instructions, and memory allocation to help track performance regressions or improvements.

Benchmarks · high confidence

A new executable target, Sources/PerformanceTest, has been added to provide a benchmarking harness for the Hummingbird server framework. This tool configures an HTTP server with specific endpoints (plain text, JSON, and a simulated wait) and utilizes NIO's MultiThreadedEventLoopGroup to facilitate performance testing via tools like wrk. The implementation is gated by a version check for Hummingbird 2.0, ensuring it only runs on compatible environments (macOS 14, iOS 17, or tvOS 17).

Sources/PerformanceTest · high confidence

The HummingbirdHTTP2 module now provides full HTTP/2 capabilities, allowing servers to handle both HTTP/1.1 with ALPN upgrade to HTTP/2 and dedicated plaintext HTTP/2 connections. This is achieved through the new \HTTP2UpgradeChannel\ for TLS-based negotiation and \HTTP2Channel\ for direct HTTP/2 streams, both configurable via \HTTP2ChannelConfiguration\ (exposed via \HTTPServerBuilder.http2Upgrade\ and \HTTPServerBuilder.plaintextHTTP2\). The implementation includes a robust connection state machine for managing idle timeouts, graceful shutdowns, and ping/pong frames, alongside a \ConfigReader\ initializer for loading TLS and HTTP/2 settings from configuration files.

Sources/HummingbirdHTTP2 · high confidence

The \HummingbirdTesting\ module (renamed from \HummingbirdXCT\) is now available for Hummingbird 2.0, providing three distinct testing strategies via \TestingSetup\: \.router\ for fast, in-process request handling without a live server; \.live\ for testing against a real server using a single-connection HTTP client; and \.ahc\ for testing with the full AsyncHTTPClient library. The module introduces \TestClientProtocol\ and \TestResponse\ types, and includes deprecation aliases for the old \HBXCT\-prefixed symbols to ease migration.

Sources/HummingbirdTesting · high confidence

This change adds a new storage subsystem for maintaining persistent key/value pairs across requests. It introduces the \PersistDriver\ protocol, which defines operations for creating, setting, getting, and removing values, including support for time-to-live (TTL) expiration via \getWithTTL\. A concrete \MemoryPersistDriver\ implementation is provided, utilizing a configurable tidy frequency to automatically clean up expired entries. The system also defines \PersistError\ to handle specific failure cases such as duplicate keys or invalid type conversions.

Sources/Hummingbird/Storage · high confidence

The Hummingbird framework now provides a dedicated Codable module that defines \ResponseEncoder\ and \RequestDecoder\ protocols, enabling structured serialization of HTTP responses and deserialization of request bodies. This change adds conformances for \ResponseEncodable\ and \ResponseCodable\, allowing Swift types that conform to \Encodable\ or \Decodable\ to be automatically handled by the router, and extends standard collections like \Array\ and \Dictionary\ to support these protocols for seamless integration with the application's encoder and decoder instances.

Sources/Hummingbird/Codable · high confidence

Added a suite of shell scripts to support the project's build and validation workflows: \validate.sh\ checks Swift code formatting and license headers; \generate-certs.sh\ creates test TLS certificates and Swift source files for \HummingbirdCoreTests\ and \HummingbirdHTTP2Tests\; \generate-contributors-list.sh\ updates the \CONTRIBUTORS.txt\ file by aggregating authors from multiple Hummingbird repositories; \test-builds.sh\ verifies that dependent packages (auth, fluent, lambda, redis) compile against the current codebase; and \verify-foundation.sh\ ensures that specific products do not depend on Foundation or ICU dynamic libraries when built without traits.

scripts · high confidence

The framework introduces the \HTTPResponseError\ protocol, allowing custom errors to define their own HTTP status codes and headers for client responses. It includes a default \HTTPError\ struct for standard error reporting and an \EditedHTTPError\ wrapper to append additional headers to existing errors. Additionally, \NIOTooManyBytesError\ now automatically maps to a 413 Payload Too Large response.

Sources/Hummingbird/Error · high confidence

The middleware module now includes CORSMiddleware for configuring Cross-Origin Resource Sharing headers (including support for multiple allowed origins via AllowOriginExtended), ContentSecurityMiddleware for setting Content-Security-Policy and related security headers, and TracingMiddleware for creating distributed tracing spans with configurable header recording and query parameter redaction. Existing middleware has also been updated: LogRequestsMiddleware now supports filtering which headers are logged and redacting sensitive ones, and MetricsMiddleware includes a cache to optimize metric lookups.

Sources/Hummingbird/Middleware · high confidence

The HummingbirdCore utilities module now includes several new types to support framework internals and improve string handling. A new \AnyAsyncSequence\ wrapper allows boxing async sequences while preserving Sendability, supported by a \SendableMetatype\ typealias that adapts to Swift 6.2+ requirements. A \FlatDictionary\ provides a collection type optimized for small datasets that supports duplicate keys, and an \UnsafeTransfer\ wrapper enables non-Sendable values to be treated as Sendable. Additionally, \String\ extensions for percent encoding and decoding have been added, along with an \OutputBuffer\ for low-level memory management and an internal \Parser\ for UTF-8 buffer processing.

Sources/HummingbirdCore/Utils · high confidence

The Hummingbird Utils module introduces several new capabilities: a \DateCache\ service that maintains an RFC 9110-compliant HTTP date string updated every second for efficient header generation; custom \SplitStringSequence\ and \SplitStringMaxSplitsSequence\ types for optimized string splitting; a \PreludeService\ wrapper to run setup logic before a service starts; and an \InitializableFromSource\ protocol for flexible initialization patterns.

Sources/Hummingbird/Utils · high confidence

The repository has been initialized with the core project structure, including the Apache 2.0 license, a Dockerfile for building and testing, and configuration files for Swift formatting and editor standards. Essential community documentation has been added, such as a Code of Conduct, Contributing guidelines, and an AI Policy for contributors. The README has been updated to provide a comprehensive overview of the Hummingbird framework, including installation instructions, usage examples, and links to official extensions and documentation.

(repo-wide) · high confidence

The middleware builder now supports \if\-\else\ and \for\-\in\ syntax, allowing users to conditionally include middleware or compose middleware from arrays directly within the builder block. This is enabled by new internal types (\\_OptionalMiddleware\, \\_SpreadMiddleware\) and result builder methods that handle optional and array-based middleware components.

Sources/Hummingbird/Middleware/MiddlewareModule · high confidence

The HummingbirdTLS module now provides a builder-based API for creating HTTP servers with TLS. Developers can use HTTPServerBuilder.tls() to wrap a base HTTP channel (such as HTTP/1.1) with TLS, passing either a direct TLSConfiguration or a TLSChannelConfiguration that supports a custom certificate verification callback. The module introduces TLSChannel to handle the TLS handshake and pipeline setup, and TLSChannelConfiguration to manage TLS settings and optional custom verification logic. Additionally, TLSChannelConfiguration can be initialized from a ConfigReader, allowing certificate chain, private key, and trust roots to be loaded from configuration sources.

Sources/HummingbirdTLS · high confidence

The URLEncodedForm module now provides direct integration with the Hummingbird request and response cycle. URLEncodedFormEncoder implements ResponseEncoder, allowing Codable values to be encoded into URL-encoded form bodies with appropriate headers, while URLEncodedFormDecoder implements RequestDecoder to parse incoming form data from request bodies. This enables seamless encoding and decoding of URL-encoded form data within Hummingbird handlers.

Sources/Hummingbird/Codable/URLEncodedForm · high confidence

The \Sources/test-framework/main.swift\ file has been deleted, removing the previous entry point that initialized an \Application\ and called \serve()\. This indicates the test framework's standalone executable or primary entry point is no longer present in this location.

Sources/test-framework · high confidence

The file-serving capabilities in Hummingbird now support more granular control over HTTP caching and performance. A new \CacheControl\ type replaces the previous fixed enum with an extensible \CacheControlValue\ that includes additional directives like \mustUnderstand\, \noTransform\, \immutable\, and custom values, allowing for more precise cache behavior. Additionally, the \FileIO\ module now allows users to configure the \chunkLength\ parameter for file reads (defaulting to 128 KB), enabling optimization of memory usage and transfer efficiency for large files.

Sources/Hummingbird/Files · high confidence

The HTTP/1 channel implementation has been refactored to expose detailed configuration options for the HTTP decoder and connection lifecycle. Users can now set specific limits for header field size, total header list size, and the maximum number of headers to control memory usage and prevent abuse. Additionally, an idle timeout can be configured to automatically close connections that remain inactive for a specified duration, improving resource management. These settings are applied via the new HTTP1Channel.Configuration struct during server initialization.

Sources/HummingbirdCore/Server/HTTP · high confidence

The framework has been upgraded to version 2.0, introducing a complete rewrite of the core application structure. The legacy \HB\-prefixed types (e.g., \HBApplication\, \HBRouter\) have been removed in favor of a new, cleaner API (e.g., \Application\, \Router\), with compatibility aliases marked as unavailable to force migration. The application lifecycle is now managed via the \ServiceLifecycle\ framework, replacing the previous custom \Lifecycle\ implementation, and the server is built using \HTTPServerBuilder\ instead of raw NIO \ServerBootstrap\. Configuration is now handled by a dedicated \ApplicationConfiguration\ struct and a new \ConfigReader\ initializer, supporting environment variables and \.env\ files via \NIOFileSystem\. The HTTP handler has been refactored to be non-throwing at the channel level, with error handling centralized in the application responder, and the server now supports binding to Unix domain sockets and configurable server names.

Sources/HummingBird · high confidence

The router has been rewritten for Hummingbird 2.0, introducing a new \RouterPath\ type that supports OpenAPI-style parameter syntax (e.g., \{id}\) alongside existing capture syntax (\:id\). This change brings automatic HEAD endpoint generation for GET routes, a \routes\ property to inspect registered paths, and a \validate()\ method to detect conflicting route definitions at startup. The update also adds helper methods to extract UUIDs from parameters, supports recursive wildcards (\\\\), and allows for case-insensitive path matching via \RouterOptions\.

Sources/Hummingbird/Router · high confidence

This change introduces the Hummingbird 2.0 server-side foundation, replacing the previous request handling model with a new, structured approach. It adds a new \RequestContext\ protocol and \BasicRequestContext\ implementation to manage request metadata (such as logger, endpoint path, and parameters) and decoupled encoder/decoder configuration. The \Request\ type gains new capabilities for conditional requests (ETag and date-based headers like \If-None-Match\, \If-Match\, \If-Modified-Since\, and \If-Unmodified-Since\) and body collection. Additionally, it provides a \ChildRequestContext\ protocol for creating nested request contexts, a \RequestID\ generator for unique request tracking, and an \HTTPResponder\ protocol to standardize how routes produce responses. The \Response\ type now includes a \redirect\ helper, and \URI\ gains a \decodeQuery\ method for parsing query parameters.

Sources/Hummingbird/Server · high confidence

The HummingbirdRouter module now provides a new v2 routing API built around Swift result builders. Users can define routes and route groups using the new \RouterBuilder\, \Route\, and \RouteGroup\ types, which support middleware chains and handler closures. This update introduces \ContextTransform\ and \ThrowingContextTransform\ middleware to allow route groups to operate with custom \RequestContext\ types, enabling better state management within nested routes. Additionally, the router now supports case-insensitive path matching via the \RouterBuilderOptions.caseInsensitive\ option, and symbols previously prefixed with "HB" (e.g., \HBRouterBuilder\) have been renamed to their unprefixed equivalents (e.g., \RouterBuilder\) to align with the framework's naming conventions.

Sources/HummingbirdRouter · high confidence

The HTTP module introduces a \ContentSecurityPolicy\ helper to construct Content-Security-Policy headers for mitigating XSS attacks, and a new \Cookie\ struct with strict RFC 6265 validation. Cookie creation now includes a \validated\ method that throws errors for invalid names or values, and asserts in debug builds when \SameSite=None\ is used without the \Secure\ attribute. The \SameSite.secure\ case is deprecated in favor of \SameSite.strict\. Additionally, \MediaType\ gains support for quoted parameter values and a \withParameter\ helper, while \FileExtension\ provides case-insensitive file extension mapping.

Sources/Hummingbird/HTTP · high confidence

The \Sources/HummingbirdCore/Response\ module introduces new \Response\ and \ResponseBody\ structs to manage HTTP responses. A key behavioral change is that setting the response body now automatically updates or clears the \Content-Length\ header if the new body's length differs from the existing one, ensuring header consistency without manual intervention. The \ResponseBody\ supports multiple backings (empty, single buffer, or async closures) and provides a \map\ function for transforming body content, while \ResponseWriter\ optimizes writing for non-streamed bodies by batching head, body, and end parts into a single operation.

Sources/HummingbirdCore/Response · high confidence

The request processing API in HummingbirdCore has been updated to support robust handling of long-running requests, such as Server-Sent Events. The \RequestBody\ type now exposes \consumeWithCancellationOnInboundClose\, which automatically cancels the provided operation if the underlying HTTP stream is closed by the client. This is implemented via a new \RequestBodyMergedWithUnderlyingRequestPartIterator\ that seamlessly transitions from the request body stream to the underlying HTTP parts stream, ensuring proper cleanup and preventing hangs on HTTP/2 streams or abrupt client disconnections.

Sources/HummingbirdCore/Request · high confidence

The router in the Hummingbird framework has been replaced with a new trie-based implementation located in Sources/Hummingbird/Router/Trie. This change introduces a Struct of Arrays data structure for improved allocation performance and path resolution speed. It also adds support for case-insensitive route matching via a new RouterOptions flag, allowing applications to match paths regardless of letter casing without requiring manual lowercasing of route definitions.

Sources/Hummingbird/Router/Trie · high confidence

The legacy Xcode workspace file (contents.xcworkspacedata) has been removed from the project. This file previously defined a workspace reference to the package itself, and its removal indicates a shift away from using this specific Xcode workspace structure for the Swift Package Manager setup.

.swiftpm · medium confidence

The server implementation has been rewritten to use NIOAsyncChannel, introducing a new \Server\ actor that manages lifecycle via \run()\ and \shutdownGracefully()\ instead of returning EventLoopFutures. This change brings a new \BindAddress\ struct that supports binding to NWEndpoint in addition to host/port and Unix domain sockets, and adds a \MaximumAvailableConnections\ delegate to \ServerConfiguration\ for limiting concurrent connections to prevent overload. The \HTTPUserEventHandler\ is now deprecated in favor of \HTTPConnectionStateHandler\, and the server now uses \withGracefulShutdownHandler\ for shutdown logic while ignoring transient \NIOFcntlFailedError\ to improve stability.

Sources/HummingbirdCore/Server · high confidence

Added HTTP/2 test suite with TLS certificates and configuration validation; Added comprehensive test suite for Hummingbird core components; Added test coverage for URLEncodedForm decoding, encoding, and integration; Added test coverage for the Hummingbird Router framework; Added test suite for HummingbirdCore; Removal of LinuxMain.swift test runner.

This change upgrades the Hummingbird framework to Swift 6.2, significantly updating core dependencies including swift-nio to 2.100.0, swift-service-lifecycle to 2.0.0, and swift-log to 1.14.0, while introducing new dependencies like swift-async-algorithms, swift-atomics, and swift-http-types. The package now targets macOS 11, iOS 15, and visionOS 1, and introduces new library products (HummingbirdCore, HummingbirdHTTP2, HummingbirdTLS, HummingbirdRouter, HummingbirdTesting) with configurable traits for configuration support and full Foundation usage, replacing the previous single-library structure.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 68 → 67 (-1.3)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 93 → 92 (-0.1)
• Architecture 98 → 89 (-9.0)
• Maturity 59 → 59 (+0.0)
• Readiness 66 → 68 (+1.9)
• Security 74 → 73 (-1.5)
• Performance 79 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Hotspot: Sources/Hummingbird/Middleware/FileMiddleware.swift (Sources/Hummingbird/Middleware/FileMiddleware.swift)

• Ambiguous overload resolution for service registration. One overload takes a single Service, the other takes a Sequence. While technically distinct, in Swift, passing an array of services (which is a Sequence) to the single-service overload is impossible, but passing a single service to the sequence overload is valid. This can lead to confusion or unnecessary boxing/unboxing. More importantly, Application also has a services property in its constructor. The existence of addServices suggests mutable registration, but the constructor also accepts services. It is unclear if addServices appends to the constructor-provided list or replaces it.
• Coverage not measured — Swift suite
• Dependency hygiene PARTLY measured — SwiftPM pinning read, dependency currency NOT established
• Duplicate lifecycle hook with different signatures. Application exposes onServerRunning taking a Channel, while the protocol ApplicationProtocol also defines onServerRunning taking a Channel. However, Application also has a constructor parameter onServerRunning. It is unclear if the property/method on the instance overrides the constructor closure or if they are distinct hooks. More critically, ApplicationProtocol is likely an internal or implementation detail, yet it exposes the same named hook as the public Application type, creating confusion about which one the user should implement or call.
• Duplicated block (11 lines × 2) (Sources/HummingbirdCore/Utils/String+percentEncode.swift)
• Duplicated block (14 lines × 2) (Sources/Hummingbird/Files/CacheControl.swift)
• Duplicated block (9 lines × 2) (Sources/HummingbirdCore/Utils/String+percentEncode.swift)
• High: security finding (details withheld)
• Off the main sequence: HummingbirdCore
• Projects may be oversized for their cohesion

• 8 commits — 8 feature/other, 0 fixes

• .github/workflows — 3 commits
• (root) — 2 commits
• docs/sbom — 2 commits
• Sources/Hummingbird — 1 commit

• change: Add FullFoundation trait that enables code needing the full Foundation library (#899)
• change: Add accept-ranges header for file middleware requests (#900)
• change: Bump github/codeql-action in the dependencies group (#898)
• change: Bump the dependencies group across 1 directory with 2 updates (#909)
• change: Remove 6.1 version of Package.swift (#903)
• change: Update Software Bill of Materials (SBOM) (#902)
• change: Update Software Bill of Materials (SBOM) (#904)
• change: Update from hummingbird-project-template 8c63c9c2fd2b6b44e967d2b2b131330c7568715e (#901)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

hummingbird-project/hummingbird was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.