freastal 0.0.1__tar.gz

freastal-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Bylund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freastal-0.0.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: freastal
+Version: 0.0.1
+Summary: Fast libuv + picohttpparser WSGI/ASGI server (Irish: freastal — service)
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# freastal
+
+A fast WSGI/ASGI server for Python, built as a C extension on top of [libuv](https://libuv.org/) and [picohttpparser](https://github.com/h2o/picohttpparser). Optional TLS 1.3 via [picotls](https://github.com/h2o/picotls).
+
+*Freastal* (IPA: /ˈfʲɾʲasˠtəl/) is Irish Gaelic for "service."
+
+## Performance
+
+Benchmarked against gunicorn+uvicorn (the most common production Python stack) as baseline. 30-second runs, `wrk -t4 -c40`, 4 worker processes, ARM64 Linux.
+
+### 500B response
+
+| Server | Protocol | Req/s | p50 | p99 | vs baseline |
+|--------|----------|------:|----:|----:|------------:|
+| **gunicorn+uvicorn** | **ASGI** | **~225k** | **156µs** | **476µs** | **1.00×** |
+| bjoern | WSGI | ~370k | 90µs | 390µs | 1.65× |
+| freastal | WSGI | ~424k | 78µs | 312µs | 1.88× |
+| freastal | ASGI | ~408k | 81µs | 317µs | 1.81× |
+| freastal | TLS 1.3 | ~421k | 78µs | 342µs | 1.87× |
+
+### 12KB response
+
+| Server | Protocol | Req/s | p50 | p99 | vs baseline |
+|--------|----------|------:|----:|----:|------------:|
+| **gunicorn+uvicorn** | **ASGI** | **~201k** | **173µs** | **524µs** | **1.00×** |
+| bjoern | WSGI | ~293k | 120µs | 360µs | 1.46× |
+| freastal | WSGI | ~299k | 114µs | 391µs | 1.49× |
+| freastal | ASGI | ~295k | 115µs | 409µs | 1.47× |
+| freastal | TLS 1.3 | ~279k | 121µs | 555µs | 1.39× |
+
+## Installation
+
+Pre-built wheels for Linux (x86\_64, aarch64) and macOS (arm64, x86\_64) are available on PyPI:
+
+```bash
+pip install freastal
+```
+
+Building from source requires libuv ≥ 1.44, a C compiler, and (optionally) OpenSSL for TLS support. See [Building from source](#building-from-source).
+
+## Usage
+
+### WSGI
+
+```python
+import freastal
+
+def app(environ, start_response):
+    body = b"Hello, world!"
+    start_response("200 OK", [("Content-Type", "text/plain")])
+    return [body]
+
+freastal.serve(app, host="0.0.0.0", port=8000, workers=4)
+```
+
+### ASGI
+
+```python
+import freastal
+
+async def app(scope, receive, send):
+    await send({"type": "http.response.start", "status": 200,
+                "headers": [[b"content-type", b"text/plain"]]})
+    await send({"type": "http.response.body", "body": b"Hello, world!"})
+
+freastal.serve_asgi(app, host="0.0.0.0", port=8000, workers=4)
+```
+
+### TLS 1.3
+
+```python
+freastal.serve(app, host="0.0.0.0", port=8000, workers=4,
+               certfile="/path/to/cert.pem", keyfile="/path/to/key.pem")
+```
+
+TLS requires OpenSSL headers at build time. Wheels published to PyPI include TLS support.
+
+## Architecture
+
+- **libuv** — cross-platform event loop; io\_uring-ready on Linux (libuv ≥ 1.45 batches syscalls automatically)
+- **picohttpparser** — SSE4.2/NEON SIMD HTTP/1.1 parser from the h2o project; vendored
+- **picotls** — TLS 1.3 library from the h2o project; vendored, gated by `FREASTAL_TLS`
+- **io_uring fixed-buffer path** (Linux, optional) — when built with `liburing`, responses > 4 KB are copied into pre-registered kernel buffers and sent with `io_uring_prep_write_fixed`, eliminating per-write `get_user_pages()` overhead. libuv ≥ 1.45 also transparently batches `accept`/`read`/`write` via io_uring regardless of this flag.
+- Single `uv_write` per response — headers and body sent together, no extra copy
+- HTTP/1.1 keep-alive: connections re-armed in-place without close/reopen; `TCP_NODELAY` set on every accepted socket
+- Slab allocator for per-connection state — no per-request malloc on the hot path
+- Pre-interned Python strings for all WSGI/ASGI environ keys
+- GIL released for the duration of the libuv event loop; acquired only when calling the WSGI/ASGI application and touching Python response objects
+- `SO_REUSEPORT` (`UV_TCP_REUSEPORT`) for kernel-level load balancing across worker processes
+
+**Multi-process model:** `workers=N` forks N independent OS processes, each with its own libuv loop and Python interpreter (and therefore its own GIL). The kernel distributes incoming connections across workers via `SO_REUSEPORT`.
+
+**ASGI event loop bridge (libuv ↔ asyncio):**
+
+freastal runs asyncio inside the libuv event loop rather than the other way around. A `uv_check_t` steps asyncio after each I/O poll; a `uv_poll_t` on asyncio's selector fd wakes libuv when external async I/O (database calls, aiohttp, etc.) completes.
+
+## Building from source
+
+```bash
+# macOS
+brew install libuv openssl@3
+pip install freastal --no-binary freastal
+
+# Debian/Ubuntu
+apt-get install libuv1-dev libssl-dev
+pip install freastal --no-binary freastal
+
+# Debian/Ubuntu with io_uring fixed-buffer path (Linux ≥ 5.6)
+apt-get install libuv1-dev libssl-dev liburing-dev
+pip install freastal --no-binary freastal
+```
+
+picohttpparser and picotls are vendored — no extra steps required.
+
+## Requirements
+
+- Python ≥ 3.10
+- Linux or macOS
+- libuv ≥ 1.44 (shared library, found via pkg-config or standard include paths)
+- OpenSSL (optional, for TLS 1.3)
+
+## License
+
+MIT

freastal-0.0.1/README.md

@@ -0,0 +1,124 @@
+# freastal
+
+A fast WSGI/ASGI server for Python, built as a C extension on top of [libuv](https://libuv.org/) and [picohttpparser](https://github.com/h2o/picohttpparser). Optional TLS 1.3 via [picotls](https://github.com/h2o/picotls).
+
+*Freastal* (IPA: /ˈfʲɾʲasˠtəl/) is Irish Gaelic for "service."
+
+## Performance
+
+Benchmarked against gunicorn+uvicorn (the most common production Python stack) as baseline. 30-second runs, `wrk -t4 -c40`, 4 worker processes, ARM64 Linux.
+
+### 500B response
+
+| Server | Protocol | Req/s | p50 | p99 | vs baseline |
+|--------|----------|------:|----:|----:|------------:|
+| **gunicorn+uvicorn** | **ASGI** | **~225k** | **156µs** | **476µs** | **1.00×** |
+| bjoern | WSGI | ~370k | 90µs | 390µs | 1.65× |
+| freastal | WSGI | ~424k | 78µs | 312µs | 1.88× |
+| freastal | ASGI | ~408k | 81µs | 317µs | 1.81× |
+| freastal | TLS 1.3 | ~421k | 78µs | 342µs | 1.87× |
+
+### 12KB response
+
+| Server | Protocol | Req/s | p50 | p99 | vs baseline |
+|--------|----------|------:|----:|----:|------------:|
+| **gunicorn+uvicorn** | **ASGI** | **~201k** | **173µs** | **524µs** | **1.00×** |
+| bjoern | WSGI | ~293k | 120µs | 360µs | 1.46× |
+| freastal | WSGI | ~299k | 114µs | 391µs | 1.49× |
+| freastal | ASGI | ~295k | 115µs | 409µs | 1.47× |
+| freastal | TLS 1.3 | ~279k | 121µs | 555µs | 1.39× |
+
+## Installation
+
+Pre-built wheels for Linux (x86\_64, aarch64) and macOS (arm64, x86\_64) are available on PyPI:
+
+```bash
+pip install freastal
+```
+
+Building from source requires libuv ≥ 1.44, a C compiler, and (optionally) OpenSSL for TLS support. See [Building from source](#building-from-source).
+
+## Usage
+
+### WSGI
+
+```python
+import freastal
+
+def app(environ, start_response):
+    body = b"Hello, world!"
+    start_response("200 OK", [("Content-Type", "text/plain")])
+    return [body]
+
+freastal.serve(app, host="0.0.0.0", port=8000, workers=4)
+```
+
+### ASGI
+
+```python
+import freastal
+
+async def app(scope, receive, send):
+    await send({"type": "http.response.start", "status": 200,
+                "headers": [[b"content-type", b"text/plain"]]})
+    await send({"type": "http.response.body", "body": b"Hello, world!"})
+
+freastal.serve_asgi(app, host="0.0.0.0", port=8000, workers=4)
+```
+
+### TLS 1.3
+
+```python
+freastal.serve(app, host="0.0.0.0", port=8000, workers=4,
+               certfile="/path/to/cert.pem", keyfile="/path/to/key.pem")
+```
+
+TLS requires OpenSSL headers at build time. Wheels published to PyPI include TLS support.
+
+## Architecture
+
+- **libuv** — cross-platform event loop; io\_uring-ready on Linux (libuv ≥ 1.45 batches syscalls automatically)
+- **picohttpparser** — SSE4.2/NEON SIMD HTTP/1.1 parser from the h2o project; vendored
+- **picotls** — TLS 1.3 library from the h2o project; vendored, gated by `FREASTAL_TLS`
+- **io_uring fixed-buffer path** (Linux, optional) — when built with `liburing`, responses > 4 KB are copied into pre-registered kernel buffers and sent with `io_uring_prep_write_fixed`, eliminating per-write `get_user_pages()` overhead. libuv ≥ 1.45 also transparently batches `accept`/`read`/`write` via io_uring regardless of this flag.
+- Single `uv_write` per response — headers and body sent together, no extra copy
+- HTTP/1.1 keep-alive: connections re-armed in-place without close/reopen; `TCP_NODELAY` set on every accepted socket
+- Slab allocator for per-connection state — no per-request malloc on the hot path
+- Pre-interned Python strings for all WSGI/ASGI environ keys
+- GIL released for the duration of the libuv event loop; acquired only when calling the WSGI/ASGI application and touching Python response objects
+- `SO_REUSEPORT` (`UV_TCP_REUSEPORT`) for kernel-level load balancing across worker processes
+
+**Multi-process model:** `workers=N` forks N independent OS processes, each with its own libuv loop and Python interpreter (and therefore its own GIL). The kernel distributes incoming connections across workers via `SO_REUSEPORT`.
+
+**ASGI event loop bridge (libuv ↔ asyncio):**
+
+freastal runs asyncio inside the libuv event loop rather than the other way around. A `uv_check_t` steps asyncio after each I/O poll; a `uv_poll_t` on asyncio's selector fd wakes libuv when external async I/O (database calls, aiohttp, etc.) completes.
+
+## Building from source
+
+```bash
+# macOS
+brew install libuv openssl@3
+pip install freastal --no-binary freastal
+
+# Debian/Ubuntu
+apt-get install libuv1-dev libssl-dev
+pip install freastal --no-binary freastal
+
+# Debian/Ubuntu with io_uring fixed-buffer path (Linux ≥ 5.6)
+apt-get install libuv1-dev libssl-dev liburing-dev
+pip install freastal --no-binary freastal
+```
+
+picohttpparser and picotls are vendored — no extra steps required.
+
+## Requirements
+
+- Python ≥ 3.10
+- Linux or macOS
+- libuv ≥ 1.44 (shared library, found via pkg-config or standard include paths)
+- OpenSSL (optional, for TLS 1.3)
+
+## License
+
+MIT

freastal-0.0.1/freastal/__init__.py

@@ -0,0 +1,126 @@
+"""freastal – libuv + picohttpparser WSGI/ASGI server."""
+
+import asyncio
+import os
+import signal
+import sys
+import multiprocessing
+import time
+
+from ._freastal import (
+    serve as _serve_single,
+    serve_asgi as _serve_asgi_single,
+    __version__,
+)
+
+__all__ = ["serve", "serve_asgi", "__version__"]
+
+
+def serve(
+    app,
+    host="0.0.0.0",
+    port=8000,
+    workers=1,
+    reuse_port=True,
+    certfile=None,
+    keyfile=None,
+):
+    """Start freastal.
+
+    With workers=1 (default) runs in-process.
+    With workers>1 forks worker processes, each binding with SO_REUSEPORT
+    so the kernel load-balances connections across them.
+    Pass certfile and keyfile (PEM paths) to enable TLS 1.3 (requires picotls).
+    """
+    if workers <= 1:
+        _serve_single(
+            app,
+            host=host,
+            port=port,
+            reuse_port=reuse_port,
+            certfile=certfile,
+            keyfile=keyfile,
+        )
+        return
+
+    processes = []
+
+    def _worker(worker_id):
+        print(f"[freastal] worker {worker_id} pid={os.getpid()} starting", flush=True)
+        try:
+            _serve_single(
+                app,
+                host=host,
+                port=port,
+                reuse_port=True,
+                certfile=certfile,
+                keyfile=keyfile,
+            )
+        except KeyboardInterrupt:
+            pass
+
+    def _shutdown(sig, frame):
+        for p in processes:
+            p.terminate()
+        for p in processes:
+            p.join(timeout=5)
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _shutdown)
+    signal.signal(signal.SIGTERM, _shutdown)
+
+    for i in range(workers):
+        p = multiprocessing.Process(target=_worker, args=(i + 1,), daemon=True)
+        p.start()
+        processes.append(p)
+
+    for p in processes:
+        p.join()
+
+
+def serve_asgi(app, host="0.0.0.0", port=8000, workers=1, reuse_port=True):
+    """Start freastal in ASGI mode.
+
+    With workers=1 runs in-process.
+    With workers>1 forks worker processes using SO_REUSEPORT.
+    Each worker creates its own asyncio event loop.
+    """
+
+    def _run_single():
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        _serve_asgi_single(app, loop, host=host, port=port, reuse_port=reuse_port)
+
+    if workers <= 1:
+        _run_single()
+        return
+
+    processes = []
+
+    def _worker(worker_id):
+        print(
+            f"[freastal] ASGI worker {worker_id} pid={os.getpid()} starting", flush=True
+        )
+        try:
+            _run_single()
+        except KeyboardInterrupt:
+            pass
+
+    def _shutdown(sig, frame):
+        for p in processes:
+            p.terminate()
+        for p in processes:
+            p.join(timeout=5)
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _shutdown)
+    signal.signal(signal.SIGTERM, _shutdown)
+
+    for i in range(workers):
+        p = multiprocessing.Process(target=_worker, args=(i + 1,), daemon=True)
+        p.start()
+        processes.append(p)
+        time.sleep(0.05)
+
+    for p in processes:
+        p.join()

freastal-0.0.1/freastal/_asgi_protocol.py

@@ -0,0 +1,42 @@
+"""Pure-Python ASGI protocol bridge for freastal.
+
+run_asgi_request() is called from C (asgi_dispatch) once per HTTP request.
+It creates the receive/send coroutines and schedules the ASGI app as an
+asyncio Task on the loop that freastal is stepping from its uv_check_t callback.
+"""
+
+from ._freastal import asgi_send_response
+
+
+def run_asgi_request(loop, app, scope, body, capsule):
+    """Schedule `app(scope, receive, send)` as a Task and return it.
+
+    The Task runs inside the asyncio loop that freastal drives from
+    uv_check_t / uv_poll_t callbacks.  Because receive() returns immediately
+    and send() calls back into C synchronously, a simple ASGI app completes
+    in one _run_once() step with no event-loop round-trips.
+
+    Apps that do real async I/O (await aiohttp.get(...), await db.query(...))
+    work normally: their futures are resolved by asyncio's selector, which
+    freastal monitors via a uv_poll_t on asyncio's selector fd.
+    """
+    status_cell = [None]
+    headers_cell = [None]
+
+    async def receive():
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    async def send(event):
+        t = event["type"]
+        if t == "http.response.start":
+            status_cell[0] = event["status"]
+            headers_cell[0] = list(event.get("headers", []))
+        elif t == "http.response.body":
+            asgi_send_response(
+                capsule,
+                status_cell[0],
+                headers_cell[0],
+                event.get("body", b""),
+            )
+
+    return loop.create_task(app(scope, receive, send))