feat(request): add last_event_id property

docs/_newsfragments/2580.newandimproved.rst

@@ -0,0 +1,4 @@
+A new request property, :attr:`req.last_event_id <falcon.Request.last_event_id>`,
+was added to provide convenient access to the ``Last-Event-ID`` header.
+This header is commonly sent by clients when reconnecting to a
+:attr:`Server-Sent Events <falcon.asgi.Response.sse>` stream.

falcon/asgi/request.py

@@ -260,6 +260,7 @@ def __init__(
     if_range: str | None = asgi_helpers._header_property('If-Range')
     referer: str | None = asgi_helpers._header_property('Referer')
     user_agent: str | None = asgi_helpers._header_property('User-Agent')
+    last_event_id: str | None = asgi_helpers._header_property('Last-Event-ID')
 
     @property
     def accept(self) -> str:

falcon/request.py

@@ -355,6 +355,8 @@ def __repr__(self) -> str:
     """Value of the If-Range header, or ``None`` if the header is missing."""
     referer: str | None = helpers._header_property('HTTP_REFERER')
     """Value of the Referer header, or ``None`` if the header is missing."""
+    last_event_id: str | None = helpers._header_property('HTTP_LAST_EVENT_ID')
+    """Value of the Last-Event-ID header, or ``None`` if the header is missing."""
 
     @property
     def forwarded(self) -> list[Forwarded] | None:

tests/test_request_attrs.py

@@ -1058,6 +1058,17 @@ def test_get_param_as_list_multiple_values_vs_delimiter(self, asgi, delimiter):
         result = req.get_param_as_list('phrase', delimiter=delimiter)
         assert result == ['quick brown fox', 'lazy dog']
 
+    @pytest.mark.parametrize('value', ['12345', '1768042793-1337'])
+    def test_last_event_id(self, asgi, value):
+        req = create_req(asgi, headers={'Last-Event-ID': value})
+        assert req.last_event_id == value
+
+    @pytest.mark.parametrize('value', [None, '', ' '])
+    def test_last_event_id_missing(self, asgi, value):
+        headers = {'Last-Event-ID': value} if value is not None else {}
+        req = create_req(asgi, headers=headers)
+        assert req.last_event_id is None
+
     # -------------------------------------------------------------------------
     # Helpers
     # -------------------------------------------------------------------------