palfrey 0.1.0__tar.gz

palfrey-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# folders
+*.egg-info/
+.hypothesis/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.scannerwork/
+.tox/
+.venv/
+.vscode/
+__pycache__/
+virtualenv/
+build/
+dist/
+node_modules/
+results/
+site/
+site_lang/
+target/
+
+# files
+par.md
+**/*.so
+**/*.sqlite
+*.iml
+**/*_test*
+.DS_Store
+.coverage
+.coverage.*
+.python-version
+coverage.*
+example.sqlite

palfrey-0.1.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright © 2025, Dymmond Ltd. 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 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.

palfrey-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: palfrey
+Version: 0.1.0
+Summary: A clean-room ASGI server with Uvicorn-compatible CLI and behavior mapping.
+Project-URL: Homepage, https://github.com/dymmond/palfrey
+Project-URL: Documentation, https://palfrey.dymmond.com
+Project-URL: Source, https://github.com/dymmond/palfrey
+Project-URL: Changelog, https://github.com/dymmond/palfrey/blob/main/CHANGELOG.md
+Author-email: Tiago Silva <tarsil@tarsild.io>
+License: MIT
+License-File: LICENSE
+Keywords: asgi,click,server,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click<9.0.0,>=8.1.7
+Requires-Dist: h11>=0.8
+Provides-Extra: benchmark
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.34.0; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: maturin<2.0.0,>=1.9.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.11.0; extra == 'dev'
+Requires-Dist: ty>=0.0.1a16; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: griffe-typingdoc<1.0,>=0.2.2; extra == 'docs'
+Requires-Dist: mdx-include>=1.4.2; extra == 'docs'
+Requires-Dist: mkdocs-macros-plugin>=0.4.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.4.4; extra == 'docs'
+Requires-Dist: mkdocs-meta-descriptions-plugin>=2.3.0; extra == 'docs'
+Requires-Dist: mkdocs<2.0.0,>=1.1.2; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.23.0; extra == 'docs'
+Requires-Dist: pyyaml<7.0.0,>=6.0; extra == 'docs'
+Requires-Dist: sayer>=0.7.4; extra == 'docs'
+Requires-Dist: typing-extensions>=3.10.0; extra == 'docs'
+Provides-Extra: http2
+Requires-Dist: h2>=4.1.0; extra == 'http2'
+Provides-Extra: http3
+Requires-Dist: aioquic>=1.2.0; extra == 'http3'
+Provides-Extra: standard
+Requires-Dist: colorama>=0.4; (sys_platform == 'win32') and extra == 'standard'
+Requires-Dist: httptools>=0.6.3; extra == 'standard'
+Requires-Dist: python-dotenv>=0.13; extra == 'standard'
+Requires-Dist: pyyaml>=5.1; extra == 'standard'
+Requires-Dist: uvloop>=0.15.1; (sys_platform != 'win32' and (sys_platform != 'cygwin' and platform_python_implementation != 'PyPy')) and extra == 'standard'
+Requires-Dist: watchfiles>=0.20; extra == 'standard'
+Requires-Dist: websockets>=10.4; extra == 'standard'
+Provides-Extra: testing
+Requires-Dist: pytest-cov<7.0.0,>=5.0.0; extra == 'testing'
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# Palfrey
+
+<p align="center">
+  <a href="https://palfrey.dymmond.com"><img src="https://res.cloudinary.com/dymmond/image/upload/v1771522360/Palfrey/Logo/logo_ocxyty.png" alt='Palfrey'></a>
+</p>
+
+<p align="center">
+    <em>Palfrey is a clean-room, high-performance Python ASGI server with source-traceable parity mapping.</em>
+</p>
+
+<p align="center">
+<a href="https://github.com/dymmond/palfrey/actions/workflows/ci.yml/badge.svg?event=push&branch=main" target="_blank">
+    <img src="https://github.com/dymmond/palfrey/actions/workflows/ci.yml/badge.svg?event=push&branch=main" alt="Test Suite">
+</a>
+
+<a href="https://pypi.org/project/palfrey" target="_blank">
+    <img src="https://img.shields.io/pypi/v/palfrey?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+
+<a href="https://pypi.org/project/palfrey" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/palfrey.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://palfrey.dev](https://palfrey.dev) 📚
+
+**Source Code**: [https://github.com/dymmond/palfrey](https://github.com/dymmond/palfrey)
+
+**The official supported version is always the latest released**.
+
+---
+
+Palfrey is a clean-room ASGI server focused on three things:
+
+- behavior you can reason about
+- deployment controls you can operate safely
+- performance you can reproduce and verify
+
+Protocol runtime modes include HTTP/1.1 backends plus opt-in HTTP/2 (`--http h2`) and HTTP/3 (`--http h3`) paths.
+
+This documentation is written for both technical and non-technical readers.
+
+- Engineers can use the protocol details, option tables, and runbooks.
+- Product, support, and operations teams can use the plain-language summaries and checklists.
+
+## What Palfrey Does
+
+At runtime, Palfrey sits between clients and your ASGI application.
+
+1. accepts TCP or UNIX socket connections
+2. parses protocol bytes into ASGI events
+3. calls your app with `scope`, `receive`, `send`
+4. writes responses back to clients
+5. manages process behavior (reload, workers, graceful shutdown)
+
+## Who Should Start Where
+
+## If you are new to ASGI
+
+1. [Installation](getting-started/installation.md)
+2. [Quickstart](getting-started/quickstart.md)
+3. [Terms and Mental Models](concepts/terms-and-mental-models.md)
+4. [Server Behavior](concepts/server-behavior.md)
+
+## If you operate production services
+
+1. [Deployment](operations/deployment.md)
+2. [Workers](operations/workers.md)
+3. [Observability](operations/observability.md)
+4. [Troubleshooting](guides/troubleshooting.md)
+5. [Release Process](operations/release-process.md)
+
+## First 60 Seconds
+
+Create `main.py`:
+
+```python
+async def app(scope, receive, send):
+    """Return a plain-text greeting for HTTP requests."""
+    if scope["type"] != "http":
+        return
+
+    body = b"Hello from Palfrey"
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                (b"content-type", b"text/plain; charset=utf-8"),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+```
+
+Run Palfrey:
+
+```bash
+palfrey main:app --host 127.0.0.1 --port 8000
+```
+
+Check it:
+
+```bash
+curl http://127.0.0.1:8000
+```
+
+Gunicorn + Palfrey worker:
+
+```bash
+gunicorn main:app -k palfrey.workers.PalfreyWorker -w 4 -b 0.0.0.0:8000
+```
+
+## Documentation Structure
+
+## Getting Started
+
+- install, verify, and run your first app
+- move from a minimal app to real startup patterns
+
+## Concepts
+
+- what ASGI is, and how Palfrey applies it
+- how HTTP, WebSocket, and lifespan flows behave
+- how server internals affect user-visible outcomes
+
+## Reference
+
+- full CLI and config surface
+- protocol and logging behavior
+- env var model and common errors
+
+## Guides
+
+- migration, security hardening, production rollout
+- practical troubleshooting and FAQ
+
+## Operations
+
+- deployment shapes, workers, reload model
+- capacity planning, observability, benchmark method
+- platform-specific notes and release process
+
+## Plain-Language Summary
+
+If your application is the business logic, Palfrey is the runtime control layer around it.
+A good runtime control layer gives teams:
+
+- predictable startup and shutdown
+- fewer surprises under traffic spikes
+- clearer incident response paths
+- safer, repeatable deployments

palfrey-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Palfrey
+
+<p align="center">
+  <a href="https://palfrey.dymmond.com"><img src="https://res.cloudinary.com/dymmond/image/upload/v1771522360/Palfrey/Logo/logo_ocxyty.png" alt='Palfrey'></a>
+</p>
+
+<p align="center">
+    <em>Palfrey is a clean-room, high-performance Python ASGI server with source-traceable parity mapping.</em>
+</p>
+
+<p align="center">
+<a href="https://github.com/dymmond/palfrey/actions/workflows/ci.yml/badge.svg?event=push&branch=main" target="_blank">
+    <img src="https://github.com/dymmond/palfrey/actions/workflows/ci.yml/badge.svg?event=push&branch=main" alt="Test Suite">
+</a>
+
+<a href="https://pypi.org/project/palfrey" target="_blank">
+    <img src="https://img.shields.io/pypi/v/palfrey?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+
+<a href="https://pypi.org/project/palfrey" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/palfrey.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://palfrey.dev](https://palfrey.dev) 📚
+
+**Source Code**: [https://github.com/dymmond/palfrey](https://github.com/dymmond/palfrey)
+
+**The official supported version is always the latest released**.
+
+---
+
+Palfrey is a clean-room ASGI server focused on three things:
+
+- behavior you can reason about
+- deployment controls you can operate safely
+- performance you can reproduce and verify
+
+Protocol runtime modes include HTTP/1.1 backends plus opt-in HTTP/2 (`--http h2`) and HTTP/3 (`--http h3`) paths.
+
+This documentation is written for both technical and non-technical readers.
+
+- Engineers can use the protocol details, option tables, and runbooks.
+- Product, support, and operations teams can use the plain-language summaries and checklists.
+
+## What Palfrey Does
+
+At runtime, Palfrey sits between clients and your ASGI application.
+
+1. accepts TCP or UNIX socket connections
+2. parses protocol bytes into ASGI events
+3. calls your app with `scope`, `receive`, `send`
+4. writes responses back to clients
+5. manages process behavior (reload, workers, graceful shutdown)
+
+## Who Should Start Where
+
+## If you are new to ASGI
+
+1. [Installation](getting-started/installation.md)
+2. [Quickstart](getting-started/quickstart.md)
+3. [Terms and Mental Models](concepts/terms-and-mental-models.md)
+4. [Server Behavior](concepts/server-behavior.md)
+
+## If you operate production services
+
+1. [Deployment](operations/deployment.md)
+2. [Workers](operations/workers.md)
+3. [Observability](operations/observability.md)
+4. [Troubleshooting](guides/troubleshooting.md)
+5. [Release Process](operations/release-process.md)
+
+## First 60 Seconds
+
+Create `main.py`:
+
+```python
+async def app(scope, receive, send):
+    """Return a plain-text greeting for HTTP requests."""
+    if scope["type"] != "http":
+        return
+
+    body = b"Hello from Palfrey"
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                (b"content-type", b"text/plain; charset=utf-8"),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+```
+
+Run Palfrey:
+
+```bash
+palfrey main:app --host 127.0.0.1 --port 8000
+```
+
+Check it:
+
+```bash
+curl http://127.0.0.1:8000
+```
+
+Gunicorn + Palfrey worker:
+
+```bash
+gunicorn main:app -k palfrey.workers.PalfreyWorker -w 4 -b 0.0.0.0:8000
+```
+
+## Documentation Structure
+
+## Getting Started
+
+- install, verify, and run your first app
+- move from a minimal app to real startup patterns
+
+## Concepts
+
+- what ASGI is, and how Palfrey applies it
+- how HTTP, WebSocket, and lifespan flows behave
+- how server internals affect user-visible outcomes
+
+## Reference
+
+- full CLI and config surface
+- protocol and logging behavior
+- env var model and common errors
+
+## Guides
+
+- migration, security hardening, production rollout
+- practical troubleshooting and FAQ
+
+## Operations
+
+- deployment shapes, workers, reload model
+- capacity planning, observability, benchmark method
+- platform-specific notes and release process
+
+## Plain-Language Summary
+
+If your application is the business logic, Palfrey is the runtime control layer around it.
+A good runtime control layer gives teams:
+
+- predictable startup and shutdown
+- fewer surprises under traffic spikes
+- clearer incident response paths
+- safer, repeatable deployments

palfrey-0.1.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark package for Palfrey performance comparisons."""

palfrey-0.1.0/benchmarks/apps.py

@@ -0,0 +1,39 @@
+"""Benchmark ASGI application targets."""
+
+from __future__ import annotations
+
+
+async def app(scope, receive, send):
+    """Serve HTTP and WebSocket echo paths for benchmark workloads."""
+
+    if scope["type"] == "lifespan":
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+    if 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"pong"})
+        return
+
+    if scope["type"] == "websocket":
+        await send({"type": "websocket.accept"})
+        while True:
+            message = await receive()
+            if message["type"] == "websocket.disconnect":
+                return
+            if message["type"] == "websocket.receive":
+                if "text" in message:
+                    await send({"type": "websocket.send", "text": message["text"]})
+                else:
+                    await send({"type": "websocket.send", "bytes": message.get("bytes", b"")})