Skip to content
CAI
Software that uses CAICheck a score

hummingbird-project/hummingbird

67.7

Adequate · 15 November 2026

16.4k

lines of production code

Swift

primary language

5

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add JSON encoding and decoding support for Hummingbird requests and responses

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

Added Hummingbird performance benchmarks

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

Added performance test executable for Hummingbird 2.0

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

Introduce HTTP/2 support with upgrade and plaintext modes

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

Introduce HummingbirdTesting module with router, live, and AsyncHTTPClient test frameworks

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

Introduce persistent key/value storage with expiration support

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

Introduces Codable response encoding and decoding protocols

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

New CI and development utility scripts

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

New HTTP error handling protocol and types

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

New security and observability middleware added

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

New utility types and string encoding helpers added to HummingbirdCore

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

New utility utilities for HTTP date handling, string splitting, and service lifecycle

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

Repository initialization with project scaffolding and documentation

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

Support for conditional and iterative middleware composition

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

TLS server support via HTTPServerBuilder and configurable TLS channels

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

URLEncodedForm integration with Hummingbird Request/Response lifecycle

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

Removals

Removal of test-framework main.swift entry point

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

Behavioural changes

Extensible Cache-Control headers and configurable file chunk sizes

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

HTTP/1 server now supports configurable decoder limits and idle timeouts

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

Hummingbird 2.0 application architecture and API overhaul

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

Hummingbird 2.0 router overhaul with new path syntax and validation

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

Hummingbird 2.0 server-side request handling and context architecture

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

Introduce result-builder-based router with context transforms and case-insensitive routing

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

New Response and ResponseBody types with automatic Content-Length handling

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

New request body handling with inbound close cancellation

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

New trie-based router implementation with case-insensitive support

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

Removed legacy Xcode workspace configuration

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

Server 2.0: NIOAsyncChannel-based architecture with connection limits and NWEndpoint support

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

Test coverage

1 commit adding/updating tests in Tests/HummingbirdTests/Utils; 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.

Dependencies

Major dependency upgrade and Swift 6.2 migration for Hummingbird 2.0

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 cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 65 → 68 (+2.7)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 76 → 74 (-1.9)
  • Architecture 88 → 94 (+6.6)
  • Maturity 59 → 59 (+0.0)
  • Readiness 61 → 68 (+6.8)
  • Security 78 → 84 (+6.9)
  • Performance 84 → 100 (+15.6)

Resolved (10)

  • Duplicated block (11 lines × 2) (Sources/Hummingbird/HTTP/Cookie.swift)
  • Duplicated block (11 lines × 2) (Sources/HummingbirdCore/Utils/String+percentEncode.swift)
  • Duplicated block (11 lines × 2) (Sources/HummingbirdHTTP2/TLSChannelConfiguration.swift)
  • Duplicated block (6 lines × 2) (Sources/Hummingbird/Middleware/CORSMiddleware.swift)
  • Duplicated block (7 lines × 3) (Sources/Hummingbird/Utils/HTTPHeaderDateFormatStyle.swift)
  • Duplicated block (9 lines × 2) (Sources/HummingbirdCore/Utils/String+percentEncode.swift)
  • No ADRs found
  • No artifact signing
  • No build provenance
  • Projects may be oversized for their cohesion

New (43)

  • Duplicated block (11 lines × 2) (Sources/Hummingbird/HTTP/Cookie.swift)
  • Duplicated block (11 lines × 2) (Sources/HummingbirdHTTP2/TLSChannelConfiguration.swift)
  • Duplicated block (17 lines × 2) (Sources/HummingbirdCore/Utils/String+percentEncode.swift)
  • Duplicated block (6 lines × 2) (Sources/Hummingbird/Middleware/CORSMiddleware.swift)
  • Edited copies of one member (3 members, 4+ corresponding lines) (Sources/HummingbirdTesting/TestClient.swift)
  • Edited copies of one member (3 members, 7+ corresponding lines) (Sources/HummingbirdRouter/ContextTransform.swift)
  • Edited copies of one member (4 members, 11+ corresponding lines) (Sources/Hummingbird/Codable/JSON/JSONCoding.swift)
  • Edited copies of one member (4 members, 14+ corresponding lines) (Sources/HummingbirdCore/Utils/HBParser.swift)
  • Edited copies of one member (6 members, 6+ corresponding lines) (Sources/HummingbirdRouter/Route.swift)
  • Edited copies of one member (7 members, 6+ corresponding lines) (Sources/HummingbirdRouter/Route.swift)
  • Edited copy of a member (10 corresponding lines) (Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift)
  • Edited copy of a member (10 corresponding lines) (Sources/Hummingbird/Router/Parameters+UUID.swift)
  • Edited copy of a member (11 corresponding lines) (Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift)
  • Edited copy of a member (11 corresponding lines) (Sources/Hummingbird/Router/ResponseGenerator.swift)
  • Edited copy of a member (12 corresponding lines) (Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift)
  • Edited copy of a member (12 corresponding lines) (Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift)
  • Edited copy of a member (12 corresponding lines) (Sources/Hummingbird/Utils/SplitStringSequences.swift)
  • Edited copy of a member (12 corresponding lines) (Sources/HummingbirdHTTP2/HTTP2UpgradeChannel.swift)
  • Edited copy of a member (13 corresponding lines) (Sources/Hummingbird/Files/FileIO.swift)
  • Edited copy of a member (13 corresponding lines) (Sources/Hummingbird/Middleware/LogRequestMiddleware.swift)
  • …and 23 more

Changes since last survey

  • 13 commits — 13 feature/other, 0 fixes

By area

  • .github/workflows — 4 commits
  • (root) — 2 commits
  • Sources/Hummingbird — 2 commits
  • Sources/HummingbirdCore — 2 commits
  • Sources/HummingbirdTesting — 1 commit
  • Tests/HummingbirdTests — 1 commit
  • docs/sbom — 1 commit

Notable commits

  • change: Add scorecard badge to README (#944)
  • change: Add temporary folder/file test traits (#935)
  • change: Bump peter-evans/create-pull-request (#945)
  • change: Bump the dependencies group across 1 directory with 2 updates (#943)
  • change: Create scorecard.yml (#929)
  • change: Deprecate _HB_SendableMetatype (#933)
  • change: Enable strict memory safety checking (#776) (#876)
  • change: Ensure uri has forward slash prefix (#937)
  • change: Improve GH action permissions (#938)
  • change: LocalFileSystem option to follow symbolic links or not (#934)
  • change: Replace unsafe code with span (#932)
  • change: Update README with new sponsor (#930)
  • change: Update Software Bill of Materials (SBOM) (#928)

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

Survey your own repository

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.

About this page

  • The score is its most recent published measurement, taken on 15 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 1c1602bc03932d02748e857af4eaa3f0bf6d8427 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-3c33c1882dc1.