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

{uhttp_workers-1.0.0/uhttp_workers.egg-info → uhttp_workers-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-workers
-Version: 1.0.0
+Version: 1.2.0
 Summary: Multi-process worker dispatcher built on uhttp-server
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -269,6 +269,7 @@ def process(self, request):
     # request.query        — {'page': '1'} or None
     # request.data         — dict (JSON), bytes (binary), or None
     # request.headers      — dict
+    # request.cookies      — dict (lazy-parsed from Cookie header)
     # request.content_type — 'application/json'
 
     # return data (status 200)
@@ -276,8 +277,101 @@ def process(self, request):
 
     # return data with status
     return {'error': 'not found'}, 404
+
+    # defer response — worker continues accepting requests
+    return _workers.DEFERRED
+```
+
+### 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:
@@ -315,6 +409,43 @@ class MyDispatcher(_workers.Dispatcher):
 
 `do_check()` is only called for requests going to worker pools — static files and sync handlers are not affected.
 
+### Worker-Level Validation
+
+Override `do_check()` on the worker — runs before routing to handler:
+
+```python
+class MyWorker(_workers.Worker):
+    def do_check(self, request):
+        token = request.cookies.get('session')
+        if not token:
+            return {'error': 'unauthorized'}, 401
+```
+
+Return `(data, status)` tuple to reject, or `None` to continue. You can also raise `RejectRequest`:
+
+```python
+    def do_check(self, request):
+        if not self.validate_token(request.cookies.get('session')):
+            raise _workers.RejectRequest(
+                data={'error': 'forbidden'}, status=403)
+```
+
+`RejectRequest` accepts optional `data` (default: `{'error': 'Rejected'}`) and `status` (default: `403`).
+
+### Error Handling
+
+Override `on_request_error()` on the worker to customize error handling when a request handler raises an exception:
+
+```python
+class MyWorker(_workers.Worker):
+    def on_request_error(self, request, err):
+        if isinstance(err, DatabaseError):
+            self.db.reconnect()
+        return super().on_request_error(request, err)
+```
+
+Default behavior logs the error with traceback and returns 500.
+
 ## Post-Response Hook
 
 Override `on_response()` on the dispatcher to post-process after a response is sent to the client — e.g., forward data to another worker pool:
@@ -394,6 +525,15 @@ Log messages are sent to the dispatcher via the shared response queue and printe
 
 **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:
+
+```python
+if self.log.is_debug:
+    self.log.debug("Details: %s", expensive_computation())
+```
+
+Available: `is_debug`, `is_info`, `is_warning`, `is_error`.
+
 Set minimum level per pool:
 
 ```python

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

@@ -255,6 +255,7 @@ def process(self, request):
     # request.query        — {'page': '1'} or None
     # request.data         — dict (JSON), bytes (binary), or None
     # request.headers      — dict
+    # request.cookies      — dict (lazy-parsed from Cookie header)
     # request.content_type — 'application/json'
 
     # return data (status 200)
@@ -262,8 +263,101 @@ def process(self, request):
 
     # return data with status
     return {'error': 'not found'}, 404
+
+    # defer response — worker continues accepting requests
+    return _workers.DEFERRED
+```
+
+### 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:
@@ -301,6 +395,43 @@ class MyDispatcher(_workers.Dispatcher):
 
 `do_check()` is only called for requests going to worker pools — static files and sync handlers are not affected.
 
+### Worker-Level Validation
+
+Override `do_check()` on the worker — runs before routing to handler:
+
+```python
+class MyWorker(_workers.Worker):
+    def do_check(self, request):
+        token = request.cookies.get('session')
+        if not token:
+            return {'error': 'unauthorized'}, 401
+```
+
+Return `(data, status)` tuple to reject, or `None` to continue. You can also raise `RejectRequest`:
+
+```python
+    def do_check(self, request):
+        if not self.validate_token(request.cookies.get('session')):
+            raise _workers.RejectRequest(
+                data={'error': 'forbidden'}, status=403)
+```
+
+`RejectRequest` accepts optional `data` (default: `{'error': 'Rejected'}`) and `status` (default: `403`).
+
+### Error Handling
+
+Override `on_request_error()` on the worker to customize error handling when a request handler raises an exception:
+
+```python
+class MyWorker(_workers.Worker):
+    def on_request_error(self, request, err):
+        if isinstance(err, DatabaseError):
+            self.db.reconnect()
+        return super().on_request_error(request, err)
+```
+
+Default behavior logs the error with traceback and returns 500.
+
 ## Post-Response Hook
 
 Override `on_response()` on the dispatcher to post-process after a response is sent to the client — e.g., forward data to another worker pool:
@@ -380,6 +511,15 @@ Log messages are sent to the dispatcher via the shared response queue and printe
 
 **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:
+
+```python
+if self.log.is_debug:
+    self.log.debug("Details: %s", expensive_computation())
+```
+
+Available: `is_debug`, `is_info`, `is_warning`, `is_error`.
+
 Set minimum level per pool:
 
 ```python

uhttp_workers-1.2.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.0.0 → uhttp_workers-1.2.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()