feat (status_codes): update HTTP status constants wrt RFC 9110 (#2330)

* feat (status_codes) update HTTP status code constants wrt RFC 9110 refactor(response): replace falcon.HTTPPayloadTooLarge with falcon.HTTPContentTooLarge Replace the usage of falcon.HTTPPayloadTooLarge with falcon.HTTPContentTooLarge in the codebase. This change aligns with the recent renaming of the class in the Falcon library. The new class name better reflects the purpose of the error, which is to indicate that the content of the request is too large for the server to process. Closes #2322 * docs(_newsfragments) documented class name change from HTTPPayloadTooLarge to HTTPContentTooLarge * fix(status_codes): bring back removed constant for compatibility, fix ruff * chore: misc touchups * refactor: add a compat alias HTTPPayloadTooLarge ==> HTTPContentTooLarge * docs: tweaks newsfragment for HTTP status code updates --------- Co-authored-by: Vytautas Liuolia <[email protected]>
falconry · Sep 27, 2024 · 9b0f7da · 9b0f7da
1 parent f843b4f
commit 9b0f7da
Show file tree

Hide file tree

Showing 12 changed files with 56 additions and 24 deletions.
diff --git a/README.rst b/README.rst
@@ -573,7 +573,7 @@ Note that this example assumes that the
                 msg = ('The size of the request is too large. The body must not '
                        'exceed ' + str(limit) + ' bytes in length.')
 
-                raise falcon.HTTPPayloadTooLarge(
+                raise falcon.HTTPContentTooLarge(
                     title='Request body is too large', description=msg)
 
         return hook
@@ -830,7 +830,7 @@ Here's the ASGI version of the app from above. Note that it uses the
                 msg = ('The size of the request is too large. The body must not '
                        'exceed ' + str(limit) + ' bytes in length.')
 
-                raise falcon.HTTPPayloadTooLarge(
+                raise falcon.HTTPContentTooLarge(
                     title='Request body is too large', description=msg)
 
         return hook

diff --git a/docs/_newsfragments/2276.newandimproved.rst b/docs/_newsfragments/2276.newandimproved.rst
@@ -0,0 +1,11 @@
+The class ``falcon.HTTPPayloadTooLarge`` was renamed to
+:class:`falcon.HTTPContentTooLarge`, together with the accompanying HTTP
+:ref:`status code <status>` update, in order to reflect the newest HTTP
+semantics as per
+`RFC 9110, Section 15.5.14 <https://datatracker.ietf.org/doc/html/rfc9110#status.413>`__.
+(The old class name remains available as a deprecated compatibility alias.)
+
+In addition, one new :ref:`status code constant <status>` was added:
+``falcon.HTTP_421`` (also available as ``falcon.HTTP_MISDIRECTED_REQUEST``)
+in accordance with
+`RFC 9110, Section 15.5.20 <https://datatracker.ietf.org/doc/html/rfc9110#status.421>`__.
diff --git a/docs/api/errors.rst b/docs/api/errors.rst
@@ -150,7 +150,7 @@ Predefined Errors
 .. autoclass:: falcon.HTTPPreconditionFailed
     :members:
 
-.. autoclass:: falcon.HTTPPayloadTooLarge
+.. autoclass:: falcon.HTTPContentTooLarge
     :members:
 
 .. autoclass:: falcon.HTTPUriTooLong

diff --git a/docs/api/status.rst b/docs/api/status.rst
@@ -139,7 +139,7 @@ HTTPStatus
     HTTP_GONE = HTTP_410
     HTTP_LENGTH_REQUIRED = HTTP_411
     HTTP_PRECONDITION_FAILED = HTTP_412
-    HTTP_REQUEST_ENTITY_TOO_LARGE = HTTP_413
+    HTTP_CONTENT_TOO_LARGE = HTTP_413
     HTTP_REQUEST_URI_TOO_LONG = HTTP_414
     HTTP_UNSUPPORTED_MEDIA_TYPE = HTTP_415
     HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = HTTP_416
@@ -168,7 +168,7 @@ HTTPStatus
     HTTP_410 = '410 Gone'
     HTTP_411 = '411 Length Required'
     HTTP_412 = '412 Precondition Failed'
-    HTTP_413 = '413 Payload Too Large'
+    HTTP_413 = '413 Content Too Large'
     HTTP_414 = '414 URI Too Long'
     HTTP_415 = '415 Unsupported Media Type'
     HTTP_416 = '416 Range Not Satisfiable'

diff --git a/examples/things_advanced.py b/examples/things_advanced.py
@@ -141,7 +141,7 @@ def hook(req, resp, resource, params):
                 'exceed ' + str(limit) + ' bytes in length.'
             )
 
-            raise falcon.HTTPPayloadTooLarge(
+            raise falcon.HTTPContentTooLarge(
                 title='Request body is too large', description=msg
             )
 

diff --git a/examples/things_advanced_asgi.py b/examples/things_advanced_asgi.py
@@ -143,7 +143,7 @@ async def hook(req, resp, resource, params):
                 'exceed ' + str(limit) + ' bytes in length.'
             )
 
-            raise falcon.HTTPPayloadTooLarge(
+            raise falcon.HTTPContentTooLarge(
                 title='Request body is too large', description=msg
             )
 

diff --git a/falcon/__init__.py b/falcon/__init__.py
@@ -123,6 +123,7 @@
     'HTTPNotAcceptable',
     'HTTPNotFound',
     'HTTPNotImplemented',
+    'HTTPContentTooLarge',
     'HTTPPayloadTooLarge',
     'HTTPPreconditionFailed',
     'HTTPPreconditionRequired',
@@ -303,7 +304,6 @@
     'HTTP_PROCESSING',
     'HTTP_PROXY_AUTHENTICATION_REQUIRED',
     'HTTP_REQUESTED_RANGE_NOT_SATISFIABLE',
-    'HTTP_REQUEST_ENTITY_TOO_LARGE',
     'HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE',
     'HTTP_REQUEST_TIMEOUT',
     'HTTP_REQUEST_URI_TOO_LONG',
@@ -354,6 +354,7 @@
 from falcon.errors import HTTPBadGateway
 from falcon.errors import HTTPBadRequest
 from falcon.errors import HTTPConflict
+from falcon.errors import HTTPContentTooLarge
 from falcon.errors import HTTPFailedDependency
 from falcon.errors import HTTPForbidden
 from falcon.errors import HTTPGatewayTimeout
@@ -529,6 +530,7 @@
 from falcon.status_codes import HTTP_BAD_GATEWAY
 from falcon.status_codes import HTTP_BAD_REQUEST
 from falcon.status_codes import HTTP_CONFLICT
+from falcon.status_codes import HTTP_CONTENT_TOO_LARGE
 from falcon.status_codes import HTTP_CONTINUE
 from falcon.status_codes import HTTP_CREATED
 from falcon.status_codes import HTTP_EARLY_HINTS
@@ -567,7 +569,6 @@
 from falcon.status_codes import HTTP_PRECONDITION_REQUIRED
 from falcon.status_codes import HTTP_PROCESSING
 from falcon.status_codes import HTTP_PROXY_AUTHENTICATION_REQUIRED
-from falcon.status_codes import HTTP_REQUEST_ENTITY_TOO_LARGE
 from falcon.status_codes import HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE
 from falcon.status_codes import HTTP_REQUEST_TIMEOUT
 from falcon.status_codes import HTTP_REQUEST_URI_TOO_LONG

diff --git a/falcon/errors.py b/falcon/errors.py
@@ -37,10 +37,11 @@ def on_get(self, req, resp):
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Iterable, Optional, TYPE_CHECKING, Union
+from typing import Any, Iterable, Optional, TYPE_CHECKING, Union
 
 from falcon.http_error import HTTPError
 import falcon.status_codes as status
+from falcon.util import deprecation
 from falcon.util.misc import dt_to_http
 
 if TYPE_CHECKING:
@@ -73,7 +74,7 @@ def on_get(self, req, resp):
     'HTTPNotAcceptable',
     'HTTPNotFound',
     'HTTPNotImplemented',
-    'HTTPPayloadTooLarge',
+    'HTTPContentTooLarge',
     'HTTPPreconditionFailed',
     'HTTPPreconditionRequired',
     'HTTPRangeNotSatisfiable',
@@ -952,8 +953,8 @@ def __init__(
         )
 
 
-class HTTPPayloadTooLarge(HTTPError):
-    """413 Payload Too Large.
+class HTTPContentTooLarge(HTTPError):
+    """413 Content Too Large.
 
     The server is refusing to process a request because the request
     payload is larger than the server is willing or able to process.
@@ -1025,6 +1026,17 @@ def __init__(
         )
 
 
+# TODO(vytas): Remove in Falcon 5.0.
+class HTTPPayloadTooLarge(HTTPContentTooLarge):
+    """Compatibility alias of :class:`falcon.HTTPContentTooLarge`."""
+
+    @deprecation.deprecated(
+        'HTTPPayloadTooLarge is deprecated; use HTTPContentTooLarge instead.'
+    )
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+
 class HTTPUriTooLong(HTTPError):
     """414 URI Too Long.
 

diff --git a/falcon/status_codes.py b/falcon/status_codes.py
@@ -93,7 +93,9 @@
 HTTP_LENGTH_REQUIRED: Final[str] = HTTP_411
 HTTP_412: Final[str] = '412 Precondition Failed'
 HTTP_PRECONDITION_FAILED: Final[str] = HTTP_412
-HTTP_413: Final[str] = '413 Payload Too Large'
+HTTP_413: Final[str] = '413 Content Too Large'
+HTTP_CONTENT_TOO_LARGE: Final[str] = HTTP_413
+HTTP_PAYLOAD_TOO_LARGE: Final[str] = HTTP_413
 HTTP_REQUEST_ENTITY_TOO_LARGE: Final[str] = HTTP_413
 HTTP_414: Final[str] = '414 URI Too Long'
 HTTP_REQUEST_URI_TOO_LONG: Final[str] = HTTP_414
@@ -330,6 +332,7 @@
     'HTTP_BAD_GATEWAY',
     'HTTP_BAD_REQUEST',
     'HTTP_CONFLICT',
+    'HTTP_CONTENT_TOO_LARGE',
     'HTTP_CONTINUE',
     'HTTP_CREATED',
     'HTTP_EARLY_HINTS',
@@ -369,7 +372,6 @@
     'HTTP_PROCESSING',
     'HTTP_PROXY_AUTHENTICATION_REQUIRED',
     'HTTP_REQUESTED_RANGE_NOT_SATISFIABLE',
-    'HTTP_REQUEST_ENTITY_TOO_LARGE',
     'HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE',
     'HTTP_REQUEST_TIMEOUT',
     'HTTP_REQUEST_URI_TOO_LONG',

diff --git a/tests/test_error.py b/tests/test_error.py
@@ -18,7 +18,7 @@
         (falcon.HTTPGone, status.HTTP_410),
         (falcon.HTTPLengthRequired, status.HTTP_411),
         (falcon.HTTPPreconditionFailed, status.HTTP_412),
-        (falcon.HTTPPayloadTooLarge, status.HTTP_413),
+        (falcon.HTTPContentTooLarge, status.HTTP_413),
         (falcon.HTTPUriTooLong, status.HTTP_414),
         (falcon.HTTPUnsupportedMediaType, status.HTTP_415),
         (falcon.HTTPUnprocessableEntity, status.HTTP_422),
@@ -81,7 +81,7 @@ def test_with_default_title_and_desc_args(err, title, args):
         falcon.HTTPGone,
         falcon.HTTPLengthRequired,
         falcon.HTTPPreconditionFailed,
-        falcon.HTTPPayloadTooLarge,
+        falcon.HTTPContentTooLarge,
         falcon.HTTPUriTooLong,
         falcon.HTTPUnsupportedMediaType,
         falcon.HTTPUnprocessableEntity,
@@ -128,7 +128,7 @@ def test_with_title_desc_and_headers(err):
         falcon.HTTPGone,
         falcon.HTTPLengthRequired,
         falcon.HTTPPreconditionFailed,
-        falcon.HTTPPayloadTooLarge,
+        falcon.HTTPContentTooLarge,
         falcon.HTTPUriTooLong,
         falcon.HTTPUnsupportedMediaType,
         falcon.HTTPUnprocessableEntity,
@@ -195,7 +195,7 @@ def test_args_kw_only(err, args):
     [
         falcon.HTTPServiceUnavailable,
         falcon.HTTPTooManyRequests,
-        falcon.HTTPPayloadTooLarge,
+        falcon.HTTPContentTooLarge,
     ],
 )
 def test_with_retry_after(err):
@@ -210,7 +210,7 @@ def test_with_retry_after(err):
     [
         falcon.HTTPServiceUnavailable,
         falcon.HTTPTooManyRequests,
-        falcon.HTTPPayloadTooLarge,
+        falcon.HTTPContentTooLarge,
     ],
 )
 def test_with_retry_after_and_headers(err):
@@ -283,7 +283,7 @@ def test_custom_400(err, args, title, desc):
             'a, b',
             True,
         ),
-        (falcon.HTTPPayloadTooLarge, 'Retry-After', 'retry_after', 123, '123', False),
+        (falcon.HTTPContentTooLarge, 'Retry-After', 'retry_after', 123, '123', False),
         (
             falcon.HTTPRangeNotSatisfiable,
             'Content-Range',
@@ -350,3 +350,9 @@ def test_override_header_list(
         assert header_name in value.headers
         assert isinstance(value.headers, dict)
         assert value.headers[header_name] == res
+
+
+def test_http_payload_too_large_deprecation():
+    with pytest.warns(match='HTTPContentTooLarge'):
+        err = errors.HTTPPayloadTooLarge()
+        assert err.title == '413 Content Too Large'
diff --git a/tests/test_httperror.py b/tests/test_httperror.py
@@ -171,7 +171,7 @@ def on_get(self, req, resp):
 
 class RequestEntityTooLongResource:
     def on_get(self, req, resp):
-        raise falcon.HTTPPayloadTooLarge(
+        raise falcon.HTTPContentTooLarge(
             title='Request Rejected', description='Request Body Too Large'
         )
 
@@ -181,7 +181,7 @@ def __init__(self, retry_after):
         self.retry_after = retry_after
 
     def on_get(self, req, resp):
-        raise falcon.HTTPPayloadTooLarge(
+        raise falcon.HTTPContentTooLarge(
             title='Request Rejected',
             description='Request Body Too Large',
             retry_after=self.retry_after,

diff --git a/tests/test_status_codes.py b/tests/test_status_codes.py
@@ -16,7 +16,7 @@ def test_statuses_are_in_compliance_with_http_from_python313(self, status):
         if status_code >= 700:
             pytest.skip('Codes above 700 are not defined in http package')
         http_status = http.HTTPStatus(status_code)
-        if status_code in [413, 418, 422]:
+        if status_code in [418, 422]:
             assert http_status.phrase != message
         else:
             assert http_status.phrase == message