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

{uhttp_workers-1.2.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.2.0
+Version: 1.4.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -234,6 +234,21 @@ class MyWorker(_workers.Worker):
 
 Extra keyword arguments from `WorkerPool(...)` are available as `self.kwargs`.
 
+### Teardown
+
+`teardown()` is called once when the worker process is stopping — use it to release resources:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self.db = connect_db()
+
+    def teardown(self):
+        self.db.close()
+```
+
+Called after the run loop exits (clean stop, orphan detection, or pipe close), before the process terminates. Exceptions are logged but do not block shutdown.
+
 ### Configuration Updates
 
 Dispatcher can send configuration to workers at runtime via per-worker control queues:
@@ -278,10 +293,29 @@ def process(self, request):
     # return data with status
     return {'error': 'not found'}, 404
 
+    # return data with status and headers
+    return {'ok': True}, 200, {'X-Custom': 'value'}
+
+    # return Response object — full control (headers, cookies)
+    return _workers.Response(
+        None,  # request_id is set automatically
+        data={'ok': True},
+        headers={'X-Custom': 'value'},
+        cookies={'session': 'abc123'})
+
     # defer response — worker continues accepting requests
     return _workers.DEFERRED
 ```
 
+`request.respond()` (for deferred responses) also accepts `headers` and `cookies`:
+
+```python
+request.respond(
+    data={'result': 'done'},
+    headers={'X-Job-Id': '42'},
+    cookies={'session': 'abc'})
+```
+
 ### Deferred Responses
 
 Return `DEFERRED` to skip immediate response. The worker stays in the select loop, accepts new requests, and sends the response later via `request.respond()`:
@@ -432,6 +466,17 @@ Return `(data, status)` tuple to reject, or `None` to continue. You can also rai
 
 `RejectRequest` accepts optional `data` (default: `{'error': 'Rejected'}`) and `status` (default: `403`).
 
+`RejectRequest` can also be raised from request handlers — useful for access control within individual endpoints:
+
+```python
+    @_workers.api('/admin/users', 'GET')
+    def admin_users(self, request):
+        if not self.is_admin(request):
+            raise _workers.RejectRequest(
+                data={'error': 'admin only'}, status=403)
+        return {'users': self.list_users()}
+```
+
 ### Error Handling
 
 Override `on_request_error()` on the worker to customize error handling when a request handler raises an exception:
@@ -468,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):
@@ -523,6 +605,20 @@ class MyWorker(_workers.Worker):
 
 Log messages are sent to the dispatcher via the shared response queue and printed in the dispatcher process — no interleaved output from multiple processes.
 
+The dispatcher itself also has a `self.log` Logger that writes directly via `on_log()` (no queue), so it can be used at any time — including before workers are started:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.log.info("Dispatcher starting on port %d", self._port)
+
+    def on_idle(self):
+        self.log.debug("idle tick")
+```
+
+Set dispatcher log level via constructor: `Dispatcher(log_level=LOG_DEBUG, ...)` (default `LOG_INFO`).
+
 **Log levels:** `LOG_DEBUG` (10), `LOG_INFO` (20), `LOG_WARNING` (30), `LOG_ERROR` (40), `LOG_CRITICAL` (50)
 
 Check current level with `is_*` properties to skip expensive formatting:

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

@@ -220,6 +220,21 @@ class MyWorker(_workers.Worker):
 
 Extra keyword arguments from `WorkerPool(...)` are available as `self.kwargs`.
 
+### Teardown
+
+`teardown()` is called once when the worker process is stopping — use it to release resources:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self.db = connect_db()
+
+    def teardown(self):
+        self.db.close()
+```
+
+Called after the run loop exits (clean stop, orphan detection, or pipe close), before the process terminates. Exceptions are logged but do not block shutdown.
+
 ### Configuration Updates
 
 Dispatcher can send configuration to workers at runtime via per-worker control queues:
@@ -264,10 +279,29 @@ def process(self, request):
     # return data with status
     return {'error': 'not found'}, 404
 
