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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.1.0
+Version: 1.3.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:
@@ -277,8 +292,120 @@ 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()`:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self._jobs = {}
+
+    @_workers.api('/process', 'POST')
+    def process(self, request):
+        job_id = start_background_work(request.data)
+        self._jobs[job_id] = request
+        return _workers.DEFERRED
+
+    def on_work_done(self, job_id, result):
+        request = self._jobs.pop(job_id)
+        request.respond(data={'result': result})
+```
+
+Note: deferred requests are still subject to dispatcher timeout — call `self.keep_alive()` periodically to prevent 504.
+
+### Keep Alive
+
+Call `self.keep_alive()` during long operations to reset both the request timeout and stuck worker detection:
+
+```python
+@_workers.api('/export', 'POST')
+def export(self, request):
+    for chunk in generate_large_export():
+        self.keep_alive()
+    return {'status': 'done'}
+```
+
+### Server-Sent Events (SSE)
+
+Stream events to clients using the same API as `uhttp.server.Client`:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self._subscribers = {}
+
+    @_workers.api('/events', 'GET')
+    def events(self, request):
+        request.response_stream()  # sends headers, keeps connection open
+        self._subscribers[request.request_id] = request
+        return _workers.DEFERRED
+
+    def notify(self, data):
+        for req in self._subscribers.values():
+            req.send_event(data=data, event='update')
+
+    def on_disconnect(self, request_id):
+        self._subscribers.pop(request_id, None)
+```
+
+Available streaming methods on `Request`:
+
+| Method | Description |
+|--------|-------------|
+| `response_stream(content_type, headers, cookies)` | Start streaming (default: `text/event-stream`) |
+| `send_event(data, event, event_id, retry)` | Send SSE event |
+| `send_chunk(data)` | Send raw data chunk |
+| `response_stream_end()` | End stream and close connection |
+
+Streaming requests are excluded from dispatcher timeout expiration. When the client disconnects, the dispatcher notifies the worker via `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:
+
+```python
+class MyWorker(_workers.Worker):
+    @_workers.api('/events', 'GET')
+    def subscribe(self, request):
+        request.response_stream()
+        self._subscribers[request.request_id] = request
+        if len(self._subscribers) >= 100:
+            self.pause()
+        return _workers.DEFERRED
+
+    def on_disconnect(self, request_id):
+        self._subscribers.pop(request_id, None)
+        if not self._accepting and len(self._subscribers) < 100:
+            self.resume()
+```
+
+`pause()` excludes the request queue from `select()` — the worker continues processing control messages, custom fd events, and `on_idle()`. `resume()` re-enables request acceptance.
+
 ## URL Patterns
 
 Dispatcher uses prefix matching to route requests to pools:
