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.
Top comments (0)