palfrey 0.1.2

A clean-room ASGI server with Uvicorn-compatible CLI and behavior mapping.

Palfrey

Palfrey is a clean-room, high-performance Python ASGI server with source-traceable parity mapping.

---

Documentation: https://palfrey.dymmond.com 📚

Source Code: 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.

Palfrey vs Uvicorn

Palfrey was built with deep respect for Uvicorn and the ASGI ecosystem it helped mature. This is not a "winner vs loser" comparison. Uvicorn is an excellent, battle-tested server, and Palfrey intentionally keeps a compatible API/CLI experience so teams coming from Uvicorn feel at home. Our goal is to offer another strong option when teams want different internal architecture and extended runtime capabilities.

Benchmark snapshot (your run):

• Command: python benchmarks/run.py --http-requests 50000

Scenario	Palfrey Ops/s	Uvicorn Ops/s	Relative Speed
HTTP	36793.21	22021.90	1.671x
WebSocket	36556.28	13822.97	2.645x

These numbers are environment-dependent. Always benchmark with your own app, traffic profile, and infrastructure before making production decisions.

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
2. Quickstart
3. Terms and Mental Models
4. Server Behavior

If you operate production services

1. Deployment
2. Workers
3. Observability
4. Troubleshooting
5. Release Process

First 60 Seconds

Create main.py:

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:

palfrey main:app --host 127.0.0.1 --port 8000

Check it:

curl http://127.0.0.1:8000

Gunicorn + Palfrey worker:

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