dart-lang/shelf

This system is a modular HTTP server framework for Dart, centered on the core \shelf\ library which provides middleware composition and request handling. It extends this foundation with specialized packages for routing, static file serving, reverse proxying, and WebSocket support. The ecosystem also includes utilities for testing HTTP interactions and code generation for routing, all standardized on Dart 3.9+ with rigorous compliance testing against HTTP/1.1 specifications.

11 changes.

This period focused on the initial release of the shelf\_router package, introducing a trie-based routing system with annotation support and an accompanying code generator. The work also included updating the entire shelf ecosystem to require Dart 3.9+ and modernizing dependencies, while removing legacy entry points like shelf\_static.

15 changes.

This period focused on expanding the Shelf ecosystem with new packages for WebSocket support, static file serving, and testing utilities, while introducing a comprehensive HTTP/1.1 compliance testing framework. The core library and its dependencies were updated to require Dart 3.9, incorporating behavioral fixes for cookie handling and performance improvements in static file serving.

A new vendor submodule, Http11Probe, has been added to the repository. This package provides the baseline for HTTP/1.1 compliance testing, enabling the system to verify adherence to the HTTP/1.1 specification.

vendor · high confidence

The example directory now includes a complete, runnable demonstration of the shelf\_router\_generator package. It features a main.dart file defining service classes with annotated route handlers (GET, ALL, MOUNT) and URL parameters, alongside the generated main.g.dart file that implements the corresponding router logic. This provides users with a concrete reference for how to structure their code and use the generator to create Shelf handlers.

_pkgs/shelf\_router\generator/example · high confidence

The example directory now includes a main.dart file that demonstrates how to use the shelf\_router package. It shows creating a Router, adding GET handlers with URL parameters, handling asynchronous requests, mounting sub-routers, and setting up a pipeline with middleware.

_pkgs/shelf\router/example · high confidence

A new \tool/ci.sh\ script has been added to automate continuous integration tasks. This script iterates through specified packages (defined by the \PKGS\ environment variable) and executes various tasks such as analysis, formatting, and testing. Notably, it supports running tests on Chrome and with the Dart2Wasm compiler, enabling broader test coverage across different execution environments.

tool · high confidence

This entry introduces the \shelf\_packages\_handler\ package, which provides a Shelf handler for serving virtual \packages/\ directories. It includes \packagesHandler\ to serve package assets based on a provided map or the current isolate's resolution logic, and \packagesDirHandler\ to mount this behavior at any \/packages/\ segment in the URL. The package requires Dart ^3.9.0 and includes comprehensive tests for both handlers.

_pkgs/shelf\_packages\_handler, pkgs/shelf\_router\generator/lib · high confidence

Introduces the shelf\_router package, providing a request routing library for the shelf web server framework. Users can now define routes based on HTTP methods and path patterns using the Router class, and optionally organize handlers in classes annotated with @Route for code generation via shelf\_router\_generator.

_pkgs/shelf\router/lib · high confidence

This change introduces the \shelf\_test\_handler\ package, providing utilities to test HTTP interactions with Shelf handlers. It includes \ShelfTestHandler\ for defining expected request sequences and \ShelfTestServer\ for wrapping the handler in a local HTTP server, allowing developers to assert on request methods, paths, and responses during testing. The package requires Dart 3.9.0 and is configured to run tests on Chrome and Dart Wasm.

_pkgs/shelf\_test\handler · high confidence

The shelf\_web\_socket package is introduced, providing a Shelf handler that upgrades HTTP requests to WebSocket connections. The \webSocketHandler\ function accepts a connection callback and optional configuration for supported subprotocols, allowed origins (to prevent cross-origin attacks), and ping intervals for disconnect detection. An example application is included to demonstrate serving the handler on localhost.

_pkgs/shelf\_web\socket/lib · high confidence

Added a new \pkgs/\_shelf\_compliance\ package that validates \package:shelf\ against RFC 9110/9112 requirements using the vendored \Http11Probe\ tool. This includes a test harness that runs an echo server, captures JSON reports, and compares them against golden baselines to detect behavioral changes in areas like chunked encoding, cookies, and conditional requests.

_pkgs/\_shelf\compliance · high confidence

This change introduces the core \shelf\_router\ library, providing a new HTTP router for Shelf applications. It adds a \Router\ class that routes requests based on HTTP verbs and path patterns, supporting URL parameters (e.g., \/users/\<id\>\) and custom regular expressions. The router uses a Trie data structure for efficient candidate filtering before regex matching. It automatically handles HEAD requests for GET routes by stripping the response body and allows mounting other handlers under specific prefixes. Additionally, it provides a \Route\ annotation class for use with \shelf\_router\_generator\ to automatically generate routing code from class methods, and exposes captured parameters via \request.params\.

_pkgs/shelf\router/lib/src · high confidence

Adds the \shelf\_router\_generator\ package, which provides a code generator that scans classes for methods annotated with \shelf\router.Route\. It automatically generates a \\$\<className\>Router\ method that configures a \shelf\_router.Router\ instance by mapping annotated HTTP verbs and routes to the corresponding service methods, including support for mounting sub-routers via the \$mount\ verb.

_pkgs/shelf\_router\generator/lib/src · high confidence

The core implementation files for the Shelf HTTP server library have been added to the \pkgs/shelf/lib/src\ directory. This includes the foundational classes for handling HTTP requests and responses (\Request\, \Response\, \Message\), body management (\Body\), and header parsing (\Headers\). It also introduces the middleware composition system via \Pipeline\, \Cascade\, and \Middleware\ types, along with supporting utilities like \Handler\ typedefs, \IOServer\ for IO-backed serving, and helper classes for unmodifiable maps and header manipulation.

pkgs/shelf/lib/src · high confidence

The \lib/shelf\_static.dart\ file, which previously served as the library entry point for the \shelf\_static\ package, has been deleted. This change removes the top-level library declaration, effectively eliminating the public API surface for this specific library file within the package.

lib · high confidence

The shelf\_proxy package now requires Dart 3.9.0 or higher. This change updates the package's minimum SDK constraint, meaning users must upgrade their Dart environment to use this version of the library.

_pkgs/shelf\proxy · high confidence

The \serve\ and \serveRequests\ functions in \shelf\_io.dart\ now accept a \poweredByHeader\ argument, allowing users to customize or omit the default 'X-Powered-By' response header. By default, the header is set to 'Dart with package:shelf', but passing \null\ removes it entirely, giving users control over server technology disclosure.

pkgs/shelf/lib · high confidence

The package has raised its minimum SDK requirement to Dart 3.9.0. Additionally, the handling of multiple Cookie header values has been corrected to join them with '; ' (semicolon and space) instead of ',' (comma), aligning with the cookie-string grammar defined in RFC 6265 section 5.4.

pkgs/shelf · high confidence

The \webSocketHandler\ has been updated to enforce stricter protocol requirements: it now rejects requests that do not use HTTP/1.1 and requires the underlying server to support request hijacking via \dart:io\ sockets. This change removes support for WebSocket connections initiated through non-standard or non-IO sockets, ensuring that only valid, hijackable HTTP/1.1 upgrade requests are processed.

_pkgs/shelf\_web\socket/lib/src · high confidence

The \shelf\_static\ handler now uses asynchronous file system operations (replacing blocking calls like \statSync\) to prevent blocking the Dart isolate event loop, significantly improving performance under high concurrency. It adds support for HTTP caching via \generateETag\ and \maxAge\ parameters on \createStaticHandler\ and \createFileHandler\, and fixes handling of oversized integer values in HTTP \Range\ headers to prevent unhandled \FormatException\ errors.

_pkgs/shelf\static · high confidence

Add router performance benchmarks; Added test coverage for shelf\_proxy forwarding and header handling; Added test fixtures for shelf\_router\_generator code generation; Added tests for ShelfTestHandler and ShelfTestServer; Added tests for WebSocket handler functionality; Added tests for shelf\_router\_generator build verification and server routing; Initial test coverage for shelf\_router.

The shelf ecosystem (shelf, shelf\_router, shelf\_static, shelf\_proxy, shelf\_web\_socket, shelf\_packages\_handler, shelf\_test\_handler, and shelf\_router\_generator) has been updated to require Dart SDK ^3.9.0 and upgraded to use modern versions of core dependencies such as http, test, and analyzer. This ensures compatibility with the latest Dart runtime and standardizes linting across the packages via dart\_flutter\_team\_lints.

(dependencies) · high confidence

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

• First survey — no prior run to compare against. CAI 66.

• Code Health 97
• Architecture 98
• Maturity 59
• Readiness 74
• Security 57
• Domain Modelling 100

• 300 commits — 266 feature/other, 34 fixes

• (root) — 77 commits
• .github/workflows — 63 commits
• pkgs/shelf — 30 commits
• pkgs/shelf_router_generator — 29 commits
• pkgs/shelf_router — 25 commits
• (repo) — 19 commits
• lib/src — 11 commits
• pkgs/shelf_static — 10 commits
• pkgs/shelf_web_socket — 10 commits
• pkgs/_shelf_compliance — 4 commits
• .github/dependabot.yml — 3 commits
• .github/no-response.yml — 3 commits
• pkgs/shelf_test_handler — 3 commits
• pkgs/shelf_packages_handler — 2 commits
• pkgs/shelf_proxy — 2 commits
• .github/ISSUE_TEMPLATE — 1 commit
• .github/labeler.yml — 1 commit
• example/example.dart — 1 commit
• lib/shelf_io.dart — 1 commit
• test/cascade_test.dart — 1 commit

• fix: Enable and fix a number of new lints
• fix: Fix 244 (#268)
• fix: Fix Router.routeNotFound to enable multiple read() calls on it.
• fix: Fix SDK constraints 2.12.0-0 to 2.12.0 (#148)
• fix: Fix labeler.yml (#403)
• fix: Fix a number of hints and lints (#151)
• fix: Fix an issue with range support, prepare for release (#62)
• fix: Fix changelog (#44)
• fix: Fix doc comment issues (#209)
• fix: Fix doc comment references (#323)
• fix: Fix multi-header handling in shelf_proxy (#519)
• fix: Fix name of mono_pkg.yAml in shelf_test_handler and shelf_web_socket (#225)
• fix: Fix newly enforced lint (#19)
• fix: Fix pubspec repository for shelf_web_socket (#233)
• fix: Fix repository url in shelf_router and shelf_router_generator (#240)
• fix: Fixes for package score: longer description and correct example filename (#56)
• fix: Merge pull request #147 from isoos/fix-rnf
• fix: Remove author field, fix SDK constraint (#20)
• fix: Revert "drop legacy SDk tests" - Test on dart 2.8.4 (#15)
• fix: Update analysis_options and make corresponding fixes (#220)
• …and 280 more

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

dart-lang/shelf 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.