PAGI Distribution Split

The news: PAGI is now three CPAN distributions instead of one.

• PAGI-Server — the reference server
• PAGI-Tools — the application toolkit
• PAGI — the specification

Install what you actually run

In practice, almost everyone starts the same way: cpanm PAGI::Server to get a server that runs PAGI apps, and probably PAGI::Tools for the request/response helpers, router, and middleware you'll want while building one. That's the common case, and the split is built around it — you install the pieces you use instead of swallowing one monolith that bundled the server, the toolkit, and the spec together.

Underneath both sits the specification : a small, deliberately stable contract — the shape of $scope, $receive, $send, and the event types — that the server and the toolkit both implement. Keeping it in its own distribution is the real reason to split: the fast-moving parts (the server and the toolkit, where the churn actually lives) can iterate freely without destabilizing the protocol you write your apps against.

To be candid: today there is exactly one reference server, so "just depend on the bare spec" isn't something most people will do yet. That separation is forward-looking — it's what makes an alternative server, or a framework built straight on the protocol, possible without forking everything else. The split lays that groundwork; it isn't pretending it's already the common path.

And nothing breaks in the meantime: installing PAGI still pulls in the server and toolkit as dependencies during the transition, so cpanm PAGI gives you the whole stack exactly as before. That convenience dependency is temporary — depend on PAGI::Server and/or PAGI::Tools directly when you're ready.

What's notable in each

PAGI-Server — the reference server. An IO::Async-based implementation handling HTTP/1.1, HTTP/2, WebSocket, SSE, TLS, and multi-worker pre-forking, with the pagi-server CLI and a swappable-server runner. It's validated against a compliance suite, and any server implementing the documented contract is a drop-in alternative — which is exactly the door the split holds open.

PAGI-Tools — the toolkit. The ergonomics you reach for when actually building apps: a router and a class-based endpoint framework, a middleware suite, ready-made apps (static files, proxy, a PSGI bridge), and Request/Response/Context helpers. A few highlights: PAGI::Response is now a value you build and then send (a clean split between assembling a response and committing it to the wire), a new ordered, case-insensitive PAGI::Headers container, and a to_app coercion that lets every composition point accept coderefs, objects, or class names interchangeably. An in-process PAGI::Test::Client lets you test apps without a live server.

PAGI — the spec. Now pure documentation (the module plus the PAGI::Spec::* POD) and the canonical place to start: the tutorial, a cookbook, a PSGI migration guide, and a guide for framework authors. Recent protocol work made connection state observable — pagi.connection gained response_started / response_complete as observer-independent facts — pinned down scope shallow-clone semantics (how per-request state is shared vs. isolated through middleware), and now mandates server-side header byte-safety (a server must reject CR/LF/NUL in header names and values rather than forwarding or silently rewriting them).

Status, and a note

The specification is stable — breaking changes won't be made except for critical security issues, so raw PAGI apps you write today keep working. The server and toolkit are beta : solid, but not yet battle-tested in production, so run the server behind nginx/Apache/Caddy for now.

PAGI is a labor of love for the future of async web programming in Perl. The project is dedicated to the memory of Matt S. Trout, who encouraged the author's first CPAN contribution two decades ago — without which none of this would exist.

To kick the tires:

cpanm PAGI::Server PAGI::Tools
pagi-server --app ./app.pl --port 5000

Feedback, bug reports, and contributions are all welcome. Start with the tutorial; if you're coming from PSGI, the migration guide maps the mental model across.