punkasgi 0.1.0__tar.gz

punkasgi-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+uv.lock
+
+bench/.envs/

punkasgi-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+Copyright 2026 Giovanni Barillari
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1.  Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+3.  Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

punkasgi-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: punkasgi
+Version: 0.1.0
+Summary: An ASGI server for the tonio runtime, built on httpunk
+Project-URL: Homepage, https://github.com/gi0baro/punkasgi
+Project-URL: Funding, https://github.com/sponsors/gi0baro
+Project-URL: Source, https://github.com/gi0baro/punkasgi
+Project-URL: Issues, https://github.com/gi0baro/punkasgi/issues
+Author-email: Giovanni Barillari <g@baro.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: asgi,async,http,httpunk,server,tonio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.14
+Requires-Dist: click>=7.0
+Requires-Dist: httpunk~=0.4.1
+Requires-Dist: tonio~=0.9.17
+Requires-Dist: websockets>=17
+Provides-Extra: standard
+Requires-Dist: python-dotenv>=0.13; extra == 'standard'
+Requires-Dist: pyyaml>=5.1; extra == 'standard'
+Description-Content-Type: text/markdown
+
+# punkasgi
+
+punkasgi is an ASGI server for the [TonIO](https://github.com/gi0baro/tonio) runtime,
+built on top of [HTTPunk](https://github.com/gi0baro/httpunk).
+
+> **Warning:** punkasgi is in an early stage and still work in progress.
+
+> **Note:** punkasgi was built with substantial help from LLMs, under human supervision.
+
+## In a nutshell
+
+- HTTP/1.0, HTTP/1.1 and HTTP/2 (prior knowledge on plain TCP, ALPN over TLS), with
+  every protocol behaviour coming from httpunk: keep-alive, head timeouts, framing,
+  `Date` headers, graceful shutdown
+- WebSockets over HTTP/1.1 through the sans-io `websockets` implementation, with
+  keepalive pings, per-message deflate and the `websocket.http.response` extension
+- The ASGI 3 protocol handling (scope contents, `receive()` / `send()` semantics, lifespan,
+  websocket messages) follows [uvicorn](https://github.com/Kludex/uvicorn)
+- Single process architecture: the TonIO runtime's threads are the workers
+
+## Installation
+
+```shell
+pip install punkasgi
+```
+
+punkasgi needs a free-threaded CPython 3.14 or later, as tonio does. The `standard` extra
+adds `python-dotenv` (for `--env-file`) and `PyYAML` (for YAML logging configurations).
+
+## Quickstart
+
+```python
+# main.py
+async def app(scope, receive, send):
+    assert scope["type"] == "http"
+    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!"})
+```
+
+```shell
+punkasgi main:app
+```
+
+Or *programmatically*:
+
+```python
+import punkasgi
+
+punkasgi.run("main:app", host="0.0.0.0", port=8000, threads=4)
+```
+
+`punkasgi --help` lists every option. The ones worth knowing:
+
+| option | note |
+|---|---|
+| `--threads` | size of the tonio runtime, defaults to `$WEB_CONCURRENCY` or the CPU count |
+| `--http auto\|h1\|h2` | protocol selection: `auto` sniffs the HTTP/2 preface on plain TCP and follows ALPN over TLS |
+| `--ws/--no-ws` | WebSocket upgrades on or off; with them off an upgrade request is answered 400 |
+| `--timeout-keep-alive` | hyper's head read timeout: it bounds the idle wait between requests together with the read of the next request head |
+| `--timeout-graceful-shutdown` | how long a shutdown waits for in-flight requests; unset waits without a deadline |
+| `--proxy-headers` | trust `X-Forwarded-For` / `X-Forwarded-Proto` from `--forwarded-allow-ips`; off by default |
+| `--access-log` | one `punkasgi.access` line per response; off by default |
+
+A first `SIGINT` or `SIGTERM` starts a graceful shutdown; a second `SIGINT` leaves at once
+with whatever is still in flight. Environment variables use the `PUNKASGI_` prefix (e.g.
+`PUNKASGI_PORT`), loggers are `punkasgi.error`, `punkasgi.access` and `punkasgi.asgi`,
+and the default `server` header is `punkasgi`.
+
+## Behaviours worth knowing
+
+These follow httpunk, and through it hyper, rather than any other server:
+
+- **Unread request bodies.** After a response completes, a request body the application
+  left unread is drained only if it is already buffered; otherwise the connection closes
+  instead of being reused for the next request.
+- **Response `content-length`.** punkasgi does not check the body against the declared
+  length. On HTTP/1 a body shorter than declared fails the response and closes the
+  connection, and a longer one is cut at the declared length; on HTTP/2 the frames go out
+  as sent.
+- **`Date` header.** Always written, on both protocols.
+
+## License
+
+punkasgi is released under the BSD-3-Clause license.

punkasgi-0.1.0/README.md

@@ -0,0 +1,84 @@
+# punkasgi
+
+punkasgi is an ASGI server for the [TonIO](https://github.com/gi0baro/tonio) runtime,
+built on top of [HTTPunk](https://github.com/gi0baro/httpunk).
+
+> **Warning:** punkasgi is in an early stage and still work in progress.
+
+> **Note:** punkasgi was built with substantial help from LLMs, under human supervision.
+
+## In a nutshell
+
+- HTTP/1.0, HTTP/1.1 and HTTP/2 (prior knowledge on plain TCP, ALPN over TLS), with
+  every protocol behaviour coming from httpunk: keep-alive, head timeouts, framing,
+  `Date` headers, graceful shutdown
+- WebSockets over HTTP/1.1 through the sans-io `websockets` implementation, with
+  keepalive pings, per-message deflate and the `websocket.http.response` extension
+- The ASGI 3 protocol handling (scope contents, `receive()` / `send()` semantics, lifespan,
+  websocket messages) follows [uvicorn](https://github.com/Kludex/uvicorn)
+- Single process architecture: the TonIO runtime's threads are the workers
+
+## Installation
+
+```shell
+pip install punkasgi
+```
+
+punkasgi needs a free-threaded CPython 3.14 or later, as tonio does. The `standard` extra
+adds `python-dotenv` (for `--env-file`) and `PyYAML` (for YAML logging configurations).
+
+## Quickstart
+
+```python
+# main.py
+async def app(scope, receive, send):
+    assert scope["type"] == "http"
+    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!"})
+```
+
+```shell
+punkasgi main:app
+```
+
+Or *programmatically*:
+
+```python
+import punkasgi
+
+punkasgi.run("main:app", host="0.0.0.0", port=8000, threads=4)
+```
+
+`punkasgi --help` lists every option. The ones worth knowing:
+
+| option | note |
+|---|---|
+| `--threads` | size of the tonio runtime, defaults to `$WEB_CONCURRENCY` or the CPU count |
+| `--http auto\|h1\|h2` | protocol selection: `auto` sniffs the HTTP/2 preface on plain TCP and follows ALPN over TLS |
+| `--ws/--no-ws` | WebSocket upgrades on or off; with them off an upgrade request is answered 400 |
+| `--timeout-keep-alive` | hyper's head read timeout: it bounds the idle wait between requests together with the read of the next request head |
+| `--timeout-graceful-shutdown` | how long a shutdown waits for in-flight requests; unset waits without a deadline |
+| `--proxy-headers` | trust `X-Forwarded-For` / `X-Forwarded-Proto` from `--forwarded-allow-ips`; off by default |
+| `--access-log` | one `punkasgi.access` line per response; off by default |
+
+A first `SIGINT` or `SIGTERM` starts a graceful shutdown; a second `SIGINT` leaves at once
+with whatever is still in flight. Environment variables use the `PUNKASGI_` prefix (e.g.
+`PUNKASGI_PORT`), loggers are `punkasgi.error`, `punkasgi.access` and `punkasgi.asgi`,
+and the default `server` header is `punkasgi`.
+
+## Behaviours worth knowing
+
+These follow httpunk, and through it hyper, rather than any other server:
+
+- **Unread request bodies.** After a response completes, a request body the application
+  left unread is drained only if it is already buffered; otherwise the connection closes
+  instead of being reused for the next request.
+- **Response `content-length`.** punkasgi does not check the body against the declared
+  length. On HTTP/1 a body shorter than declared fails the response and closes the
+  connection, and a longer one is cut at the declared length; on HTTP/2 the frames go out
+  as sent.
+- **`Date` header.** Always written, on both protocols.
+
+## License
+
+punkasgi is released under the BSD-3-Clause license.

punkasgi-0.1.0/punkasgi/__init__.py

@@ -0,0 +1,6 @@
+from punkasgi._version import __version__
+from punkasgi.config import Config
+from punkasgi.main import Server, main, run
+
+
+__all__ = ["Config", "Server", "__version__", "main", "run"]

punkasgi-0.1.0/punkasgi/__main__.py

@@ -0,0 +1,5 @@
+from punkasgi.main import main
+
+
+if __name__ == "__main__":
+    main()

punkasgi-0.1.0/punkasgi/_types.py

@@ -0,0 +1,253 @@
+"""
+Copyright (c) Django Software Foundation and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+class ASGIVersions(TypedDict):
+    spec_version: str
+    version: Literal["2.0"] | Literal["3.0"]
+
+
+class HTTPScope(TypedDict):
+    type: Literal["http"]
+    asgi: ASGIVersions
+    http_version: str
+    method: str
+    scheme: str
+    path: str
+    raw_path: bytes
+    query_string: bytes
+    root_path: str
+    headers: Iterable[tuple[bytes, bytes]]
+    client: tuple[str, int] | None
+    server: tuple[str, int | None] | None
+    state: NotRequired[dict[str, Any]]
+    extensions: NotRequired[dict[str, dict[object, object]]]
+
+
+class WebSocketScope(TypedDict):
+    type: Literal["websocket"]
+    asgi: ASGIVersions
+    http_version: str
+    scheme: str
+    path: str
+    raw_path: bytes
+    query_string: bytes
+    root_path: str
+    headers: Iterable[tuple[bytes, bytes]]
+    client: tuple[str, int] | None
+    server: tuple[str, int | None] | None
+    subprotocols: Iterable[str]
+    state: NotRequired[dict[str, Any]]
+    extensions: NotRequired[dict[str, dict[object, object]]]
+
+
+class LifespanScope(TypedDict):
+    type: Literal["lifespan"]
+    asgi: ASGIVersions
+    state: NotRequired[dict[str, Any]]
+
+
+WWWScope = HTTPScope | WebSocketScope
+Scope = HTTPScope | WebSocketScope | LifespanScope
+
+
+class HTTPRequestEvent(TypedDict):
+    type: Literal["http.request"]
+    body: bytes
+    more_body: bool
+
+
+class HTTPResponseDebugEvent(TypedDict):
+    type: Literal["http.response.debug"]
+    info: dict[str, object]
+
+
+class HTTPResponseStartEvent(TypedDict):
+    type: Literal["http.response.start"]
+    status: int
+    headers: NotRequired[Iterable[tuple[bytes, bytes]]]
+    trailers: NotRequired[bool]
+
+
+class HTTPResponseBodyEvent(TypedDict):
+    type: Literal["http.response.body"]
+    body: bytes
+    more_body: NotRequired[bool]
+
+
+class HTTPResponseTrailersEvent(TypedDict):
+    type: Literal["http.response.trailers"]
+    headers: Iterable[tuple[bytes, bytes]]
+    more_trailers: bool
+
+
+class HTTPServerPushEvent(TypedDict):
+    type: Literal["http.response.push"]
+    path: str
+    headers: Iterable[tuple[bytes, bytes]]
+
+
+class HTTPDisconnectEvent(TypedDict):
+    type: Literal["http.disconnect"]
+
+
+class WebSocketConnectEvent(TypedDict):
+    type: Literal["websocket.connect"]
+
+
+class WebSocketAcceptEvent(TypedDict):
+    type: Literal["websocket.accept"]
+    subprotocol: NotRequired[str | None]
+    headers: NotRequired[Iterable[tuple[bytes, bytes]]]
+
+
+class _WebSocketReceiveEventBytes(TypedDict):
+    type: Literal["websocket.receive"]
+    bytes: bytes
+    text: NotRequired[None]
+
+
+class _WebSocketReceiveEventText(TypedDict):
+    type: Literal["websocket.receive"]
+    bytes: NotRequired[None]
+    text: str
+
+
+WebSocketReceiveEvent = _WebSocketReceiveEventBytes | _WebSocketReceiveEventText
+
+
+class _WebSocketSendEventBytes(TypedDict):
+    type: Literal["websocket.send"]
+    bytes: bytes
+    text: NotRequired[None]
+
+
+class _WebSocketSendEventText(TypedDict):
+    type: Literal["websocket.send"]
+    bytes: NotRequired[None]
+    text: str
+
+
+WebSocketSendEvent = _WebSocketSendEventBytes | _WebSocketSendEventText
+
+
+class WebSocketResponseStartEvent(TypedDict):
+    type: Literal["websocket.http.response.start"]
+    status: int
+    headers: Iterable[tuple[bytes, bytes]]
+
+
+class WebSocketResponseBodyEvent(TypedDict):
+    type: Literal["websocket.http.response.body"]
+    body: bytes
+    more_body: NotRequired[bool]
+
+
+class WebSocketDisconnectEvent(TypedDict):
+    type: Literal["websocket.disconnect"]
+    code: int
+    reason: NotRequired[str | None]
+
+
+class WebSocketCloseEvent(TypedDict):
+    type: Literal["websocket.close"]
+    code: NotRequired[int]
+    reason: NotRequired[str | None]
+
+
+class LifespanStartupEvent(TypedDict):
+    type: Literal["lifespan.startup"]
+
+
+class LifespanShutdownEvent(TypedDict):
+    type: Literal["lifespan.shutdown"]
+
+
+class LifespanStartupCompleteEvent(TypedDict):
+    type: Literal["lifespan.startup.complete"]
+
+
+class LifespanStartupFailedEvent(TypedDict):
+    type: Literal["lifespan.startup.failed"]
+    message: str
+
+
+class LifespanShutdownCompleteEvent(TypedDict):
+    type: Literal["lifespan.shutdown.complete"]
+
+
+class LifespanShutdownFailedEvent(TypedDict):
+    type: Literal["lifespan.shutdown.failed"]
+    message: str
+
+
+WebSocketEvent = WebSocketReceiveEvent | WebSocketDisconnectEvent | WebSocketConnectEvent
+
+
+ASGIReceiveEvent = (
+    HTTPRequestEvent
+    | HTTPDisconnectEvent
+    | WebSocketConnectEvent
+    | WebSocketReceiveEvent
+    | WebSocketDisconnectEvent
+    | LifespanStartupEvent
+    | LifespanShutdownEvent
+)
+
+
+ASGISendEvent = (
+    HTTPResponseStartEvent
+    | HTTPResponseBodyEvent
+    | HTTPResponseTrailersEvent
+    | HTTPServerPushEvent
+    | HTTPDisconnectEvent
+    | WebSocketAcceptEvent
+    | WebSocketSendEvent
+    | WebSocketResponseStartEvent
+    | WebSocketResponseBodyEvent
+    | WebSocketCloseEvent
+    | LifespanStartupCompleteEvent
+    | LifespanStartupFailedEvent
+    | LifespanShutdownCompleteEvent
+    | LifespanShutdownFailedEvent
+)
+
+
+ASGIReceiveCallable = Callable[[], Awaitable[ASGIReceiveEvent]]
+ASGISendCallable = Callable[[ASGISendEvent], Awaitable[None]]
+
+
+ASGI3Application = Callable[[Scope, ASGIReceiveCallable, ASGISendCallable], Awaitable[None]]
+ASGIApplication = ASGI3Application

punkasgi-0.1.0/punkasgi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"