uhttp-server 2.2.1__tar.gz → 2.3.0__tar.gz

uhttp_server-2.3.0/.github/workflows/micropython.yml

@@ -0,0 +1,40 @@
+name: MicroPython Integration
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: pip install -e .
+      - run: python -m unittest discover tests/ -v
+
+  micropython:
+    runs-on: [self-hosted, Linux]
+    needs: unit-tests
+    strategy:
+      fail-fast: false
+      matrix:
+        device: [ESP32]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install packages
+        run: |
+          $HOME/actions-runner/.venv/bin/pip install -e .
+          $HOME/actions-runner/.venv/bin/pip install uhttp-client
+
+      - name: MicroPython tests (${{ matrix.device }})
+        run: |
+          export PATH="$HOME/actions-runner/.venv/bin:$PATH"
+          export MPY_TEST_PORT="$(cat $HOME/actions-runner/.config/mpytool/${{ matrix.device }})"
+          export MPY_WIFI_SSID="$(jq -r .ssid $HOME/actions-runner/.config/uhttp/wifi.json)"
+          export MPY_WIFI_PASSWORD="$(jq -r .password $HOME/actions-runner/.config/uhttp/wifi.json)"
+          python -m unittest tests.test_mpy_integration -v

uhttp_server-2.3.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Install package
+        run: pip install .
+
+      - name: Run unit tests
+        run: python -m unittest discover -v tests/
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

uhttp_server-2.3.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      max-parallel: 1
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install .
+
+      - name: Run unit tests
+        run: python -m unittest discover -v tests/

uhttp_server-2.3.0/.gitignore

@@ -0,0 +1,10 @@
+*.egg-info
+__pycache__
+*.pyc
+.*
+!.gitignore
+!.github
+!.mpyproject
+*.pem
+*.md
+!README*.md