+    # return data with status and headers
+    return {'ok': True}, 200, {'X-Custom': 'value'}
+
+    # return Response object — full control (headers, cookies)
+    return _workers.Response(
+        None,  # request_id is set automatically
+        data={'ok': True},
+        headers={'X-Custom': 'value'},
+        cookies={'session': 'abc123'})
+
     # defer response — worker continues accepting requests
     return _workers.DEFERRED
 ```
 
+`request.respond()` (for deferred responses) also accepts `headers` and `cookies`:
+
+```python
+request.respond(
+    data={'result': 'done'},
+    headers={'X-Job-Id': '42'},
+    cookies={'session': 'abc'})
+```
+
 ### Deferred Responses
 
 Return `DEFERRED` to skip immediate response. The worker stays in the select loop, accepts new requests, and sends the response later via `request.respond()`:
@@ -418,6 +452,17 @@ Return `(data, status)` tuple to reject, or `None` to continue. You can also rai
 
 `RejectRequest` accepts optional `data` (default: `{'error': 'Rejected'}`) and `status` (default: `403`).
 
+`RejectRequest` can also be raised from request handlers — useful for access control within individual endpoints:
+
+```python
+    @_workers.api('/admin/users', 'GET')
+    def admin_users(self, request):
+        if not self.is_admin(request):
+            raise _workers.RejectRequest(
+                data={'error': 'admin only'}, status=403)
+        return {'users': self.list_users()}
+```
+
 ### Error Handling
 
 Override `on_request_error()` on the worker to customize error handling when a request handler raises an exception:
@@ -454,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):
@@ -509,6 +591,20 @@ class MyWorker(_workers.Worker):
 
 Log messages are sent to the dispatcher via the shared response queue and printed in the dispatcher process — no interleaved output from multiple processes.
 
+The dispatcher itself also has a `self.log` Logger that writes directly via `on_log()` (no queue), so it can be used at any time — including before workers are started:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.log.info("Dispatcher starting on port %d", self._port)
+
+    def on_idle(self):
+        self.log.debug("idle tick")
+```
+
+Set dispatcher log level via constructor: `Dispatcher(log_level=LOG_DEBUG, ...)` (default `LOG_INFO`).
+
 **Log levels:** `LOG_DEBUG` (10), `LOG_INFO` (20), `LOG_WARNING` (30), `LOG_ERROR` (40), `LOG_CRITICAL` (50)
 
 Check current level with `is_*` properties to skip expensive formatting:

{uhttp_workers-1.2.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.2.0 → uhttp_workers-1.4.0}/tests/test_worker.py

@@ -124,6 +124,14 @@ class RejectWorker(Worker):
         return {'data': 'ok'}
 
 
+class RejectFromHandlerWorker(Worker):
+    """Worker where handler raises RejectRequest."""
+
+    @api('/protected', 'GET')
+    def protected(self, request):
+        raise RejectRequest(data={'error': 'no access'}, status=403)
+
+
 class FailCheckWorker(Worker):
     """Worker with do_check that raises unexpected exception."""
 
@@ -163,6 +171,15 @@ class TestWorkerDoCheck(unittest.TestCase):
         resp = worker._handle_request(req)
         self.assertEqual(resp.status, 403)
 
+    def test_reject_from_handler(self):
+        queues = [mp.Queue() for _ in range(3)]
+        worker = RejectFromHandlerWorker(0, *queues)
+        worker._build_routes()
+        req = Request(1, 'GET', '/protected')
+        resp = worker._handle_request(req)
+        self.assertEqual(resp.status, 403)
+        self.assertEqual(resp.data, {'error': 'no access'})
+
     def test_do_check_exception(self):
         queues = [mp.Queue() for _ in range(3)]
         worker = FailCheckWorker(0, *queues)
@@ -558,6 +575,101 @@ class TestSSEWorkerDisconnect(unittest.TestCase):
         self.assertTrue(found)
 
 
