uhttp-workers 1.3.0__tar.gz → 1.4.0__tar.gz

{uhttp_workers-1.3.0/uhttp_workers.egg-info → uhttp_workers-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.3.0
+Version: 1.4.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -513,6 +513,43 @@ class MyDispatcher(_workers.Dispatcher):
 `pending` is a `_PendingRequest` with `client` (original connection) and `pool` (source pool).
 Requests with `request_id=-1` are ignored by the dispatcher when the worker responds.
 
+`on_response()` fires only for the happy path (handler returned a response). For lifecycle
+cleanup that must run regardless of outcome — timeouts, client disconnects, shutdown — use
+`on_pending_removed()` (see below).
+
+## Request Lifecycle Hook
+
+Override `on_pending_removed(request_id, pending, reason)` on the dispatcher when you keep
+side-state keyed by `request_id` and need it cleaned up exactly once, no matter how the
+request ended:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def on_pending_removed(self, request_id, pending, reason):
+        self._side_state.pop(request_id, None)
+        if reason == _workers.PENDING_TIMEOUT:
+            self._metrics.timeouts += 1
+```
+
+Reason is one of:
+
+| Constant | When |
+|---|---|
+| `PENDING_COMPLETED` | Handler returned a response, client got it. `on_response()` runs first. |
+| `PENDING_TIMEOUT` | Request exceeded `pool.timeout`; client got 504. Worker may still be processing. |
+| `PENDING_DISCONNECTED` | Client disconnected mid-stream; worker was notified via control queue (race possible). |
+| `PENDING_STREAM_CLOSED` | Worker ended the SSE stream cleanly. |
+| `PENDING_SHUTDOWN` | Dispatcher is shutting down; client got 503. |
+
+The hook is invoked after the client-facing action (respond / disconnect / control queue put)
+so dispatcher state is finalized when it runs. Exceptions raised by the hook are logged at
+`LOG_ERROR` and swallowed — they will not crash the dispatcher loop.
+
+Override `on_response()` if you only care about the happy path (e.g. cross-pool forwarding).
+Override `on_pending_removed()` if you need exactly-once cleanup. Overriding both is allowed
+but discouraged — for the `PENDING_COMPLETED` reason, `on_response()` is called immediately
+before `on_pending_removed()`.
+
 ## Dispatcher Idle Hook
 
 Override `on_idle()` on the dispatcher for periodic background tasks — called on each `select()` timeout (every `SELECT_TIMEOUT` seconds, default 1s):

{uhttp_workers-1.3.0 → uhttp_workers-1.4.0}/README.md

@@ -499,6 +499,43 @@ class MyDispatcher(_workers.Dispatcher):
 `pending` is a `_PendingRequest` with `client` (original connection) and `pool` (source pool).
 Requests with `request_id=-1` are ignored by the dispatcher when the worker responds.
 
+`on_response()` fires only for the happy path (handler returned a response). For lifecycle
+cleanup that must run regardless of outcome — timeouts, client disconnects, shutdown — use
+`on_pending_removed()` (see below).
+
+## Request Lifecycle Hook
+
+Override `on_pending_removed(request_id, pending, reason)` on the dispatcher when you keep
+side-state keyed by `request_id` and need it cleaned up exactly once, no matter how the
+request ended:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def on_pending_removed(self, request_id, pending, reason):
+        self._side_state.pop(request_id, None)
+        if reason == _workers.PENDING_TIMEOUT:
+            self._metrics.timeouts += 1
+```
+
+Reason is one of:
+
+| Constant | When |
+|---|---|
+| `PENDING_COMPLETED` | Handler returned a response, client got it. `on_response()` runs first. |
+| `PENDING_TIMEOUT` | Request exceeded `pool.timeout`; client got 504. Worker may still be processing. |
+| `PENDING_DISCONNECTED` | Client disconnected mid-stream; worker was notified via control queue (race possible). |
+| `PENDING_STREAM_CLOSED` | Worker ended the SSE stream cleanly. |
+| `PENDING_SHUTDOWN` | Dispatcher is shutting down; client got 503. |
+
+The hook is invoked after the client-facing action (respond / disconnect / control queue put)
+so dispatcher state is finalized when it runs. Exceptions raised by the hook are logged at
+`LOG_ERROR` and swallowed — they will not crash the dispatcher loop.
+
+Override `on_response()` if you only care about the happy path (e.g. cross-pool forwarding).
+Override `on_pending_removed()` if you need exactly-once cleanup. Overriding both is allowed
+but discouraged — for the `PENDING_COMPLETED` reason, `on_response()` is called immediately
+before `on_pending_removed()`.
+
 ## Dispatcher Idle Hook
 
 Override `on_idle()` on the dispatcher for periodic background tasks — called on each `select()` timeout (every `SELECT_TIMEOUT` seconds, default 1s):

{uhttp_workers-1.3.0 → uhttp_workers-1.4.0}/tests/test_dispatcher.py

@@ -12,6 +12,9 @@ from uhttp.workers import (
     MSG_RESPONSE, MSG_HEARTBEAT,
     MSG_SSE_OPEN, MSG_SSE_EVENT, MSG_SSE_CLOSE,
     CTL_DISCONNECT,
+    PENDING_COMPLETED, PENDING_TIMEOUT, PENDING_DISCONNECTED,
+    PENDING_STREAM_CLOSED, PENDING_SHUTDOWN,
+    LOG_ERROR,
     _PendingRequest,
 )
 
@@ -552,5 +555,177 @@ class TestDispatcherSSE(unittest.TestCase):
         # should not raise, just ignore
 
 
+class TestDispatcherPendingRemoved(unittest.TestCase):
+    """Tests for the on_pending_removed lifecycle hook."""
+
+    def _make_dispatcher(self, dispatcher_cls=Dispatcher):
+        pool = WorkerPool(DummyWorker, routes=['/api/**'])
+        d = dispatcher_cls.__new__(dispatcher_cls)
+        d._sync_routes = []
+        d._static_routes = {}
+        d._pools = [pool]
+        d._pending = {}
+        d._max_pending = 1000
+        d._next_request_id = 0
+        d._response_queue = mp.Queue()
+        d._log_is_tty = False
+        d.log_calls = []
+        d.on_log = lambda name, level, msg: d.log_calls.append(
+            (name, level, msg))
+        d.recorded = []
+        return d, pool
+
+    def test_completed_fires_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append((request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        d._pending[1] = pending
+        response = Response(request_id=1, data={'ok': True}, status=200)
+        d._process_response((MSG_RESPONSE, 1, response))
+        self.assertEqual(d.recorded, [(1, PENDING_COMPLETED)])
+
+    def test_completed_calls_on_response_before_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_response(self, response, pending):
+                self.recorded.append(('on_response', response.request_id))
+
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append(('hook', request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        d._pending[1] = pending
+        response = Response(request_id=1, data={'ok': True}, status=200)
+        d._process_response((MSG_RESPONSE, 1, response))
+        self.assertEqual(d.recorded, [
+            ('on_response', 1),
+            ('hook', 1, PENDING_COMPLETED),
+        ])
+
+    def test_timeout_fires_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append((request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        pending.timestamp = 0  # very old
+        d._pending[1] = pending
+        d._expire_pending()
+        self.assertNotIn(1, d._pending)
+        self.assertEqual(client.response_status, 504)
+        self.assertEqual(d.recorded, [(1, PENDING_TIMEOUT)])
+
+    def test_stream_closed_fires_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append((request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+        client = MockClient('GET', '/api/events')
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        d._pending[1] = pending
+        d._process_response((MSG_SSE_CLOSE, 1))
+        self.assertTrue(client.stream_ended)
+        self.assertEqual(d.recorded, [(1, PENDING_STREAM_CLOSED)])
+
+    def test_disconnect_fires_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append((request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+        client = MockClient('GET', '/api/events')
+        client._connected = False
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        pending.worker_id = None  # skip control queue routing
+        d._pending[1] = pending
+        d._process_response(
+            (MSG_SSE_EVENT, 1, {'data': 'x'}, 'ping', None, None))
+        self.assertNotIn(1, d._pending)
+        self.assertEqual(d.recorded, [(1, PENDING_DISCONNECTED)])
+
+    def test_shutdown_fires_hook(self):
+
+        class RecordingDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                self.recorded.append((request_id, reason))
+
+        d, pool = self._make_dispatcher(RecordingDispatcher)
+
+        class FakeHttpServer:
+            def close(self):
+                pass
+
+        class FakePool:
+            def shutdown(self, timeout):
+                pass
+
+        d._http_server = FakeHttpServer()
+        d._pools = [FakePool()]
+        d._shutdown_timeout = 0.0  # skip drain loop immediately
+
+        client_a = MockClient('GET', '/api/a')
+        client_b = MockClient('GET', '/api/b')
+        d._pending[1] = _PendingRequest(client_a, pool)
+        d._pending[2] = _PendingRequest(client_b, pool)
+
+        d._shutdown()
+
+        self.assertEqual(client_a.response_status, 503)
+        self.assertEqual(client_b.response_status, 503)
+        self.assertEqual(sorted(d.recorded), [
+            (1, PENDING_SHUTDOWN),
+            (2, PENDING_SHUTDOWN),
+        ])
+        self.assertEqual(d._pending, {})
+
+    def test_hook_exception_is_swallowed_and_logged(self):
+
+        class BrokenDispatcher(Dispatcher):
+            def on_pending_removed(self, request_id, pending, reason):
+                raise RuntimeError('boom')
+
+        d, pool = self._make_dispatcher(BrokenDispatcher)
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        d._pending[1] = pending
+        response = Response(request_id=1, data={'ok': True}, status=200)
+        # must not propagate
+        d._process_response((MSG_RESPONSE, 1, response))
+        # client still got the response
+        self.assertTrue(client.responded)
+        self.assertEqual(client.response_status, 200)
+        # error was logged
+        error_logs = [
+            msg for _, level, msg in d.log_calls if level == LOG_ERROR]
+        self.assertEqual(len(error_logs), 1)
+        self.assertIn('on_pending_removed', error_logs[0])
+        self.assertIn('boom', error_logs[0])
+
+    def test_default_hook_is_noop(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        d._pending[1] = pending
+        response = Response(request_id=1, data={'ok': True}, status=200)
+        # base Dispatcher has no-op on_pending_removed → must not raise
+        d._process_response((MSG_RESPONSE, 1, response))
+        self.assertTrue(client.responded)
+
+
 if __name__ == '__main__':
     unittest.main()

{uhttp_workers-1.3.0 → uhttp_workers-1.4.0}/uhttp/workers.py

@@ -29,6 +29,13 @@ CTL_STOP = 'STOP'
 CTL_CONFIG = 'CONFIG'
 CTL_DISCONNECT = 'DISCONNECT'
 
+# Reasons for on_pending_removed
+PENDING_COMPLETED = 'COMPLETED'
+PENDING_TIMEOUT = 'TIMEOUT'
+PENDING_DISCONNECTED = 'DISCONNECTED'
+PENDING_STREAM_CLOSED = 'STREAM_CLOSED'
+PENDING_SHUTDOWN = 'SHUTDOWN'
+
 # Sentinel for deferred response
 DEFERRED = object()
 
@@ -1074,12 +1081,39 @@ class Dispatcher:
         """Called after response is sent to client.
 
         Override to post-process, e.g., forward data to another pool.
+        Fires only on a real handler response (PENDING_COMPLETED path);
+        use on_pending_removed() for lifecycle cleanup that must run
+        regardless of outcome.
 
         Args:
             response: Response object from worker.
             pending: _PendingRequest with client and pool reference.
         """
 
+    def on_pending_removed(self, request_id, pending, reason):
+        """Called exactly once per dispatched request, whatever the outcome.
+
+        Override for side-state cleanup keyed by request_id. Fires after
+        the client-facing action (respond/disconnect/control queue put) so
+        the dispatcher state is already finalized when this runs.
+        Exceptions raised here are logged and swallowed.
+
+        Reason values:
+            PENDING_COMPLETED     - handler returned a response, client got it.
+                                    on_response() is invoked first.
+            PENDING_TIMEOUT       - request exceeded pool.timeout; client got 504.
+                                    Worker may still be processing the request.
+            PENDING_DISCONNECTED  - client disconnected mid-stream; worker was
+                                    notified via control queue (race possible).
+            PENDING_STREAM_CLOSED - worker ended the SSE stream cleanly.
+            PENDING_SHUTDOWN      - dispatcher is shutting down; client got 503.
+
+        Args:
+            request_id: The request id being removed.
+            pending: _PendingRequest snapshot (client, pool, worker_id, ...).
+            reason: One of the PENDING_* constants above.
+        """
+
     def on_idle(self):
         """Called on each select timeout when no events arrived.
 
@@ -1224,6 +1258,8 @@ class Dispatcher:
             pending = self._pending.pop(request_id, None)
             if pending is not None:
                 pending.client.response_stream_end()
+                self._notify_pending_removed(
+                    request_id, pending, PENDING_STREAM_CLOSED)
         elif msg_type == MSG_RESPONSE:
             _, request_id, response = msg
             pending = self._pending.pop(request_id, None)
@@ -1234,6 +1270,8 @@ class Dispatcher:
                     headers=response.headers,
                     cookies=response.cookies)
                 self.on_response(response, pending)
+                self._notify_pending_removed(
+                    request_id, pending, PENDING_COMPLETED)
 
     def _stream_disconnected(self, request_id, pending):
         """Handle client disconnect during streaming."""
@@ -1243,6 +1281,18 @@ class Dispatcher:
             if pending.worker_id < len(pool._control_queues):
                 pool._control_queues[pending.worker_id].put(
                     (CTL_DISCONNECT, request_id))
+        self._notify_pending_removed(
+            request_id, pending, PENDING_DISCONNECTED)
+
+    def _notify_pending_removed(self, request_id, pending, reason):
+        """Invoke on_pending_removed, log and swallow exceptions."""
+        try:
+            self.on_pending_removed(request_id, pending, reason)
+        except Exception as exc:
+            self.on_log(
+                pending.pool.name, LOG_ERROR,
+                f"on_pending_removed({reason}) raised for "
+                f"request {request_id}: {exc!r}")
 
     def _process_responses(self):
         """Process all pending messages from response queue."""
@@ -1269,6 +1319,8 @@ class Dispatcher:
                 f"{pending.pool.timeout}s")
             pending.client.respond(
                 {'error': 'Request timeout'}, status=504)
+            self._notify_pending_removed(
+                request_id, pending, PENDING_TIMEOUT)
 
     def _check_all_workers(self):
         """Check health of all worker pools and queue sizes."""
@@ -1395,12 +1447,14 @@ class Dispatcher:
             except _queue.Empty:
                 pass
         # respond 503 to remaining pending
-        for pending in self._pending.values():
+        for request_id, pending in self._pending.items():
             try:
                 pending.client.respond(
                     {'error': 'Server shutting down'}, status=503)
             except Exception:
                 pass
+            self._notify_pending_removed(
+                request_id, pending, PENDING_SHUTDOWN)
         self._pending.clear()
         # shutdown all pools
         for pool in self._pools:

{uhttp_workers-1.3.0 → uhttp_workers-1.4.0/uhttp_workers.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.3.0
+Version: 1.4.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -513,6 +513,43 @@ class MyDispatcher(_workers.Dispatcher):
 `pending` is a `_PendingRequest` with `client` (original connection) and `pool` (source pool).
 Requests with `request_id=-1` are ignored by the dispatcher when the worker responds.
 
+`on_response()` fires only for the happy path (handler returned a response). For lifecycle
+cleanup that must run regardless of outcome — timeouts, client disconnects, shutdown — use
+`on_pending_removed()` (see below).
+
+## Request Lifecycle Hook
+
+Override `on_pending_removed(request_id, pending, reason)` on the dispatcher when you keep
+side-state keyed by `request_id` and need it cleaned up exactly once, no matter how the
+request ended:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def on_pending_removed(self, request_id, pending, reason):
+        self._side_state.pop(request_id, None)
+        if reason == _workers.PENDING_TIMEOUT:
+            self._metrics.timeouts += 1
+```
+
+Reason is one of:
+
+| Constant | When |
+|---|---|
+| `PENDING_COMPLETED` | Handler returned a response, client got it. `on_response()` runs first. |
+| `PENDING_TIMEOUT` | Request exceeded `pool.timeout`; client got 504. Worker may still be processing. |
+| `PENDING_DISCONNECTED` | Client disconnected mid-stream; worker was notified via control queue (race possible). |
+| `PENDING_STREAM_CLOSED` | Worker ended the SSE stream cleanly. |
+| `PENDING_SHUTDOWN` | Dispatcher is shutting down; client got 503. |
+
+The hook is invoked after the client-facing action (respond / disconnect / control queue put)
+so dispatcher state is finalized when it runs. Exceptions raised by the hook are logged at
+`LOG_ERROR` and swallowed — they will not crash the dispatcher loop.
+
+Override `on_response()` if you only care about the happy path (e.g. cross-pool forwarding).
+Override `on_pending_removed()` if you need exactly-once cleanup. Overriding both is allowed
+but discouraged — for the `PENDING_COMPLETED` reason, `on_response()` is called immediately
+before `on_pending_removed()`.
+
 ## Dispatcher Idle Hook
 
 Override `on_idle()` on the dispatcher for periodic background tasks — called on each `select()` timeout (every `SELECT_TIMEOUT` seconds, default 1s):