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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.3.0
+Version: 1.5.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -10,7 +10,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: POSIX
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: uhttp-server
+Requires-Dist: uhttp-server>=2.5.2
 
 # uhttp-workers
 
@@ -384,6 +384,31 @@ Available streaming methods on `Request`:
 
 Streaming requests are excluded from dispatcher timeout expiration. When the client disconnects, the dispatcher notifies the worker via `on_disconnect(request_id)`.
 
+### NDJSON Streaming
+
+Stream JSON objects line-by-line (`application/x-ndjson`) — one JSON value per line, terminated by `\n`. Useful for incremental APIs that aren't event-shaped (long lists, log tails, progress updates):
+
+```python
+class MyWorker(_workers.Worker):
+    @_workers.api('/devices/scan', 'GET')
+    def scan(self, request):
+        request.response_ndjson()
+        for device in self.discover_devices():
+            request.send_ndjson({'id': device.id, 'name': device.name})
+        request.response_stream_end()
+        return _workers.DEFERRED
+```
+
+NDJSON methods on `Request`:
+
+| Method | Description |
+|--------|-------------|
+| `response_ndjson(headers, cookies)` | Start NDJSON stream (wrapper over `response_stream` with `application/x-ndjson`) |
+| `send_ndjson(obj)` | Send one JSON-serializable value as a line |
+| `response_stream_end()` | End stream and close connection (shared with SSE) |
+
+Same lifecycle as SSE: excluded from timeout expiration, client disconnect triggers `on_disconnect(request_id)`.
+
 ### Flow Control
 
 Workers can stop accepting new requests when busy. Requests stay in the shared pool queue for other workers to pick up:
@@ -513,6 +538,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.5.0}/README.md

@@ -370,6 +370,31 @@ Available streaming methods on `Request`:
 
 Streaming requests are excluded from dispatcher timeout expiration. When the client disconnects, the dispatcher notifies the worker via `on_disconnect(request_id)`.
 
+### NDJSON Streaming
+
+Stream JSON objects line-by-line (`application/x-ndjson`) — one JSON value per line, terminated by `\n`. Useful for incremental APIs that aren't event-shaped (long lists, log tails, progress updates):
+
+```python
+class MyWorker(_workers.Worker):
+    @_workers.api('/devices/scan', 'GET')
+    def scan(self, request):
+        request.response_ndjson()
+        for device in self.discover_devices():
+            request.send_ndjson({'id': device.id, 'name': device.name})
+        request.response_stream_end()
+        return _workers.DEFERRED
+```
+
+NDJSON methods on `Request`:
+
+| Method | Description |
+|--------|-------------|
+| `response_ndjson(headers, cookies)` | Start NDJSON stream (wrapper over `response_stream` with `application/x-ndjson`) |
+| `send_ndjson(obj)` | Send one JSON-serializable value as a line |
+| `response_stream_end()` | End stream and close connection (shared with SSE) |
+
+Same lifecycle as SSE: excluded from timeout expiration, client disconnect triggers `on_disconnect(request_id)`.
+
 ### Flow Control
 
 Workers can stop accepting new requests when busy. Requests stay in the shared pool queue for other workers to pick up:
@@ -499,6 +524,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.5.0}/pyproject.toml