+class HeadersCookiesWorker(Worker):
+    """Worker that returns headers/cookies in various ways."""
+
+    @api('/three-tuple', 'GET')
+    def three_tuple(self, request):
+        return {'ok': True}, 201, {'X-Custom': 'val'}
+
+    @api('/response-obj', 'GET')
+    def response_obj(self, request):
+        return Response(
+            None, data={'ok': True}, status=200,
+            headers={'X-Custom': 'val'},
+            cookies={'session': 'abc'})
+
+    @api('/two-tuple', 'GET')
+    def two_tuple(self, request):
+        return {'ok': True}, 202
+
+
+class TestResponseHeadersCookies(unittest.TestCase):
+
+    def setUp(self):
+        queues = [mp.Queue() for _ in range(3)]
+        self.worker = HeadersCookiesWorker(0, *queues)
+        self.worker._build_routes()
+
+    def test_three_tuple(self):
+        req = Request(1, 'GET', '/three-tuple')
+        resp = self.worker._handle_request(req)
+        self.assertEqual(resp.status, 201)
+        self.assertEqual(resp.data, {'ok': True})
+        self.assertEqual(resp.headers, {'X-Custom': 'val'})
+        self.assertIsNone(resp.cookies)
+
+    def test_response_object(self):
+        req = Request(7, 'GET', '/response-obj')
+        resp = self.worker._handle_request(req)
+        self.assertEqual(resp.request_id, 7)  # auto-set
+        self.assertEqual(resp.headers, {'X-Custom': 'val'})
+        self.assertEqual(resp.cookies, {'session': 'abc'})
+
+    def test_two_tuple_no_headers(self):
+        req = Request(1, 'GET', '/two-tuple')
+        resp = self.worker._handle_request(req)
+        self.assertEqual(resp.status, 202)
+        self.assertIsNone(resp.headers)
+        self.assertIsNone(resp.cookies)
+
+    def test_request_respond_with_cookies(self):
+        queue = mp.Queue()
+        req = Request(5, 'GET', '/x')
+        req._response_queue = queue
+        req.respond(
+            data={'ok': True},
+            headers={'X-H': '1'},
+            cookies={'sid': 'xyz'})
+        msg = queue.get(timeout=1)
+        self.assertEqual(msg[2].headers, {'X-H': '1'})
+        self.assertEqual(msg[2].cookies, {'sid': 'xyz'})
+
+
+class TeardownWorker(Worker):
+    """Worker that signals teardown via response queue."""
+
+    def teardown(self):
+        self._response_queue.put(('TEARDOWN', self.worker_id, None))
+
+
+class TestWorkerTeardown(unittest.TestCase):
+
+    def test_teardown_called_on_stop(self):
+        request_queue = mp.Queue()
+        control_queue = mp.Queue()
+        response_queue = mp.Queue()
+        control_queue.put(None)  # immediate stop
+        worker = TeardownWorker(
+            0, request_queue, control_queue, response_queue)
+        worker.heartbeat_interval = 0.1
+        worker.start()
+        worker.join(timeout=5)
+        self.assertFalse(worker.is_alive())
+        # find TEARDOWN message
+        found = False
+        deadline = time.time() + 2
+        while time.time() < deadline:
+            try:
+                msg = response_queue.get(timeout=0.2)
+            except Exception:
+                break
+            if msg[0] == 'TEARDOWN':
+                found = True
+                break
+        self.assertTrue(found)
+
+
 class PausingWorker(Worker):
     """Worker that pauses after first request."""
 

{uhttp_workers-1.2.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()
 
@@ -236,14 +243,16 @@ class Request:
                 _uhttp_server.parse_cookies(raw) if raw else {})
         return self._cookies
 
-    def respond(self, data=None, status=200):
+    def respond(self, data=None, status=200, headers=None, cookies=None):
         """Send deferred response for this request.
 
         Use after returning DEFERRED from handler.
         """
         self._response_queue.put(
             (MSG_RESPONSE, self.request_id,
-             Response(self.request_id, data=data, status=status)))
+             Response(
+                 self.request_id, data=data, status=status,
+                 headers=headers, cookies=cookies)))
 
     def response_stream(self, content_type=None, headers=None, cookies=None):
         """Start streaming response.
@@ -287,16 +296,19 @@ class Response:
         status: HTTP status code.
         data: Response body — dict (JSON), bytes (binary), or None.
         headers: Response headers dict, or None.
+        cookies: Response cookies dict, or None.
     """
 