{uhttp_server-2.2.1 → uhttp_server-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-server
-Version: 2.2.1
+Version: 2.3.0
 Summary: Micro HTTP server for Python and MicroPython
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Micro HTTP server for MicroPython and CPython.
 - SSL/TLS for HTTPS connections
 - IPv6 and dual-stack support
 - Event mode for streaming large uploads
+- WebSocket support (RFC 6455)
 - Memory-efficient (~32KB RAM minimum)
 
 ## Installation
@@ -294,6 +295,10 @@ Parameters:
 
 - Returns `True` if event mode is enabled
 
+**`max_ws_message_length`** (kwarg)
+
+- Maximum WebSocket message size before chunking (default: 64KB)
+
 #### Methods:
 
 **`event_write(self, sockets)`**
@@ -395,6 +400,18 @@ Parameters:
 
 - Application storage attribute for request state (read-write)
 
+**`is_websocket_request(self)`**
+
+- True if request is a WebSocket upgrade request
+
+**`is_websocket(self)`**
+
+- True if connection is in WebSocket mode
+
+**`ws_message(self)`**
+
+- Last received WebSocket message (str for text frames, bytes for binary frames)
+
 #### Methods:
 
 **`headers_get(self, key, default=None)`**
@@ -442,6 +459,117 @@ Parameters:
 - Read available data from buffer
 - Returns: bytes or None if no data available
 
+**`accept_websocket(self)`**
+
+- Accept WebSocket upgrade. Event mode: switches to WS mode. Non-event mode: returns `WebSocket` object.
+
+**`ws_send(self, data)`** (event mode, WebSocket)
+
+- Send WebSocket message. `str` → text frame, `bytes` → binary frame.
+
+**`ws_ping(self, data=b'')`** (event mode, WebSocket)
+
+- Send WebSocket ping frame
+
+**`ws_close(self, code=1000, reason='')`** (event mode, WebSocket)
+
+- Send WebSocket close frame and close connection
+
+
+## WebSocket Support
+
+uHTTP supports WebSocket connections (RFC 6455) in both event mode and non-event mode.
+
+### Event Mode (non-blocking, multiple connections)
+
+```python
+from uhttp.server import (
+    HttpServer, EVENT_REQUEST, EVENT_WS_REQUEST,
+    EVENT_WS_MESSAGE, EVENT_WS_CHUNK_FIRST,
+    EVENT_WS_CHUNK_NEXT, EVENT_WS_CHUNK_LAST,
+    EVENT_WS_PING, EVENT_WS_CLOSE
+)
+
+server = HttpServer(port=8080, event_mode=True)
+
+while True:
+    client = server.wait()
+    if not client:
+        continue
+
+    if client.event == EVENT_WS_REQUEST:
+        client.accept_websocket()
+
+    elif client.event == EVENT_REQUEST:
+        client.respond({'status': 'ok'})
+
+    elif client.event == EVENT_WS_MESSAGE:
+        # str for text frames, bytes for binary frames
+        client.ws_send(client.ws_message)  # echo
+
+    elif client.event == EVENT_WS_CHUNK_FIRST:
+        client.context = {'chunks': [client.ws_message]}
+
+    elif client.event == EVENT_WS_CHUNK_NEXT:
+        client.context['chunks'].append(client.ws_message)
+
+    elif client.event == EVENT_WS_CHUNK_LAST:
+        client.context['chunks'].append(client.ws_message)
+        # process all chunks...
+        client.ws_send('received')
+
+    elif client.event == EVENT_WS_PING:
+        pass  # pong sent automatically
+
+    elif client.event == EVENT_WS_CLOSE:
+        print("WebSocket closed")
+```
+
+### Non-Event Mode (blocking, simple)
+
+```python
+from uhttp.server import HttpServer
+
+server = HttpServer(port=8080)
+
+while True:
+    client = server.wait()
+    if client and client.is_websocket_request:
+        ws = client.accept_websocket()  # returns WebSocket object
+        while not ws.is_closed:
+            msg = ws.recv(timeout=5)
+            if msg is not None:
+                ws.send(msg)  # echo
+    elif client:
+        client.respond("hello")
+```
+
+### WebSocket API
+
+**HttpConnection properties:**
+- `is_websocket_request` - True if request is a WebSocket upgrade
+- `is_websocket` - True if connection is in WebSocket mode
+- `ws_message` - Last received message (str for text, bytes for binary)
+
+**HttpConnection methods (event mode):**
+- `accept_websocket()` - Accept upgrade, switch to WebSocket mode
+- `ws_send(data)` - Send message (str → text frame, bytes → binary frame)
+- `ws_ping(data=b'')` - Send ping frame
+- `ws_close(code=1000, reason='')` - Close WebSocket connection
+
+**WebSocket object (non-event mode):**
+- `recv(timeout=None)` - Receive message (blocking). Returns str/bytes/None
+- `send(data)` - Send message (str → text frame, bytes → binary frame)
+- `ping(data=b'')` - Send ping frame
+- `close(code=1000, reason='')` - Close connection
+- `is_closed` - True if connection is closed
+
+### Large Message Chunking
+
+Messages larger than `MAX_WS_MESSAGE_LENGTH` (default 64KB, configurable via `max_ws_message_length` kwarg) are delivered in chunks via `EVENT_WS_CHUNK_FIRST`, `EVENT_WS_CHUNK_NEXT`, `EVENT_WS_CHUNK_LAST` events. All chunk events contain data in `ws_message`.
+
+In non-event mode, messages exceeding the limit close the connection with status 1009.
+
 
 ## Event Mode
 
@@ -530,16 +658,70 @@ server = uhttp.server.HttpServer(address='::1', port=80)
 ../.venv/bin/python -m unittest discover -v tests/
 ```
 
-For running tests from meta-repo, see [uhttp README](https://github.com/pavelrevak/uhttp#testing).
+### MicroPython integration tests
+
+Tests run HTTP server on real ESP32 hardware, with test client on PC.
+Requires [mpytool](https://github.com/cortexm/mpytool) and `uhttp-client`.
+
+**Configuration:**
+
+1. WiFi credentials in `~/.config/uhttp/wifi.json`:
+   ```json
+   {"ssid": "MyWiFi", "password": "secret"}
+   ```
+
+2. Serial port via environment variable or mpytool config:
+   ```bash
+   # Environment variable
+   export MPY_TEST_PORT=/dev/ttyUSB0
+
+   # Or mpytool config
+   echo "/dev/ttyUSB0" > ~/.config/mpytool/ESP32
+   ```
+
+**Run tests:**
+
+```bash
+# Install dependencies
+../.venv/bin/pip install uhttp-client mpytool
+```
+
+uhttp-client - for other integration tests
+mpytool - for mpy_integration tests
+
+```bash
+# Run tests
+MPY_TEST_PORT=/dev/ttyUSB0 ../.venv/bin/python -m unittest tests.test_mpy_integration -v
+```
+
+The tests upload `server.py` to ESP32, start HTTP server, and send requests from PC.
 
 ### CI
 
-Tests run automatically on push/PR via GitHub Actions (Ubuntu + Windows, Python 3.10 + 3.14).
+Tests run automatically on push/PR via GitHub Actions:
+- Unit tests: Ubuntu + Windows, Python 3.10 + 3.14
+- MicroPython tests: Self-hosted runner with ESP32
+
 
+## Expect: 100-continue
 
-## TODO
+Server supports `Expect: 100-continue` header for large uploads:
 
-- Cookie attributes support (Path, Domain, Secure, HttpOnly, SameSite, Expires)
-- Expect: 100-continue support - currently causes deadlock (client waits for 100, server waits for body)
-- Streaming API for sending large responses (handle EAGAIN)
-- Chunked transfer encoding support (receiving and sending)
+**Non-event mode:** Server automatically sends `100 Continue` response when client sends `Expect: 100-continue` header, then waits for body.
+
+**Event mode:** Server sends `100 Continue` only when application calls `accept_body()`. This allows rejecting uploads early (e.g., respond with 413 or 401) without accepting body data.
+
+```python
+from uhttp.server import HttpServer, EVENT_HEADERS
+
+server = HttpServer(port=8080, event_mode=True)
+
+while True:
+    client = server.wait()
+    if client and client.event == EVENT_HEADERS:
+        if client.content_length > MAX_ALLOWED:
+            # No 100 Continue sent - client won't upload
+            client.respond({'error': 'too large'}, status=413)
+        else:
+            client.accept_body()  # Sends 100 Continue, starts receiving
+```

{uhttp_server-2.2.1 → uhttp_server-2.3.0}/README.md

@@ -12,6 +12,7 @@ Micro HTTP server for MicroPython and CPython.
 - SSL/TLS for HTTPS connections
 - IPv6 and dual-stack support
 - Event mode for streaming large uploads
+- WebSocket support (RFC 6455)
 - Memory-efficient (~32KB RAM minimum)
 
 ## Installation
@@ -277,6 +278,10 @@ Parameters:
 
 - Returns `True` if event mode is enabled
 
+**`max_ws_message_length`** (kwarg)
+
+- Maximum WebSocket message size before chunking (default: 64KB)
+
 #### Methods:
 
 **`event_write(self, sockets)`**
@@ -378,6 +383,18 @@ Parameters:
 
 - Application storage attribute for request state (read-write)
 
+**`is_websocket_request(self)`**
+
+- True if request is a WebSocket upgrade request
+
+**`is_websocket(self)`**
+
+- True if connection is in WebSocket mode
+
+**`ws_message(self)`**
+
+- Last received WebSocket message (str for text frames, bytes for binary frames)
+
 #### Methods:
 
 **`headers_get(self, key, default=None)`**
@@ -425,6 +442,117 @@ Parameters:
 - Read available data from buffer
 - Returns: bytes or None if no data available
 
+**`accept_websocket(self)`**
+
+- Accept WebSocket upgrade. Event mode: switches to WS mode. Non-event mode: returns `WebSocket` object.
+
+**`ws_send(self, data)`** (event mode, WebSocket)
+
+- Send WebSocket message. `str` → text frame, `bytes` → binary frame.
+
+**`ws_ping(self, data=b'')`** (event mode, WebSocket)
+
+- Send WebSocket ping frame
+
+**`ws_close(self, code=1000, reason='')`** (event mode, WebSocket)
+
+- Send WebSocket close frame and close connection
+
+
+## WebSocket Support
+
+uHTTP supports WebSocket connections (RFC 6455) in both event mode and non-event mode.
+
+### Event Mode (non-blocking, multiple connections)
+
+```python
+from uhttp.server import (
+    HttpServer, EVENT_REQUEST, EVENT_WS_REQUEST,
+    EVENT_WS_MESSAGE, EVENT_WS_CHUNK_FIRST,
+    EVENT_WS_CHUNK_NEXT, EVENT_WS_CHUNK_LAST,
+    EVENT_WS_PING, EVENT_WS_CLOSE
+)
+
+server = HttpServer(port=8080, event_mode=True)
+
+while True:
+    client = server.wait()
+    if not client:
+        continue
+
+    if client.event == EVENT_WS_REQUEST:
+        client.accept_websocket()
+
+    elif client.event == EVENT_REQUEST:
+        client.respond({'status': 'ok'})
+
+    elif client.event == EVENT_WS_MESSAGE:
+        # str for text frames, bytes for binary frames
+        client.ws_send(client.ws_message)  # echo
+
+    elif client.event == EVENT_WS_CHUNK_FIRST:
+        client.context = {'chunks': [client.ws_message]}
+
+    elif client.event == EVENT_WS_CHUNK_NEXT:
+        client.context['chunks'].append(client.ws_message)
+
+    elif client.event == EVENT_WS_CHUNK_LAST:
+        client.context['chunks'].append(client.ws_message)
+        # process all chunks...
+        client.ws_send('received')
+
+    elif client.event == EVENT_WS_PING:
+        pass  # pong sent automatically
+
+    elif client.event == EVENT_WS_CLOSE:
+        print("WebSocket closed")
+```
+
+### Non-Event Mode (blocking, simple)
+
+```python
+from uhttp.server import HttpServer
+
+server = HttpServer(port=8080)
+
+while True:
+    client = server.wait()
+    if client and client.is_websocket_request:
+        ws = client.accept_websocket()  # returns WebSocket object
+        while not ws.is_closed:
+            msg = ws.recv(timeout=5)
+            if msg is not None:
+                ws.send(msg)  # echo
+    elif client:
+        client.respond("hello")
+```
+
+### WebSocket API
+
+**HttpConnection properties:**
+- `is_websocket_request` - True if request is a WebSocket upgrade
+- `is_websocket` - True if connection is in WebSocket mode
+- `ws_message` - Last received message (str for text, bytes for binary)
+
+**HttpConnection methods (event mode):**
+- `accept_websocket()` - Accept upgrade, switch to WebSocket mode
+- `ws_send(data)` - Send message (str → text frame, bytes → binary frame)
+- `ws_ping(data=b'')` - Send ping frame
+- `ws_close(code=1000, reason='')` - Close WebSocket connection
+
+**WebSocket object (non-event mode):**
+- `recv(timeout=None)` - Receive message (blocking). Returns str/bytes/None
+- `send(data)` - Send message (str → text frame, bytes → binary frame)
+- `ping(data=b'')` - Send ping frame
+- `close(code=1000, reason='')` - Close connection
+- `is_closed` - True if connection is closed
+
+### Large Message Chunking
+
+Messages larger than `MAX_WS_MESSAGE_LENGTH` (default 64KB, configurable via `max_ws_message_length` kwarg) are delivered in chunks via `EVENT_WS_CHUNK_FIRST`, `EVENT_WS_CHUNK_NEXT`, `EVENT_WS_CHUNK_LAST` events. All chunk events contain data in `ws_message`.
+
+In non-event mode, messages exceeding the limit close the connection with status 1009.
+
 
 ## Event Mode
 
@@ -513,16 +641,70 @@ server = uhttp.server.HttpServer(address='::1', port=80)
 ../.venv/bin/python -m unittest discover -v tests/
 ```
 
-For running tests from meta-repo, see [uhttp README](https://github.com/pavelrevak/uhttp#testing).
+### MicroPython integration tests
+
+Tests run HTTP server on real ESP32 hardware, with test client on PC.
+Requires [mpytool](https://github.com/cortexm/mpytool) and `uhttp-client`.
+
+**Configuration:**
+
+1. WiFi credentials in `~/.config/uhttp/wifi.json`:
+   ```json
+   {"ssid": "MyWiFi", "password": "secret"}
+   ```
+
+2. Serial port via environment variable or mpytool config:
+   ```bash
+   # Environment variable
+   export MPY_TEST_PORT=/dev/ttyUSB0
+
+   # Or mpytool config
+   echo "/dev/ttyUSB0" > ~/.config/mpytool/ESP32
+   ```
+
+**Run tests:**
+
+```bash
+# Install dependencies
+../.venv/bin/pip install uhttp-client mpytool
+```
+
+uhttp-client - for other integration tests
+mpytool - for mpy_integration tests
+
+```bash
+# Run tests
+MPY_TEST_PORT=/dev/ttyUSB0 ../.venv/bin/python -m unittest tests.test_mpy_integration -v
+```
+
+The tests upload `server.py` to ESP32, start HTTP server, and send requests from PC.
 
 ### CI
 
-Tests run automatically on push/PR via GitHub Actions (Ubuntu + Windows, Python 3.10 + 3.14).
+Tests run automatically on push/PR via GitHub Actions:
+- Unit tests: Ubuntu + Windows, Python 3.10 + 3.14
+- MicroPython tests: Self-hosted runner with ESP32
+
 
+## Expect: 100-continue
 
-## TODO
+Server supports `Expect: 100-continue` header for large uploads:
 
-- Cookie attributes support (Path, Domain, Secure, HttpOnly, SameSite, Expires)
-- Expect: 100-continue support - currently causes deadlock (client waits for 100, server waits for body)
-- Streaming API for sending large responses (handle EAGAIN)
-- Chunked transfer encoding support (receiving and sending)
+**Non-event mode:** Server automatically sends `100 Continue` response when client sends `Expect: 100-continue` header, then waits for body.
+
+**Event mode:** Server sends `100 Continue` only when application calls `accept_body()`. This allows rejecting uploads early (e.g., respond with 413 or 401) without accepting body data.
+
+```python
+from uhttp.server import HttpServer, EVENT_HEADERS
+
+server = HttpServer(port=8080, event_mode=True)
+
+while True:
+    client = server.wait()
+    if client and client.event == EVENT_HEADERS:
+        if client.content_length > MAX_ALLOWED:
+            # No 100 Continue sent - client won't upload
+            client.respond({'error': 'too large'}, status=413)
+        else:
+            client.accept_body()  # Sends 100 Continue, starts receiving
+```