@@ -13,7 +13,7 @@ authors = [
 license = "MIT"
 requires-python = ">=3.10"
 dependencies = [
-    "uhttp-server",
+    "uhttp-server>=2.5.2",
 ]
 classifiers = [
     "Programming Language :: Python :: 3",

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

@@ -10,8 +10,11 @@ from uhttp.workers import (
     Dispatcher, Worker, WorkerPool, Request, Response,
     api, sync, RejectRequest,
     MSG_RESPONSE, MSG_HEARTBEAT,
-    MSG_SSE_OPEN, MSG_SSE_EVENT, MSG_SSE_CLOSE,
+    MSG_SSE_OPEN, MSG_SSE_EVENT, MSG_SSE_CLOSE, MSG_NDJSON,
     CTL_DISCONNECT,
+    PENDING_COMPLETED, PENDING_TIMEOUT, PENDING_DISCONNECTED,
+    PENDING_STREAM_CLOSED, PENDING_SHUTDOWN,
+    LOG_ERROR,
     _PendingRequest,
 )
 
@@ -75,6 +78,12 @@ class MockClient:
         self._chunks.append(data)
         return getattr(self, '_connected', True)
 
+    def send_ndjson(self, obj):
+        if not hasattr(self, '_ndjson'):
+            self._ndjson = []
+        self._ndjson.append(obj)
+        return getattr(self, '_connected', True)
+
     def response_stream_end(self):
         self.stream_ended = True
 
@@ -544,6 +553,42 @@ class TestDispatcherSSE(unittest.TestCase):
         # non-streaming should be expired
         self.assertNotIn(1, d._pending)
 
+    def test_ndjson_send(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/stream')
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        d._pending[1] = pending
+        d._process_response(
+            (MSG_NDJSON, 1, {'devices': [1, 2, 3]}))
+        self.assertEqual(len(client._ndjson), 1)
+        self.assertEqual(client._ndjson[0], {'devices': [1, 2, 3]})
+        # still pending — stream open
+        self.assertIn(1, d._pending)
+
+    def test_ndjson_client_disconnect(self):
+        d, pool = self._make_dispatcher()
+        pool.start(d._response_queue)
+        client = MockClient('GET', '/api/stream')
+        client._connected = False
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        pending.worker_id = 0
+        d._pending[1] = pending
+        d._process_response((MSG_NDJSON, 1, {'x': 1}))
+        # removed from pending
+        self.assertNotIn(1, d._pending)
+        # CTL_DISCONNECT sent to worker's control queue
+        msg = pool._control_queues[0].get(timeout=1)
+        self.assertEqual(msg, (CTL_DISCONNECT, 1))
+        pool.shutdown(timeout=2)
+
+    def test_ndjson_ignored_after_close(self):
+        d, pool = self._make_dispatcher()
+        # no pending request with id 99
+        d._process_response((MSG_NDJSON, 99, {'x': 1}))
+        # should not raise, just ignore
+
     def test_sse_event_ignored_after_close(self):
         d, pool = self._make_dispatcher()
         # no pending request with id 99
@@ -552,5 +597,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.5.0}/tests/test_worker.py

@@ -8,7 +8,7 @@ from uhttp.workers import (
     Worker, Request, Response, api, RejectRequest, DEFERRED,
     Logger, LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERROR,
     MSG_RESPONSE, MSG_HEARTBEAT,
-    MSG_SSE_OPEN, MSG_SSE_EVENT, MSG_SSE_CLOSE,
+    MSG_SSE_OPEN, MSG_SSE_EVENT, MSG_SSE_CLOSE, MSG_NDJSON,
     CTL_DISCONNECT)
 
 
@@ -520,6 +520,38 @@ class TestSSERequest(unittest.TestCase):
         self.assertIsNone(msg[4])
         self.assertIsNone(msg[5])
 
+    def test_response_ndjson(self):
+        self.req.response_ndjson(
+            headers={'X-Custom': '1'},
+            cookies={'sid': 'abc'})
+        msg = self.queue.get(timeout=1)
+        self.assertEqual(msg[0], MSG_SSE_OPEN)
+        self.assertEqual(msg[1], 10)
+        self.assertEqual(msg[2], 'application/x-ndjson')
+        self.assertEqual(msg[3], {'X-Custom': '1'})
+        self.assertEqual(msg[4], {'sid': 'abc'})
+
+    def test_response_ndjson_defaults(self):
+        self.req.response_ndjson()
+        msg = self.queue.get(timeout=1)
+        self.assertEqual(msg[0], MSG_SSE_OPEN)
+        self.assertEqual(msg[2], 'application/x-ndjson')
+        self.assertIsNone(msg[3])
+        self.assertIsNone(msg[4])
+
+    def test_send_ndjson(self):
+        self.req.send_ndjson({'devices': [1, 2, 3]})
+        msg = self.queue.get(timeout=1)
+        self.assertEqual(msg[0], MSG_NDJSON)
+        self.assertEqual(msg[1], 10)
+        self.assertEqual(msg[2], {'devices': [1, 2, 3]})
+
+    def test_send_ndjson_keepalive(self):
+        self.req.send_ndjson({})
+        msg = self.queue.get(timeout=1)
+        self.assertEqual(msg[0], MSG_NDJSON)
+        self.assertEqual(msg[2], {})
+
     def test_response_stream_end(self):
         self.req.response_stream_end()
         msg = self.queue.get(timeout=1)

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

@@ -23,12 +23,20 @@ MSG_LOG = 'LOG'
 MSG_SSE_OPEN = 'SSE_OPEN'
 MSG_SSE_EVENT = 'SSE_EVENT'
 MSG_SSE_CLOSE = 'SSE_CLOSE'
+MSG_NDJSON = 'NDJSON'
 
 # Worker control messages
 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()
 
@@ -275,6 +283,25 @@ class Request:
             (MSG_SSE_EVENT, self.request_id,
              data, event, event_id, retry))
 
+    def response_ndjson(self, headers=None, cookies=None):
+        """Start NDJSON streaming response (application/x-ndjson).
+
+        Thin wrapper over response_stream(). Use with DEFERRED — call from
+        handler, then send_ndjson() later. Call response_stream_end() to finish.
+        """
+        self._response_queue.put(
+            (MSG_SSE_OPEN, self.request_id,
+             'application/x-ndjson', headers, cookies))
+
+    def send_ndjson(self, obj):
+        """Send one JSON-serializable object as an NDJSON line.
+
+        Args:
+            obj: any JSON-serializable value (dict/list/str/int/float/bool/None)
+        """
+        self._response_queue.put(
+            (MSG_NDJSON, self.request_id, obj))
+
     def response_stream_end(self):
         """End streaming response and close connection."""
         self._response_queue.put(
@@ -1074,12 +1101,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.
 
@@ -1219,11 +1273,20 @@ class Dispatcher:
                         event_id=event_id, retry=retry)
                 if not ok:
                     self._stream_disconnected(request_id, pending)
+        elif msg_type == MSG_NDJSON:
+            _, request_id, obj = msg
+            pending = self._pending.get(request_id)
+            if pending is not None:
+                ok = pending.client.send_ndjson(obj)
+                if not ok:
+                    self._stream_disconnected(request_id, pending)
         elif msg_type == MSG_SSE_CLOSE:
             _, request_id = msg
             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 +1297,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 +1308,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 +1346,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 +1474,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.5.0/uhttp_workers.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.3.0
+Version: 1.5.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -10,7 +10,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: POSIX
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: uhttp-server
+Requires-Dist: uhttp-server>=2.5.2
 
 # uhttp-workers
 
@@ -384,6 +384,31 @@ Available streaming methods on `Request`:
 
 Streaming requests are excluded from dispatcher timeout expiration. When the client disconnects, the dispatcher notifies the worker via `on_disconnect(request_id)`.
 
+### NDJSON Streaming
+
+Stream JSON objects line-by-line (`application/x-ndjson`) — one JSON value per line, terminated by `\n`. Useful for incremental APIs that aren't event-shaped (long lists, log tails, progress updates):
+
+```python
+class MyWorker(_workers.Worker):
+    @_workers.api('/devices/scan', 'GET')
+    def scan(self, request):
+        request.response_ndjson()
+        for device in self.discover_devices():
+            request.send_ndjson({'id': device.id, 'name': device.name})
+        request.response_stream_end()
+        return _workers.DEFERRED
+```
+
+NDJSON methods on `Request`:
+
+| Method | Description |
+|--------|-------------|
+| `response_ndjson(headers, cookies)` | Start NDJSON stream (wrapper over `response_stream` with `application/x-ndjson`) |
+| `send_ndjson(obj)` | Send one JSON-serializable value as a line |
+| `response_stream_end()` | End stream and close connection (shared with SSE) |
+
+Same lifecycle as SSE: excluded from timeout expiration, client disconnect triggers `on_disconnect(request_id)`.
+
 ### Flow Control
 
 Workers can stop accepting new requests when busy. Requests stay in the shared pool queue for other workers to pick up:
@@ -513,6 +538,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.5.0/uhttp_workers.egg-info/requires.txt

@@ -0,0 +1 @@
+uhttp-server>=2.5.2

uhttp_workers-1.3.0/uhttp_workers.egg-info/requires.txt

@@ -1 +0,0 @@
-uhttp-server