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.