@@ -339,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:
@@ -430,6 +568,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.1.0 → uhttp_workers-1.3.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:
@@ -263,8 +278,120 @@ 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()`:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self._jobs = {}
+
+    @_workers.api('/process', 'POST')
+    def process(self, request):
+        job_id = start_background_work(request.data)
+        self._jobs[job_id] = request
+        return _workers.DEFERRED
+
+    def on_work_done(self, job_id, result):
+        request = self._jobs.pop(job_id)
+        request.respond(data={'result': result})
+```
+
+Note: deferred requests are still subject to dispatcher timeout — call `self.keep_alive()` periodically to prevent 504.
+
+### Keep Alive
+
+Call `self.keep_alive()` during long operations to reset both the request timeout and stuck worker detection:
+
+```python
+@_workers.api('/export', 'POST')
+def export(self, request):
+    for chunk in generate_large_export():
+        self.keep_alive()
+    return {'status': 'done'}
+```
+
+### Server-Sent Events (SSE)
+
+Stream events to clients using the same API as `uhttp.server.Client`:
+
+```python
+class MyWorker(_workers.Worker):
+    def setup(self):
+        self._subscribers = {}
+
+    @_workers.api('/events', 'GET')
+    def events(self, request):
+        request.response_stream()  # sends headers, keeps connection open
+        self._subscribers[request.request_id] = request
+        return _workers.DEFERRED
+
+    def notify(self, data):
+        for req in self._subscribers.values():
+            req.send_event(data=data, event='update')
+
+    def on_disconnect(self, request_id):
+        self._subscribers.pop(request_id, None)
+```
+
+Available streaming methods on `Request`:
+
+| Method | Description |
+|--------|-------------|
+| `response_stream(content_type, headers, cookies)` | Start streaming (default: `text/event-stream`) |
+| `send_event(data, event, event_id, retry)` | Send SSE event |
+| `send_chunk(data)` | Send raw data chunk |
+| `response_stream_end()` | End stream and close connection |
+
+Streaming requests are excluded from dispatcher timeout expiration. When the client disconnects, the dispatcher notifies the worker via `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:
+
+```python
+class MyWorker(_workers.Worker):
+    @_workers.api('/events', 'GET')
+    def subscribe(self, request):
+        request.response_stream()
+        self._subscribers[request.request_id] = request
+        if len(self._subscribers) >= 100:
+            self.pause()
+        return _workers.DEFERRED
+
+    def on_disconnect(self, request_id):
+        self._subscribers.pop(request_id, None)
+        if not self._accepting and len(self._subscribers) < 100:
+            self.resume()
+```
+
+`pause()` excludes the request queue from `select()` — the worker continues processing control messages, custom fd events, and `on_idle()`. `resume()` re-enables request acceptance.
+
 ## URL Patterns
 
 Dispatcher uses prefix matching to route requests to pools:
@@ -325,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:
@@ -416,6 +554,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.3.0/examples/sse_workers.py

@@ -0,0 +1,80 @@
+"""SSE (Server-Sent Events) example with deferred responses.
+
+Demonstrates:
+- SSE streaming from worker to client
+- Deferred responses (DEFERRED sentinel)
+- Client disconnect handling (on_disconnect)
+- keep_alive() for long operations
+
+Test with:
+    curl -N http://localhost:8080/events
+    curl -N http://localhost:8080/events?channel=news
+    curl -X POST http://localhost:8080/publish -d '{"msg": "hello"}'
+    curl -X POST http://localhost:8080/publish -d '{"channel": "news", "msg": "breaking"}'
+"""
+
+import uhttp.workers as _workers
+
+
+class EventWorker(_workers.Worker):
+    """Worker that manages SSE subscribers and publishes events."""
+
+    def setup(self):
+        self._subscribers = {}  # request_id → (request, channel)
+
+    @_workers.api('/events', 'GET')
+    def subscribe(self, request):
+        channel = (request.query or {}).get('channel', 'default')
+        request.response_stream()
+        request.send_event(
+            data={'status': 'connected', 'channel': channel},
+            event='open')
+        self._subscribers[request.request_id] = (request, channel)
+        if len(self._subscribers) >= self.kwargs.get('max_subscribers', 100):
+            self.pause()
+        return _workers.DEFERRED
+
+    @_workers.api('/publish', 'POST')
+    def publish(self, request):
+        channel = (request.data or {}).get('channel', 'default')
+        msg = (request.data or {}).get('msg', '')
+        count = 0
+        for req, ch in self._subscribers.values():
+            if ch == channel:
+                req.send_event(data={'msg': msg}, event='message')
+                count += 1
+        return {'published': count, 'channel': channel}
+
+    def on_disconnect(self, request_id):
+        sub = self._subscribers.pop(request_id, None)
+        if sub:
+            self.log.info("Client disconnected: %d", request_id)
+            max_subs = self.kwargs.get('max_subscribers', 100)
+            if not self._accepting and len(self._subscribers) < max_subs:
+                self.resume()
+
+    def on_idle(self):
+        # periodic keepalive to all subscribers
+        for req, _ in list(self._subscribers.values()):
+            req.send_event(event='ping')
+
+
+class MyDispatcher(_workers.Dispatcher):
+    @_workers.sync('/health')
+    def health(self, client, path_params):
+        client.respond({'status': 'ok'})
+
+
+def main():
+    pool = _workers.WorkerPool(
+        EventWorker, num_workers=2,
+        log_level=_workers.LOG_INFO,
+        timeout=30)
+    dispatcher = MyDispatcher(
+        port=8080,
+        pools=[pool])
+    dispatcher.run()
+
+
+if __name__ == '__main__':
+    main()

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

@@ -10,6 +10,8 @@ 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,
+    CTL_DISCONNECT,
     _PendingRequest,
 )
 
@@ -52,6 +54,30 @@ class MockClient:
         self.responded = True
         self.file_path = path
 
+    def response_stream(self, content_type=None, headers=None, cookies=None):
+        self.streaming = True
+        self.stream_content_type = content_type
+        self.stream_headers = headers
+        self.stream_cookies = cookies
+        return True
+
+    def send_event(self, data=None, event=None, event_id=None, retry=None):
+        if not hasattr(self, '_events'):
+            self._events = []
+        self._events.append({
+            'data': data, 'event': event,
+            'event_id': event_id, 'retry': retry})
+        return getattr(self, '_connected', True)
+
+    def send_chunk(self, data):
+        if not hasattr(self, '_chunks'):
+            self._chunks = []
+        self._chunks.append(data)
+        return getattr(self, '_connected', True)
+
+    def response_stream_end(self):
+        self.stream_ended = True
+
 
 class TestDispatcherSyncRoutes(unittest.TestCase):
 
@@ -413,5 +439,118 @@ class TestDispatcherRoutePriority(unittest.TestCase):
         self.assertEqual(len(d._pending), 0)
 
 
+class TestDispatcherSSE(unittest.TestCase):
+
+    def _make_dispatcher(self):
+        pool = WorkerPool(DummyWorker, routes=['/api/**'])
+        d = Dispatcher.__new__(Dispatcher)
+        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.on_log = lambda *_: None
+        return d, pool
+
+    def test_sse_open(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/events')
+        pending = _PendingRequest(client, pool)
+        pending.worker_id = 0
+        d._pending[1] = pending
+        d._process_response(
+            (MSG_SSE_OPEN, 1, 'text/event-stream', None, None))
+        self.assertTrue(client.streaming)
+        self.assertEqual(client.stream_content_type, 'text/event-stream')
+        self.assertTrue(pending.streaming)
+        # still in pending
+        self.assertIn(1, d._pending)
+
+    def test_sse_send_event(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/events')
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        d._pending[1] = pending
+        d._process_response(
+            (MSG_SSE_EVENT, 1, {'count': 5}, 'update', '3', None))
+        self.assertEqual(len(client._events), 1)
+        self.assertEqual(client._events[0]['data'], {'count': 5})
+        self.assertEqual(client._events[0]['event'], 'update')
+        self.assertEqual(client._events[0]['event_id'], '3')
+
+    def test_sse_send_chunk(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/stream')
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        d._pending[1] = pending
+        # send_chunk: event/event_id/retry are all None
+        d._process_response(
+            (MSG_SSE_EVENT, 1, b'raw data', None, None, None))
+        self.assertEqual(len(client._chunks), 1)
+        self.assertEqual(client._chunks[0], b'raw data')
+
+    def test_sse_close(self):
+        d, pool = self._make_dispatcher()
+        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)
+        # removed from pending
+        self.assertNotIn(1, d._pending)
+
+    def test_sse_client_disconnect(self):
+        d, pool = self._make_dispatcher()
+        pool.start(d._response_queue)
+        client = MockClient('GET', '/api/events')
+        client._connected = False  # simulate disconnected client
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        pending.worker_id = 0
+        d._pending[1] = pending
+        d._process_response(
+            (MSG_SSE_EVENT, 1, {'data': 'test'}, 'ping', None, None))
+        # 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_streaming_excluded_from_timeout(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/events')
+        pending = _PendingRequest(client, pool)
+        pending.streaming = True
+        pending.timestamp = 0  # very old
+        d._pending[1] = pending
+        d._expire_pending()
+        # streaming request should NOT be expired
+        self.assertIn(1, d._pending)
+
+    def test_non_streaming_expires(self):
+        d, pool = self._make_dispatcher()
+        client = MockClient('GET', '/api/test')
+        pending = _PendingRequest(client, pool)
+        pending.timestamp = 0  # very old
+        d._pending[1] = pending
+        d._expire_pending()
+        # non-streaming should be expired
+        self.assertNotIn(1, d._pending)
+
+    def test_sse_event_ignored_after_close(self):
+        d, pool = self._make_dispatcher()
+        # no pending request with id 99
+        d._process_response(
+            (MSG_SSE_EVENT, 99, {'data': 'test'}, None, None, None))
+        # should not raise, just ignore
+
+
 if __name__ == '__main__':
     unittest.main()