-    __slots__ = ('request_id', 'status', 'data', 'headers')
+    __slots__ = ('request_id', 'status', 'data', 'headers', 'cookies')
 
     def __init__(
-            self, request_id, data=None, status=200, headers=None):
+            self, request_id, data=None, status=200,
+            headers=None, cookies=None):
         self.request_id = request_id
         self.status = status
         self.data = data
         self.headers = headers
+        self.cookies = cookies
 
 
 # API Handler
@@ -331,10 +343,20 @@ class Logger:
         level: Minimum log level.
     """
 
-    def __init__(self, name, queue, level=LOG_WARNING):
+    def __init__(self, name, queue=None, level=LOG_WARNING, sink=None):
+        """Logger that sends to dispatcher via queue or direct callable.
+
+        Args:
+            name: Logger name.
+            queue: multiprocessing.Queue (worker context).
+            level: Minimum log level.
+            sink: Callable(name, level, message) — used instead of queue
+                (e.g., dispatcher's on_log).
+        """
         self.name = name
         self.level = level
         self._queue = queue
+        self._sink = sink
 
     @property
     def is_debug(self):
@@ -359,7 +381,10 @@ class Logger:
                 message = message.format(**kwargs) if kwargs else message
             except (TypeError, KeyError, IndexError, ValueError):
                 message = f"{msg} {args} {kwargs}"
-            self._queue.put((MSG_LOG, self.name, level, message))
+            if self._sink is not None:
+                self._sink(self.name, level, message)
+            else:
+                self._queue.put((MSG_LOG, self.name, level, message))
 
     def critical(self, msg, *args, **kwargs):
         self._log(LOG_CRITICAL, msg, *args, **kwargs)
@@ -507,6 +532,14 @@ class Worker(_mp.Process):
         Extra kwargs from WorkerPool are available as self.kwargs.
         """
 
+    def teardown(self):
+        """Called once when worker process is stopping.
+
+        Override to clean up resources (close DB connections, flush buffers).
+        Called after the run loop exits, before the process terminates.
+        Exceptions are logged but do not prevent shutdown.
+        """
+
     def pause(self):
         """Stop accepting new requests from queue.
 
@@ -618,11 +651,25 @@ class Worker(_mp.Process):
             result = handler(request)
             if result is DEFERRED:
                 return None
+            if isinstance(result, Response):
+                result.request_id = request.request_id
+                return result
+            headers = None
             if isinstance(result, tuple):
-                data, status = result
+                if len(result) == 3:
+                    data, status, headers = result
+                else:
+                    data, status = result
             else:
                 data, status = result, 200
-            return Response(request.request_id, data=data, status=status)
+            return Response(
+                request.request_id, data=data,
+                status=status, headers=headers)
+        except RejectRequest as err:
+            return Response(
+                request.request_id,
+                data=err.data,
+                status=err.status)
         except Exception as err:
             return self.on_request_error(request, err)
 
@@ -656,6 +703,16 @@ class Worker(_mp.Process):
             return
         req_reader = self._request_queue._reader
         ctl_reader = self._control_queue._reader
+        try:
+            self._run_loop(req_reader, ctl_reader)
+        finally:
+            try:
+                self.teardown()
+            except Exception:
+                self.log.error(
+                    "teardown() failed:\n%s", _traceback.format_exc())
+
+    def _run_loop(self, req_reader, ctl_reader):
         while self._running:
             read_fds = [ctl_reader] + list(self._readers)
             if self._accepting:
@@ -941,7 +998,7 @@ class Dispatcher:
     def __init__(
             self, port=8080, address='0.0.0.0', pools=None,
             static_routes=None, shutdown_timeout=10,
-            max_pending=1000, **kwargs):
+            max_pending=1000, log_level=LOG_INFO, **kwargs):
         """Initialize dispatcher.
 
         Args:
@@ -974,6 +1031,10 @@ class Dispatcher:
         self._writers = {}
         self._log_is_tty = _sys.stderr.isatty()
         self._running = False
+        self.log = Logger(
+            type(self).__name__,
+            sink=self.on_log,
+            level=log_level)
         self._build_sync_routes()
 
     def _build_sync_routes(self):
@@ -1020,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.
 
@@ -1170,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)
@@ -1177,8 +1267,11 @@ class Dispatcher:
                 pending.client.respond(
                     response.data,
                     status=response.status,
-                    headers=response.headers)
+                    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."""
@@ -1188,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."""
@@ -1214,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."""
@@ -1340,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.2.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.2.0
+Version: 1.4.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -234,6 +234,21 @@ class MyWorker(_workers.Worker):
 
 Extra keyword arguments from `WorkerPool(...)` are available as `self.kwargs`.
 
+### Teardown
+
+`teardown()` is called once when the worker process is stopping — use it to release resources:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self.db = connect_db()
+
+    def teardown(self):
+        self.db.close()
+```
+
+Called after the run loop exits (clean stop, orphan detection, or pipe close), before the process terminates. Exceptions are logged but do not block shutdown.
+
 ### Configuration Updates
 
 Dispatcher can send configuration to workers at runtime via per-worker control queues:
@@ -278,10 +293,29 @@ def process(self, request):
     # return data with status
     return {'error': 'not found'}, 404
 
+    # return data with status and headers
+    return {'ok': True}, 200, {'X-Custom': 'value'}
+
+    # return Response object — full control (headers, cookies)
+    return _workers.Response(
+        None,  # request_id is set automatically
+        data={'ok': True},
+        headers={'X-Custom': 'value'},
+        cookies={'session': 'abc123'})
+
     # defer response — worker continues accepting requests
     return _workers.DEFERRED
 ```
 
+`request.respond()` (for deferred responses) also accepts `headers` and `cookies`:
+
+```python
+request.respond(
+    data={'result': 'done'},
+    headers={'X-Job-Id': '42'},
+    cookies={'session': 'abc'})
+```
+
 ### Deferred Responses
 
 Return `DEFERRED` to skip immediate response. The worker stays in the select loop, accepts new requests, and sends the response later via `request.respond()`:
@@ -432,6 +466,17 @@ Return `(data, status)` tuple to reject, or `None` to continue. You can also rai
 
 `RejectRequest` accepts optional `data` (default: `{'error': 'Rejected'}`) and `status` (default: `403`).
 
+`RejectRequest` can also be raised from request handlers — useful for access control within individual endpoints:
+
+```python
+    @_workers.api('/admin/users', 'GET')
+    def admin_users(self, request):
+        if not self.is_admin(request):
+            raise _workers.RejectRequest(
+                data={'error': 'admin only'}, status=403)
+        return {'users': self.list_users()}
+```
+
 ### Error Handling
 
 Override `on_request_error()` on the worker to customize error handling when a request handler raises an exception:
@@ -468,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):
@@ -523,6 +605,20 @@ class MyWorker(_workers.Worker):
 
 Log messages are sent to the dispatcher via the shared response queue and printed in the dispatcher process — no interleaved output from multiple processes.
 
+The dispatcher itself also has a `self.log` Logger that writes directly via `on_log()` (no queue), so it can be used at any time — including before workers are started:
+
+```python
+class MyDispatcher(_workers.Dispatcher):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.log.info("Dispatcher starting on port %d", self._port)
+
+    def on_idle(self):
+        self.log.debug("idle tick")
+```
+
+Set dispatcher log level via constructor: `Dispatcher(log_level=LOG_DEBUG, ...)` (default `LOG_INFO`).
+
 **Log levels:** `LOG_DEBUG` (10), `LOG_INFO` (20), `LOG_WARNING` (30), `LOG_ERROR` (40), `LOG_CRITICAL` (50)
 
 Check current level with `is_*` properties to skip expensive formatting: