Changelog for Falcon 4.4.0#

Summary#

This release contains a handful of long-requested features – a RegexConverter field converter, an application-wide error reporter, and a new allow_multiple keyword argument for the query string parameter helpers, along with a number of bug fixes. As usual, the newest CPython runtime, 3.15, is fully supported (including binary wheels).

The error reporter also serves as groundwork for the native OpenTelemetry integration that has been on our roadmap for a while. We are hoping to ship that integration as part of Falcon 4.5.

This release would not have been possible without the prototypes, fixes, and feature pull requests submitted by our community. Sincere thanks to our supporters and contributors!

Changes to Supported Platforms#

CPython 3.15 is now fully supported. (#2593)

New & Improved#

A new built-in field converter, RegexConverter, has been added to support regex-based path variable matching. (#857)
A new App method, set_error_reporter(), was added for observing all exceptions raised while processing requests (for instance, in order to log them, or to submit them to an error tracking or observability service). Error reporters are supported by both WSGI and ASGI applications. (#1942)
Previously, it was not possible to cleanly test the case where a WebSocket responder would keep running without sending or receiving any messages – ASGIConductor.simulate_ws would hang forever upon exiting the context.

To afford this scenario, a new optional timeout keyword argument was added to simulate_ws() that limits how long the test harness waits, both for the handshake (accept or deny), and for the app’s task to complete after the connection is closed; when the deadline passes, an instance of TimeoutError is raised. (#2585)
An optional allow_multiple keyword argument was added to the query string parameter helpers (get_param(), get_param_as_bool(), get_param_as_date(), get_param_as_datetime(), get_param_as_dict(), get_param_as_float(), get_param_as_int(), get_param_as_json(), get_param_as_media(), and get_param_as_uuid()).

When it is set to False, and the parameter resolves to more than one value, an HTTPInvalidParam error is raised instead of picking an arbitrary one of those values (default True). (#2735)

Fixed#

As prescribed by PEP 3333, WSGI servers tunnel non-ASCII characters in the request path via ISO-8859-1, and Falcon has long decoded PATH_INFO back to UTF-8. The SCRIPT_NAME variable was, however, used verbatim when populating req.root_path. This has been fixed, and the tunneled SCRIPT_NAME is now decoded in the same way as the request path. (#2667)
When decoding with unquote_plus=False, the cythonized variant of falcon.uri.decode() mistook a literal plus sign followed by two hexadecimal digits for a percent-encoded byte. This has been fixed, and a literal plus is now preserved just like in the pure-Python case. (#2670)
When a route was only served by a catch-all on_request() responder, with no HTTP methods explicitly mapped via on_get(), on_post(), etc., the default OPTIONS responder rendered an empty Allow header, misleadingly indicating that the resource allows no methods at all. The Allow header is now omitted when the list of allowed methods is empty. (#2671)
When a simulated ASGI request bubbled up an unhandled exception, the test client’s lifespan task was left pending, emitting a stray "Task was destroyed but it is pending!" warning upon garbage collection. Such orphaned lifespan tasks are now cancelled cleanly. (#2745)

Contributors to this Release#

Many thanks to all of our talented and stylish contributors for this release!