DEV Community: John Napiorkowski

Perl PAGI Middleware

John Napiorkowski — Sun, 28 Jun 2026 00:20:24 +0000

Middleware in PAGI

A port of the sample app from What Is Middleware? — which builds the same three-layer stack in Plack/PSGI (Perl) and Starlette/ASGI (Python) — to PAGI, an async, ASGI-style application interface for Perl.

The app is deliberately tiny but exercises the three things middleware exists to do:

Logger — wrap the request, time it, log method/path in and status/duration out.
Authenticator — inspect a header, inject context for downstream layers on success, or short-circuit with a 401 on failure.
ProfileRouter — answer one specific route from inside the stack, reading the context the Authenticator injected.

All code below was run under perl-5.40.0 with PAGI::Test::Client; the log lines and responses shown in Running it are the actual captured output, not hand-written.

The PAGI middleware contract

A PAGI application is, in the spec's words, "a single coderef returning a Future": an async sub over the ($scope, $receive, $send) triple — the same shape as ASGI. $scope is the per-connection metadata hash (type, method, path, headers, …), $receive pulls inbound events, $send pushes outbound ones (http.response.start, then http.response.body), and the Future it returns resolving is what tells the server the response is complete.

Middleware is just as plain: a subroutine that takes an application and returns a new application, wrapping the inner one. That is the whole spec-level contract — app in, app out:

sub middleware {
    my ($app) = @_;
    return async sub ($scope, $receive, $send) {
        # ... before ...
        await $app->($scope, $receive, $send);   # call the inner app
        # ... after ...
    };
}

A middleware propagates the inner app's Future — its completion and any exception flow straight through — and never reads its return value, which the spec defines as inert; to observe or rewrite the response it wraps $send instead, and to add per-request context it clones $scope (top-level edits stay visible downward only).

PAGI::Middleware, from PAGI-Tools rather than the spec, is a thin convenience layer over exactly that contract. Instead of a bare sub you get a small class whose wrap($app) returns the same app-to-app coderef:

sub wrap ($self, $app) {
    return async sub ($scope, $receive, $send) {
        # ... before ...
        await $app->($scope, $receive, $send);   # call the inner app
        # ... after ...
    };
}

It earns its keep mainly through PAGI::Middleware::Builder: you get a new/_init config constructor, the modify_scope / intercept_send helpers, and a wrap method the builder's enable knows how to call. The three middleware below all take this form — but it's sugar over the plain subroutine above, not a different thing.

From that single seam you get every middleware behaviour:

Behaviour	How
Observe the response	wrap `$send` in your own async sub and watch the events flow by
Inject per-request context	`$self->modify_scope($scope, { key => $value })` and pass the copy down
Short-circuit	render your own response with `$send` and don't call `$app`
Pass non-HTTP through	check `$scope->{type}` and delegate untouched

Two notes on how this maps from the original article:

Context injection. PSGI mutates $env->{'custom.user_id'}; Starlette sets request.state.user_id. PAGI uses modify_scope, which shallow-copies the scope and merges your additions, then hands the copy to the inner app. The data is visible to everything downstream but never leaks back up to outer middleware — injection without global mutation.
Responses are values. PAGI::Response->json($data) builds a response object you can pass around; ->respond($send) is what actually writes it to the connection. Short-circuiting is just "build a response and respond, skip $app."

Why wrap($app) as the base shape? The Starlette version subclasses BaseHTTPMiddleware and overrides dispatch(request, call_next) — which reads beautifully: you await call_next(request) and get a Response back. The ergonomics are lovely; the trouble is how Starlette implements call_next. It runs the inner app in a separate task feeding an in-memory stream, and that plumbing is what adds overhead and is known to trip over streaming responses, background tasks, and context propagation. It's also HTTP-only — anything touching WebSocket or lifespan traffic, or transforming a streaming body, has to drop to the raw ASGI form regardless. So PAGI makes the raw form — wrap($app) over ($scope, $receive, $send) — the substrate every middleware is built on: it can express everything, with no hidden task or stream in the path. A call_next-style value-passing convenience can be layered on top of that substrate without inheriting the plumbing; what you don't want is to make the lossy, HTTP-only version the foundation.

Logger middleware

Times the request across the inner app and logs a line on the way in and on the way out. To learn the final status, it wraps $send and remembers the status off the http.response.start event.

package MyApp::Middleware::Logger;

use v5.40;
use parent 'PAGI::Middleware';
use Future::AsyncAwait;
use Time::HiRes qw(time);

sub wrap ($self, $app) {
    return async sub ($scope, $receive, $send) {

        # Pass through anything that isn't an HTTP request
        # (lifespan, websocket, sse) untouched.
        return await $app->($scope, $receive, $send)
          unless $scope->{type} eq 'http';

        my $start_time = time();
        say "[LOG] Incoming: $scope->{method} $scope->{path}";

        # Intercept the outgoing stream so we can observe the final status.
        my $status;
        my $wrapped_send = async sub ($event) {
            $status = $event->{status}
                if $event->{type} eq 'http.response.start';
            await $send->($event);
        };

        await $app->($scope, $receive, $wrapped_send);

        my $elapsed = time() - $start_time;
        printf "[LOG] Outgoing Status: %d (Processed in %.4f seconds)\n",
            $status, $elapsed;
    };
}

1;

The PSGI original returns a [$status, $headers, $body] arrayref it can read directly. In PAGI (as in ASGI) the response is streamed as events, so the idiomatic move is to wrap $send and observe http.response.start — exactly what the bundled PAGI::Middleware::Runtime and PAGI::Middleware::AccessLog do.

Authenticator middleware

Reads X-Auth-Token. On the magic value it logs, injects user_id => 456 for the layers below, and continues. Otherwise it logs and short-circuits with a 401 — the inner app is never called.

package MyApp::Middleware::Authenticator;

use v5.40;
use parent 'PAGI::Middleware';
use Future::AsyncAwait;
use PAGI::Request;
use PAGI::Response;

sub wrap ($self, $app) {
    return async sub ($scope, $receive, $send) {

        return await $app->($scope, $receive, $send)
          unless $scope->{type} eq 'http';

        my $req   = PAGI::Request->new($scope, $receive);
        my $token = $req->header('X-Auth-Token');

        unless (defined $token && $token eq 'secret-password-123') {
            say "[AUTH] Access Denied. Short-circuiting.";

            # Short-circuit: never call $app. A response is just a value we
            # render onto the connection ourselves.
            return await PAGI::Response->text('Unauthorized', status => 401)
                ->respond($send);
        }

        say "[AUTH] Valid token. Granting access to User #456.";

        # Inject per-request context for downstream layers. modify_scope
        # shallow-copies the scope so the addition is only visible to the
        # inner app, never leaking back out to middleware above us.
        my $authed_scope = $self->modify_scope($scope, { user_id => 456 });

        await $app->($authed_scope, $receive, $send);
    };
}

1;

PAGI::Request is a convenience wrapper over the raw scope — $req->header('X-Auth-Token') is case-insensitive, just like $req->header(...) in the Plack version. (For a real app, PAGI::Middleware::Auth::Bearer ships this pattern as a configurable building block.)

ProfileRouter middleware

If the path is /api/profile, it answers directly with JSON — reading the user_id the Authenticator injected, defaulting to 'Guest' if it somehow ran without auth. Any other path falls through to whatever is below.

package MyApp::Middleware::ProfileRouter;

use v5.40;
use parent 'PAGI::Middleware';
use Future::AsyncAwait;
use PAGI::Response;

sub wrap ($self, $app) {
    return async sub ($scope, $receive, $send) {

        # Not our route — hand off to the inner app.
        return await $app->($scope, $receive, $send)
          unless $scope->{type} eq 'http' && $scope->{path} eq '/api/profile';

        # Read the context the Authenticator injected upstream.
        say "[ROUTER] Handling /api/profile directly inside middleware.";

        my $data = {
            user_id => $scope->{user_id} // 'Guest',
            name    => 'Alice Perl',
            status  => 'Fully Delegated Architecture',
        };

        await PAGI::Response->json($data)->respond($send);
    };
}

1;

$scope->{user_id} here is the PAGI counterpart to $env->{'custom.user_id'} (PSGI) and request.state.user_id (Starlette). It is present because modify_scope put it on the copy that flowed down from the Authenticator.

Assembling the app

PAGI ships a Plack::Builder-style DSL in PAGI::Middleware::Builder. The shape mirrors the original builder { enable ...; $fallback } almost line for line:

#!/usr/bin/env perl

use v5.40;
use lib 'lib';

use PAGI::Middleware::Builder;
use PAGI::Response;

# Compose the stack, outermost first. Logger wraps Authenticator wraps
# ProfileRouter wraps the 404 fallback. The '^' prefix means "this is a
# fully-qualified class name", the PAGI equivalent of Plack's '+'.
#
# The fallback is just a Response value: the builder coerces its final
# expression through PAGI::Utils::to_app, and a PAGI::Response knows how to
# turn itself into an app. It fires only when no middleware short-circuited.
builder {
    enable '^MyApp::Middleware::Logger';
    enable '^MyApp::Middleware::Authenticator';
    enable '^MyApp::Middleware::ProfileRouter';
    PAGI::Response->text('Resource Not Found', status => 404);
};

Because a response is a value in PAGI, the fallback needs no wrapper coderef — the builder accepts the PAGI::Response object directly and calls its to_app for you. (The original PSGI version needs the explicit sub { [404, …] } because PSGI's inner app must be a callable.)

The one syntactic difference worth flagging: where Plack writes enable '+MyApp::Middleware::Logger' to mean "don't prepend the framework namespace," PAGI writes enable '^MyApp::Middleware::Logger'. Bare names like enable 'Runtime' are resolved to PAGI::Middleware::Runtime; the ^ opts out of that prefixing.

Middleware runs outermost-first, so the request flows Logger → Authenticator → ProfileRouter → fallback and the response unwinds back out through the same layers — which is why the Logger sees the final status of whatever any inner layer produced.

Running it

The example is exercised in-process with PAGI::Test::Client, which constructs the ($scope, $receive, $send) messages and invokes the app directly — no socket required.

use v5.40;
use lib 'lib';

use Test2::V0;
use JSON::MaybeXS qw(decode_json);
use PAGI::Test::Client;

my $app    = do './app.pl';
my $client = PAGI::Test::Client->new(app => $app);

subtest 'no token: Authenticator short-circuits with 401' => sub {
    my $res = $client->get('/api/profile');

    is $res->status, 401,            'status is 401';
    is $res->text,   'Unauthorized', 'body is Unauthorized';
};

subtest 'valid token + /api/profile: ProfileRouter answers with JSON' => sub {
    my $res = $client->get('/api/profile',
        headers => { 'X-Auth-Token' => 'secret-password-123' },
    );

    is $res->status, 200, 'status is 200';
    is decode_json($res->text),
        {
            user_id => 456,
            name    => 'Alice Perl',
            status  => 'Fully Delegated Architecture',
        },
        'profile payload, with user_id injected by the Authenticator';
};

subtest 'valid token + unknown path: falls through to 404' => sub {
    my $res = $client->get('/somewhere/else',
        headers => { 'X-Auth-Token' => 'secret-password-123' },
    );

    is $res->status, 404,                  'status is 404';
    is $res->text,   'Resource Not Found', 'fallback body';
};

done_testing;

Test2::V0's is does a deep, structural comparison, so the whole profile payload is checked in one assertion instead of field by field.

Actual output (prove -v), with the middleware's own [LOG]/[AUTH]/[ROUTER] lines interleaved:

[LOG] Incoming: GET /api/profile
[AUTH] Access Denied. Short-circuiting.
[LOG] Outgoing Status: 401 (Processed in 0.0001 seconds)
ok 1 - no token: Authenticator short-circuits with 401 {
    ok 1 - status is 401
    ok 2 - body is Unauthorized
    1..2
}
[LOG] Incoming: GET /api/profile
[AUTH] Valid token. Granting access to User #456.
[ROUTER] Handling /api/profile directly inside middleware.
[LOG] Outgoing Status: 200 (Processed in 0.0002 seconds)
ok 2 - valid token + /api/profile: ProfileRouter answers with JSON {
    ok 1 - status is 200
    ok 2 - profile payload, with user_id injected by the Authenticator
    1..2
}
[LOG] Incoming: GET /somewhere/else
[AUTH] Valid token. Granting access to User #456.
[LOG] Outgoing Status: 404 (Processed in 0.0001 seconds)
ok 3 - valid token + unknown path: falls through to 404 {
    ok 1 - status is 404
    ok 2 - fallback body
    1..2
}
1..3
ok
All tests successful.

The JSON body for the authorized profile request is, verbatim:

{"name":"Alice Perl","status":"Fully Delegated Architecture","user_id":456}

(PAGI::Response->json encodes with sorted keys, which is why they come out alphabetical.)

To run it against a real server instead of the test client, the same app.pl is a complete PAGI application — point a PAGI server at it:

pagi-server --app app.pl --port 5000

curl http://localhost:5000/api/profile                                  # 401
curl -H 'X-Auth-Token: secret-password-123' http://localhost:5000/api/profile   # JSON

How it lines up with the original

Concern	Plack / PSGI	Starlette / ASGI	PAGI
Middleware unit	`Plack::Middleware` + `call($env)`	`BaseHTTPMiddleware` + `dispatch(request, call_next)`	`PAGI::Middleware` + `wrap($app)` returning an async sub
Inner app handle	`$self->app->($env)`	`await call_next(request)`	`await $app->($scope, $receive, $send)`
Read a header	`$req->header('X-Auth-Token')`	`request.headers.get(...)`	`$req->header('X-Auth-Token')`
Inject context	`$env->{'custom.user_id'} = 456`	`request.state.user_id = 456`	`$self->modify_scope($scope, { user_id => 456 })`
Short-circuit	return `[401, …]`	return `PlainTextResponse(...)`	build a `PAGI::Response`, `->respond($send)`, skip `$app`
Compose stack	`builder { enable '+...'; $fallback }`	`Starlette(middleware => [...])`	`builder { enable '^...'; $fallback }`

The structure ports essentially one-to-one. The only conceptual shift from PSGI is the one the Python version already makes: responses are streamed events rather than a returned tuple, so "look at the response" means wrapping $send, and "context" lives on a copied scope rather than a mutated environment.

PAGI Distribution Split

John Napiorkowski — Sat, 27 Jun 2026 01:26:47 +0000

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.

Perl PAGI Project Updates

John Napiorkowski — Thu, 18 Jun 2026 15:31:36 +0000

Quick update to anyone interested in upcoming changes to the PAGI project (spiritual successor to Plack/PSGI).

1) Distribution split up: when we released PAGI, we initially released everything as one distribution. PAGI (https://metacpan.org/pod/PAGI) currently has a) the PAGI specification; b) the reference server and c) a bunch of ease of use tools, similar to the role that the Plack distribution played for PSGI. Putting everything into one place was just to make my life easier as in the early bunch of releases there was a lot of fixes and updates, most of which cut across all three parts of PAGI. Also I wanted to make it easy for people getting into PAGI to be able to explore the ecosystem. However now that code seems to be settling down having these in independent repos and releases makes more sense. Going forward the PAGI repo will only update if the spec itself changes; PAGI::Server and PAGI::Tools (where all the utilities and helpers now go) likewise. I think this will start to bring some stability to the ecosystem, especially now that PAGI::Server is functionally complete based on the goal chart I had for it initially. So I will only update it to fix bugs and security issues.

PAGI::Tools will probably continue to see evolution over the summer as I start to nail down more common use cases and identify patterns worth encapsulating.

2) Specification clarifications and updates: The PAGI specification itself will move to v0.3 in the next release and it contains mostly clarifications and fixes. Biggest change will be a more detailed mechanism for controlling streaming output, especially around handling back pressure as well as new callbacks to notice when the output buffer is getting full and when it clears. Hopefully these changes will make it easier and more reliable to do streaming in PAGI. PAGI::Server has been updated to match, and the response helper in PAGI::Tools has some updates around that as well.

Currently all this sits on Github:

https://github.com/jjn1056/pagi
https://github.com/jjn1056/PAGI-Server
https://github.com/jjn1056/PAGI-Tools

Right now I'm giving the Thunderhorse author some time to vet a handful of changes needed to be compatible and I want to review all the updates and doc tweaks one last time. This will land on CPAN before the Austin Perl Community conference first week of July (where I will be presenting on PAGI for those interested).
For people who might currently be depending on the PAGI distribution, for the near term I will have PAGI::Server and PAGI::Tools as dependencies of PAGI, that way your currently toolchains don't break. That will last a few months for transition.

PAGI::Server, now with HTTP/2!

John Napiorkowski — Wed, 11 Feb 2026 19:05:39 +0000

PAGI 0.001017 is on CPAN. The headline feature is HTTP/2 support in PAGI::Server, built on the nghttp2 C library and validated against h2spec's conformance suite. HTTP/2 is marked experimental in this release -- the protocol works, the compliance numbers are solid, and we want production feedback before dropping that label.

This post focuses on why h2c (cleartext HTTP/2) between your reverse proxy and backend matters, and how PAGI::Server implements it.

The Quick Version

# Install the HTTP/2 dependency
cpanm Net::HTTP2::nghttp2

# Run with HTTP/2 over TLS
pagi-server --http2 --ssl-cert cert.pem --ssl-key key.pem app.pl

# Run with cleartext HTTP/2 (h2c) -- behind a proxy
pagi-server --http2 app.pl

Your app code doesn't change. HTTP/2 is a transport concern handled entirely by the server. The same async handlers that serve HTTP/1.1 serve HTTP/2 without modification.

"I Have nginx in Front, Why Do I Care?"

If nginx terminates TLS and speaks HTTP/2 to clients, why does the backend need HTTP/2 too?

The answer is h2c -- cleartext HTTP/2 between your proxy and your application server. No TLS overhead, but all of HTTP/2's protocol benefits on the internal hop: stream multiplexing over a single TCP connection, HPACK header compression (especially effective for repetitive internal headers like auth tokens and tracing IDs), and per-stream flow control so a slow response on one stream doesn't block others.

The practical wins: fewer TCP connections between proxy and backend (one multiplexed h2c connection replaces a pool of HTTP/1.1 connections), less file descriptor and kernel memory pressure, and no TIME_WAIT churn from connection recycling.

Where h2c Matters

gRPC requires HTTP/2 -- it doesn't work over HTTP/1.1 at all. If you're building gRPC services, h2c is mandatory.

API gateway fan-out is where multiplexing shines. When your gateway fans out to 10 backend services per request, h2c means 1-2 connections per backend instead of a pool of 50-100.

Service mesh environments (Envoy/Istio sidecars) default to HTTP/2 between services. A backend that speaks h2c natively means one less protocol translation.

A Note on Proxies

Not all proxies handle h2c equally:

Envoy has the best h2c upstream support with full multiplexing
Caddy makes it trivial: reverse_proxy h2c://localhost:8080
nginx supports h2c via grpc_pass for gRPC workloads, but its generic proxy_pass doesn't support proxy_http_version 2.0

For full multiplexing to backends, Envoy or Caddy are better choices than nginx today.

HTTP/2 Over TLS -- No Proxy Required

h2c isn't the only mode. PAGI::Server also does full HTTP/2 over TLS with ALPN negotiation:

pagi-server --http2 --ssl-cert cert.pem --ssl-key key.pem app.pl

This is useful when you don't want the overhead or complexity of a reverse proxy -- internal tools, admin dashboards, development servers, or any app where the traffic doesn't justify a separate proxy layer. Browsers get HTTP/2 directly, with TLS, no nginx required.

What PAGI::Server Does

Dual-Mode Protocol Detection

With TLS, PAGI::Server uses ALPN negotiation during the handshake -- advertising h2 and http/1.1, letting the client choose. The protocol is decided before the first byte of application data.

Without TLS (h2c mode), PAGI::Server inspects the first 24 bytes of each connection for the HTTP/2 client connection preface. If it matches, the connection upgrades to HTTP/2. If not, it falls through to HTTP/1.1. Both protocols coexist on the same port, same worker -- no configuration needed beyond --http2.

Either way, HTTP/1.1 clients are still served normally. The server handles both protocols on the same port.

WebSocket over HTTP/2 (RFC 8441)

Most HTTP/2 implementations skip this. PAGI::Server supports the Extended CONNECT protocol from RFC 8441, which tunnels WebSocket connections over HTTP/2 streams. Multiple WebSocket connections multiplex over a single TCP connection instead of requiring one TCP connection each.

Compliance

Built on nghttp2 (the same C library behind curl, Firefox, and Apache's mod_http2). PAGI::Server passes 137 of 146 h2spec conformance tests (93.8%). The 9 remaining failures are in nghttp2 itself and shared with every server that uses it. Load tested with h2load at 60,000 requests across 50 concurrent connections with no data loss or protocol violations.

Full test-by-test results are published: HTTP/2 Compliance Results.

Multi-Worker and Tunable

HTTP/2 works in multi-worker prefork mode. Each worker independently handles HTTP/2 sessions:

pagi-server --http2 --workers 4 app.pl

Protocol settings are exposed for environments that need fine-tuning:

my $server = PAGI::Server->new(
    app   => $app,
    http2 => 1,
    h2_max_concurrent_streams => 50,   # default: 100
    h2_initial_window_size => 131072,  # default: 65535
    h2_max_frame_size => 32768,        # default: 16384
    h2_max_header_list_size => 32768,  # default: 65536
);

Most deployments won't need to touch these. The defaults follow the RFC recommendations.

Context in the Perl Ecosystem

Perl has had HTTP/2 libraries on CPAN (Protocol::HTTP2, Net::HTTP2), but application servers haven't integrated them with validated compliance testing. PAGI::Server is the first to publish h2spec results and ship h2c with automatic protocol detection alongside HTTP/1.1. If you're currently running Starman, Twiggy, or Hypnotoad, none of them offer HTTP/2.

What Else Is in 0.001017

The rest of the release is operational improvements:

Worker heartbeat monitoring -- parent process detects workers with blocked event loops and replaces them via SIGKILL + respawn. Default 50s timeout. Only triggers on true event loop starvation; async handlers using await are unaffected.
Custom access log format -- format strings with atoms like %a (address), %s (status), %D (duration).
TLS performance fix -- shared SSL context via SSL_reuse_ctx eliminates per-connection CA bundle parsing. 26x throughput improvement at 8+ concurrent TLS connections.
SSE wire format fix -- now handles CRLF, LF, and bare CR line endings per the SSE specification.
Multi-worker fixes -- shutdown escalation, parameter pass-through, and various stability improvements.

Getting Started

# Install PAGI
cpanm PAGI

# Install HTTP/2 support (optional)
cpanm Net::HTTP2::nghttp2

# Run your app with HTTP/2
pagi-server --http2 app.pl

PAGI 0.001016: Navigating the Future::IO Configuration Problem

John Napiorkowski — Mon, 02 Feb 2026 18:34:13 +0000

PAGI 0.001016 includes a decision we wrestled with for a while: where should Future::IO configuration live? This post walks through the tradeoffs we considered and why we landed where we did.

What is Future::IO?

Perl's async ecosystem has multiple event loops: IO::Async, Mojo::IOLoop, AnyEvent, UV. This diversity is a strength - different loops have different strengths - but it creates a problem for library authors. If you write an async Redis client, which event loop do you target?

Future::IO solves this by providing an abstraction layer. Libraries code against Future::IO's API (sleep, read, write), and Future::IO delegates to whatever event loop is actually running. This means libraries like Async::Redis work with any event loop - IO::Async, UV, or anything else that has a Future::IO backend.

The catch: Future::IO needs to be told which backend to use. It doesn't auto-detect the running loop. Someone has to explicitly configure it:

use Future::IO;
Future::IO->load_impl('IOAsync');  # Tell Future::IO to use IO::Async

This configuration must happen before any Future::IO operations are attempted. Get it wrong - or forget it entirely - and things break in confusing ways.

The Problem

Given that Future::IO needs explicit configuration, who should do it? Someone has to call:

use Future::IO;
Future::IO->load_impl('IOAsync');  # or 'UV', etc.

The question is: who?

What Doesn't Work

A quick note: PAGI is built on the async Perl ecosystem created largely by Paul Evans (LeoNerd) - IO::Async, Future, and Future::IO. His guidance shaped our thinking here, and the constraints he identified are real engineering concerns, not arbitrary rules.

Libraries configuring Future::IO - This was our first instinct. Async::Redis could call Future::IO->load_best_impl to auto-detect the best backend. But load_best_impl picks based on what's installed, not what's running. If you have UV installed but you're running under IO::Async (like PAGI::Server), you get a mismatch. Things explode.

Paul's guidance: libraries shouldn't configure Future::IO because they don't know the runtime context. This makes sense - a library is a guest in someone else's application.

PAGI::Server (the module) configuring it - We tried this too. It seemed logical - PAGI::Server runs IO::Async, so it knows the context. But there's a legitimate concern: PAGI::Server is still a module being used, and someone might embed it in a larger application.

Consider: you're running PAGI::Server alongside other event-driven code - maybe a metrics collector, a background job processor, or a connection to a message queue. Your main script creates the IO::Async loop and adds multiple notifiers to it:

my $loop = IO::Async::Loop->new;

# Your other async code
$loop->add($metrics_reporter);
$loop->add($job_processor);

# PAGI::Server is just one component
my $server = PAGI::Server->new(app => $app, port => 8080);
$loop->add($server);

$loop->run;

In this scenario, the main script is the entry point, not PAGI::Server. If PAGI::Server configured Future::IO, it would be a module reaching out to modify global state - potentially conflicting with configuration the main script already set up. The principle that only entry points should configure global state exists precisely for cases like this.

The Tradeoffs We Considered

Option 1: Apps Configure Future::IO

The "pure" approach - make apps explicit about their dependencies:

# app.pl
use Future::IO;
Future::IO->load_impl('IOAsync');

use Async::Redis;
# ...

Pros: Explicit, no magic, apps declare what they need.

Cons: This fundamentally breaks PAGI's value proposition. The whole point of PAGI is write-once portability - your app should run under any PAGI-compliant server. If your app.pl says load_impl('IOAsync'), what happens when you want to run under Conduit (Paul's Future::IO-native web server that currently supports PSGI and may support PAGI in the future)? You'd have to change your app code to switch servers. That's exactly what PAGI exists to prevent.

I kept coming back to this. Boilerplate is annoying but tolerable. Breaking server-agnosticism is a dealbreaker.

Option 2: Extend the PAGI Spec

We could add async capabilities directly to the PAGI spec - have servers provide event loop primitives through the scope:

# Hypothetical: server provides async capabilities
$scope->{'pagi.sleep'} = sub { ... };
$scope->{'pagi.timeout'} = sub { ... };

Pros: Clean abstraction. Apps use spec-defined capabilities, servers implement them however they want. True portability.

Cons: Where does it stop? PAGI is modeled after Python's ASGI, which is deliberately minimal - it defines the request/response lifecycle and nothing more. Once you add sleep, what about DNS resolution? Database connections? HTTP clients?

The spec becomes a grab-bag of async primitives, and every PAGI server implementation has to support all of them. That's a maintenance burden that discourages new server implementations. ASGI's success comes partly from its simplicity - implementing a basic ASGI server is tractable.

Option 3: Entry Point Configures

Have pagi-server (the CLI script, not the module) configure Future::IO. The script is the application entry point.

Pros: Follows the "only entry points configure" principle. CLI users get zero-config experience.

Cons: Still feels like action at distance. Programmatic users of PAGI::Server must configure it themselves.

What We Chose

We went with Option 3. In pagi-server:

# In PAGI::Runner (called by pagi-server)
sub _configure_future_io {
    my ($self) = @_;

    my $configured = eval {
        require Future::IO::Impl::IOAsync;
        1;
    };

    if ($configured && $self->mode ne 'production' && !$self->{quiet}) {
        warn "Future::IO configured for IO::Async\n";
    }
}

The result:

pagi-server myapp.pl - Future::IO auto-configured, Async::Redis and other Future::IO libraries just work
PAGI::Server->new(...) programmatically - You configure Future::IO yourself

For programmatic usage, here's what that looks like:

#!/usr/bin/env perl
use strict;
use warnings;
use IO::Async::Loop;

# Configure Future::IO BEFORE loading libraries that use it
use Future::IO;
Future::IO->load_impl('IOAsync');

# Now these work correctly
use Async::Redis;
use PAGI::Server;

my $redis = Async::Redis->new(host => 'localhost');

my $app = sub {
    my ($scope, $receive, $send) = @_;
    # ... your app using $redis
};

my $loop = IO::Async::Loop->new;
my $server = PAGI::Server->new(app => $app, port => 8080);
$loop->add($server);
$server->listen->get;
$loop->run;

We're comfortable with this tradeoff. If you're writing your own server orchestration - creating loops, adding notifiers, managing the lifecycle - you're already in "I know what I'm doing" territory. You're the kind of developer who reads documentation about event loop integration. Adding two lines to configure Future::IO is not a burden for someone already writing fifteen lines of loop setup.

The CLI user who just wants pagi-server app.pl to work shouldn't need to know any of this. The power user embedding PAGI::Server in a custom harness can handle it. (See the LOOP INTEROPERABILITY section in PAGI::Server docs.)

Why This Felt Right (Eventually)

I had doubts. Isn't this still "magic"? Isn't the app implicitly depending on server configuration?

But here's the reframing that helped: configuring the async runtime is the server's job. Python's ASGI servers don't ask users to "configure asyncio" - the runtime just works. The server provides the execution environment.

The key insight is that this isn't about any single library. It's about the entire Future::IO ecosystem - database drivers, HTTP clients, Redis, message queues, and anything else built on Future::IO. These libraries represent the future of async Perl. If every PAGI user has to understand Future::IO configuration internals before using any of them, that's a barrier to adoption that hurts the whole ecosystem.

By having pagi-server configure Future::IO, we're saying: "When you run under pagi-server, Future::IO libraries work. That's part of what the server provides." It's similar to how Python's ASGI servers provide an asyncio environment - you don't configure the async runtime, you just use libraries that depend on it.

Also in This Release: SSE Query Parameters

PAGI::SSE now has query parameter parsing, matching PAGI::Request and PAGI::WebSocket:

my $sse = PAGI::SSE->new($scope, $receive, $send);

my $channel = $sse->query_param('channel');
my $params  = $sse->query_params;  # Hash::MultiValue

This is straightforward consistency work - all three scope types now have the same query parameter API.

This Is Experimental - RFC Welcome

I want to be clear: the Future::IO integration in this release is experimental. We've made a pragmatic choice that works, but I'm not certain it's the right long-term answer.

The PAGI spec will probably need to address async capability configuration at some point. I'm just not sure what that should look like yet. Should servers declare what async backend they use? Should there be a standard way for apps to discover capabilities? Should Future::IO configuration be part of the lifespan protocol?

I'm treating this release as a request for comments. If you have thoughts on:

Whether pagi-server auto-configuring Future::IO is the right call
How the PAGI spec should handle async ecosystem integration
Alternative approaches we haven't considered
Pain points you hit when using Future::IO libraries with PAGI

...I want to hear them. Please leave your thoughts on GitHub issue #33, which I've opened specifically for this discussion.

PAGI is a PSGI-like specification for async Perl web applications. Feedback welcome at github.com/jjn1056/pagi.

The #1 sentence I add to prompts that makes them better

John Napiorkowski — Sun, 25 Jan 2026 00:16:51 +0000

Prompt Engineering or selling your soul?

If you use AI at work, you’ve probably had this experience:

You write a prompt that feels clear enough, hit enter, and the model confidently produces something that is… technically fine… but not what you meant.

Maybe it built the right thing in the wrong style.
Maybe it chose an approach you would never ship.
Maybe it made assumptions you didn’t realize you were leaving unstated.

I’ve started treating prompts like a contract with the devil.

Not because I think AI is evil — just because it’s literal, opportunistic, and perfectly willing to sprint in the wrong direction if you give it even a small opening.

And you can’t cover every edge case up front.

So here’s the one sentence I add to a lot of my prompts that consistently makes the results better:

Before you begin, ask any clarifying questions you need to fully understand what I’m asking and to do an excellent job.

Why it works (and why it’s “vibe engineering”)

Most prompting advice is basically: be more specific.

That’s true, but it’s incomplete — because the whole problem is that you often don’t realize what you forgot to specify.

This sentence flips the dynamic:

Instead of “I describe something and hope the AI guesses right,”
it becomes collaborative.

It turns the model into a reviewer before it becomes an implementer.

And it forces the “unknown unknowns” to show up early, while it’s still cheap to correct.

The kind of questions that save you

My favorite clarifying questions are the ones that expose missing context I didn’t realize mattered.

Like:

“Is there an existing system you want me to use as a template?”
“Is this a large table / high-traffic database?”
“Is this safe to run during business hours?”
“What does success look like: correctness, speed, low risk, or minimal code changes?”
“Do you care about test coverage, or just a working fix?”

Those questions aren’t just helpful to the AI.

They’re helpful to me.

Because half the time, I’m using the AI to tease out details I forgot to include in the prompt in the first place.

A realistic failure mode this prevents

Say you ask:

“Write a migration to backfill X safely.”

The AI might happily generate a perfectly valid migration that:

locks the table,
runs as one big transaction,
does a full scan,
adds an index in a way that takes forever,
and generally assumes the world is a small quiet sandbox.

It’s not “wrong” — it’s just not something you want to discover after you already committed to the approach.

If you make the model interview you first, you’ll often get the question you forgot to say out loud:

“How large is the table, and can this run on prod without blocking writes?”

That one question can save you a very annoying afternoon.

When I don’t use it

I don’t paste this sentence into every single prompt.

If I’m asking something small and obvious (“write this one-liner”, “explain this error”, “rename these variables”), it’s unnecessary overhead.

But if I’m doing any of these, it comes out almost automatically:

writing something new (a real feature, not a snippet)
debugging a complex problem
anything with multiple moving parts
anything where “technically correct” can still waste time

Copy/paste template you can steal

Here’s a version you can drop into your own prompts:

My default prompt preamble

Before you begin, ask any clarifying questions you need to fully understand what I’m asking and to do an excellent job.

Optional follow-up (if you want to be extra explicit)

If something is ambiguous, don’t guess — ask.
If there are multiple valid approaches, list the options and tell me what you recommend and why.
After questions are answered, produce the output in a clean, usable format.

That’s it.

It’s not magic. It doesn’t make the model smarter.

It just keeps the process collaborative instead of “write a prompt and hope for the best.”

Teaser: if you want to hear about the #2 sentence I add to prompts to make them even better, get me to 100 likes 😄

PAGI::Server: Stress-Testing an Async Perl HTTP Server the Hard Way

John Napiorkowski — Thu, 01 Jan 2026 21:52:45 +0000

Over the last few days I’ve been stress-testing PAGI::Server, an async HTTP server built on IO::Async, Future::IO, and an EV event loop. The goal wasn’t to chase synthetic “requests per second” numbers, but to answer harder questions:

Does streaming actually behave correctly?
What happens under sustained concurrency?
Do slow clients cause buffer bloat?
Does backpressure really work?
How does it fail under overload?

This post summarizes what I learned by pushing the server well past “normal” workloads and watching it misbehave — or not.

Architecture in one paragraph

PAGI::Server is:

single-process, event-driven by default
optionally multi-process via workers
fully async end-to-end (no threads)
streaming-first (responses are not buffered by default)
designed to support ASGI-like semantics in Perl

The server accepts connections in a main event loop and routes work through IO::Async::Stream objects. Application code produces responses via a $send callback that emits protocol events (http.response.start, http.response.body, etc.).

That last part matters, because it’s where most async servers quietly cheat.

An important note: Although PAGI::Server is IO::Async based, that is an implementation detail, not a core requirement of the PAGI specification. That said I build PAGI::Server on IO::Async because it's mature, battle tested and fully featured.

Baseline: fast responses

Before touching streaming, I tested a trivial HTTP handler.

On an older 16-core MacBook Pro:

~22–23k requests/sec
p50 latency ~20ms
p99 < 50ms
CPU mostly idle

Nothing surprising here — just confirming there’s no accidental serialization or blocking in the accept loop.

Just to set some baselines, I tested a simple, similar PSGI application using Starman, one of the most popular choices for serving PSGI apps, and I found it topped out at around 16K requests/sec, with significantly worse latency spread and dropped connections.

Streaming test: 2-second responses, 500 concurrent clients

Next, I switched to a streaming handler that sends chunks over ~2 seconds.

With 500 concurrent connections, single process:

~242–245 requests/sec
p50 ≈ 2.00s
p99 ≈ 2.3–2.4s
CPU ~10–20% busy
memory stable

This matters because the math checks out:

500 concurrent / 2 seconds ≈ 250 rps theoretical max

Hitting ~97–98% of theoretical max strongly suggests:

no head-of-line blocking
no per-connection threads
no accidental buffering

The server is doing what an async server should do: waiting, not working.

A gotcha: TTY logging will ruin your benchmark

One early run looked worse than expected. The cause was embarrassingly simple:

Access logging was printing to a terminal (TTY).

At ~20k+ log lines/sec, the terminal became the bottleneck.

Once logging was disabled or redirected:

CPU usage dropped dramatically
latency tails tightened
throughput returned to theoretical limits

Lesson: never benchmark with synchronous TTY logging enabled.

Overload behavior: what happens at 2500 concurrent streams?

With ulimit -n = 2048, single-process PAGI::Server started rejecting connections around ~2000 open sockets.

That rejection path returned:

503 Service Unavailable
Retry-After: 5
Connection: close

This is good behavior.

Instead of accepting everything and melting down, the server applied admission control based on available file descriptors.

The client (hey) complained with “unsolicited response” warnings — a known artifact when clients aggressively reuse keep-alive connections under churn. The server was behaving correctly.

Scaling out: 16 workers

With 16 worker processes, the same workload:

sustained ~1200 requests/sec at 2500 concurrency
p50 ≈ 2.00s
p99 ≈ 3.0s
all 200 responses, no rejects

Again, the math checks:

2500 concurrent / 2 seconds ≈ 1250 rps theoretical

Result: ~96% of theoretical max.

This validated that PAGI’s worker model increases capacity cleanly without breaking streaming semantics.

The real test: slow clients and backpressure

Throughput benchmarks are easy. Backpressure is not.

To test this, I used a stress app that streams tens of megabytes as fast as possible, then ran clients with artificial throttling.

Slow client test

curl --limit-rate 1M http://localhost:5000/stream/50

Observed:

~50MB transferred in ~49 seconds
download rate stayed near 1MB/s
server did not buffer the entire response
no memory blow-up

This is the critical signal.

If backpressure were broken, the server would buffer 50MB instantly and curl would “catch up” later. That did not happen.

High-throughput clients

Unthrottled clients on localhost achieved:

~75–80 MB/s per connection
linear scaling until loopback bandwidth became the limit

Again, no red flags.

Concurrency + large bodies

Using hey with 50 concurrent clients streaming 10–50MB bodies:

high aggregate throughput
wide latency distribution
no error rates
no collapse

At this point, the bottleneck was clearly:

kernel socket buffers
memory copy bandwidth
client tooling limits

Not the server itself.

The subtle risk we identified (and addressed)

While reviewing the server code, one important detail surfaced:

writes use IO::Async::Stream->write
writes enqueue data into an outgoing buffer
there is no implicit send-side backpressure unless implemented explicitly

This is fine for polite producers (like most apps), but dangerous if:

an app writes huge chunks rapidly
the client reads slowly

To address this, we added send-side backpressure:

track queued outgoing bytes
define high / low watermarks
pause $send->(...) futures when buffers exceed the high watermark
resume when the buffer drains

This change makes slow-client behavior safe by default.

What I did not see (important)

Across all tests, I did not observe:

unbounded RSS growth
runaway CPU
increasing latency under steady load
dropped connections without errors
event-loop starvation

Those are the usual failure modes of async servers. None appeared.

Final assessment

Based on these tests:

PAGI::Server handles streaming correctly
backpressure works (and is now explicit)
overload fails fast and cleanly
worker scaling behaves predictably
performance matches theoretical limits

There’s still more to do — especially long-duration soak tests and production-grade observability — but the fundamentals are solid.

Most importantly, the server behaves honestly. It doesn’t fake async by buffering everything and hoping for the best.

Perl PAGI Project Update

John Napiorkowski — Sun, 28 Dec 2025 17:14:55 +0000

What We Learned Shipping PAGI

PAGI (Perl Asynchronous Gateway Interface) is a new web specification and reference server for Perl, designed to bring first-class async/await support to web development. Think of it as Perl's answer to Python's ASGI - a modern foundation for WebSocket, Server-Sent Events, and HTTP applications using Future and Future::AsyncAwait syntax.

Since the first stable release on December 24th, we've shipped seven releases in four days. This pace wasn't planned - it emerged from squashing bugs reported by CPAN Testers, especially on important but less common platforms like FreeBSD, along with rapid iteration on the API. Here's what we learned along the way.

Sometimes the Right Code is No Code

One of the more interesting decisions we made was removing a feature: built-in sendfile support.

The initial implementation used IO::Async::FileStream with Sys::Sendfile to efficiently stream large files directly from disk to socket, bypassing userspace copying. It worked beautifully on Linux. Then we tested on FreeBSD.

The problem wasn't just FreeBSD - it was the interaction between sendfile and non-blocking sockets, edge cases with partial writes, and the complexity of handling all the ways different operating systems implement (or don't implement) zero-copy file transfers. We found ourselves writing increasingly elaborate platform-specific workarounds.

We stepped back and asked: what problem are we actually solving? In production, large file serving should go through a reverse proxy anyway. Nginx's X-Sendfile (or X-Accel-Redirect) and Apache's mod_xsendfile exist precisely for this use case. They're battle-tested, optimized, and someone else maintains them.

So we removed sendfile entirely and created PAGI::Middleware::XSendfile instead. Your PAGI application returns a special header, and your reverse proxy handles the actual file transfer. The Unix philosophy wins again: do one thing well, and compose with specialized tools.

That said, this isn't ideological. If someone wants to contribute a robust, cross-platform sendfile implementation, we'd welcome the PR. The current solution is pragmatic, not dogmatic.

Async Error Handling Done Right

Asynchronous programming has a dirty secret: errors love to disappear.

In synchronous code, an exception bubbles up naturally. In async code with fire-and-forget Futures, exceptions can vanish into the void. Your background task fails, nobody notices, and you spend hours wondering why something silently stopped working.

PAGI originally used a pattern called retain() to keep Futures alive:

$self->retain($self->some_async_operation());

This worked for keeping the Future from being garbage collected, but it had a problem: if some_async_operation() failed, the error was quietly swallowed. The Future failed, nobody was listening, and life went on - except for the bug you didn't know about.

We replaced this with adopt_future():

$self->adopt_future($self->some_async_operation());

The difference is crucial. When an adopted Future fails, the error propagates to the parent context and gets logged. You see it. You can debug it. The failure is observable.

This applies throughout PAGI's internals - connection handling, protocol parsing, worker lifecycle management. Errors that previously might have disappeared now surface properly. It's a small API change that dramatically improves debuggability.

For application developers, the pattern extends to your own code. When you spawn background work in a request handler, adopt it rather than retaining it. Your future self debugging a production issue will thank you.

Making PAGI Feel Like Perl

One principle guided several of our developer experience decisions: PAGI should feel like Perl, not like a foreign framework that happens to run on Perl.

The clearest example is the new -e and -M flags for pagi-server:

# Inline app, just like perl -e
pagi-server -e 'sub { my ($scope, $receive, $send) = @_; ... }'

# Load modules first, like perl -M
pagi-server -MPAGI::App::File -e 'PAGI::App::File->new(root => ".")->to_app'

If you've used perl -e for quick scripts, this syntax is immediately familiar. No ceremony, no boilerplate files for simple cases.

This philosophy extends to other areas:

Test::Client now traps exceptions by default, matching how Perl developers expect test failures to behave. Multi-value headers, query parameters, and form fields work naturally.

Environment modes follow the pattern established by Plack: -E development enables debugging middleware, -E production optimizes for performance. The detection is automatic based on TTY.

Signal handling follows Unix conventions. SIGTERM and SIGINT trigger graceful shutdown. SIGHUP reloads workers. SIGTTIN/SIGTTOU adjust worker counts. It behaves like the system tools Perl developers already know.

The goal is reducing cognitive overhead. You shouldn't need to learn "the PAGI way" for things Perl and Unix already have conventions for.

What's Next

PAGI is stabilizing, but there's plenty of interesting work ahead.

Documentation has been a major focus. We split the original Tutorial into two documents: a Tutorial for getting started with core concepts, and a Cookbook for advanced patterns like background tasks, database connection pooling, JWT authentication, and Redis-backed sessions. The goal is progressive disclosure - you shouldn't need to read about WebSocket heartbeat strategies before you've served your first HTTP response.

The middleware collection continues to grow. We have 37 middleware components now (authentication, rate limiting, CORS, sessions, and more), but there's always room for more.

We're considering a repository split and would love community feedback. Currently PAGI ships everything in one distribution: core spec, reference server, 37 middleware components, 19 apps, and test utilities. This is convenient (cpanm PAGI gets you everything) but means installing the full stack even if you only need parts.

Options we're weighing:

Keep unified (current) - simpler while the spec is still evolving
Split server - separate PAGI::Server as "reference implementation," enabling alternative servers
Three-way split - core spec, server, and contrib (middleware/apps) as separate distributions

What would serve you better? Lighter installs? Easier contribution workflow? Alternative server implementations? We'd appreciate hearing your use case.

Most importantly, we're looking for contributors. The codebase is approachable - modern Perl with async/await, comprehensive tests, and documented internals. Whether you want to tackle something meaty like cross-platform sendfile, or something focused like a new middleware component, there's room for your ideas.

Get Involved

GitHub: github.com/jjn1056/pagi
CPAN: PAGI on MetaCPAN
CONTRIBUTING.md: Guidelines for contributors, including our approach to AI-assisted development
SECURITY.md: How to report vulnerabilities

PAGI is licensed under the Artistic License 2.0. It's a volunteer project - no timeline commitments, but serious about quality. If your organization needs priority support or custom development, contract work is available.

Async Perl web development is here. Let's build it together.

PAGI::Server Performance and Hardening

John Napiorkowski — Mon, 15 Dec 2025 16:52:22 +0000

Some raw info on how PAGI::Server, the reference implementation of the PAGI spec (https://github.com/jjn1056/pagi) is coming along performance wise. Here's some high concurrency testing on a basic 'Hello world' app: https://github.com/jjn1056/pagi/blob/main/examples/01-hello-http/app.pl

This testing is running off my MacBook Pro, Intel era (2.4 GHz 8-Core Intel Core i9) which is not particularly known for being a great server. Running as:

 LIBEV_FLAGS=8 ./bin/pagi-server --workers 16 --quiet --no-access-log --loop EV  ./examples/01-hello-http/app.pl

Results:

% hey -z 30s -c 500 http://localhost:5000/

Summary:
  Total:    30.0217 secs
  Slowest:  0.1110 secs
  Fastest:  0.0097 secs
  Average:  0.0312 secs
  Requests/sec: 16010.2544


Response time histogram:
  0.010 [1] |
  0.020 [376]   |
  0.030 [222649]    |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.040 [226482]    |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.050 [26058] |■■■■■
  0.060 [4279]  |■
  0.070 [492]   |
  0.081 [123]   |
  0.091 [173]   |
  0.101 [20]    |
  0.111 [2] |


Latency distribution:
  10% in 0.0249 secs
  25% in 0.0273 secs
  50% in 0.0304 secs
  75% in 0.0340 secs
  90% in 0.0381 secs
  95% in 0.0414 secs
  99% in 0.0505 secs

Details (average, fastest, slowest):
  DNS+dialup:   0.0000 secs, 0.0097 secs, 0.1110 secs
  DNS-lookup:   0.0000 secs, 0.0000 secs, 0.0193 secs
  req write:    0.0000 secs, 0.0000 secs, 0.0091 secs
  resp wait:    0.0311 secs, 0.0096 secs, 0.1110 secs
  resp read:    0.0000 secs, 0.0000 secs, 0.0035 secs

Status code distribution:
  [200] 480655 responses

This beats a similar PSGI hello world running under Starman by 30%, but the important bit to note is that PAGI::Server successfully responded to all requests, whereas Starman fell over by 80% at this load on my machine. That's why you need to run Starman behind an edge server like Nginx; it just can't take the high concurrency.

I've also been doing http/websockets compliance and security testing on PAGI::Server, working draft is here:

https://github.com/jjn1056/pagi/blob/main/lib/PAGI/Server/Compliance.pod

volunteers who know a lot about flogging servers very welcomed to help me test this. In production you are still likely to run behind a proxy or edge server like Ngnix but the more robust it is stand alone the better.

In Defense of Rudolph (and Against State-Sanctioned Reindeer Bullying)

John Napiorkowski — Sun, 14 Dec 2025 13:28:34 +0000

Every year around Christmas, we are expected—required, really—to cheerfully sing along to Rudolph the Red-Nosed Reindeer, a song that is widely regarded as wholesome, heartwarming, and suitable for children. It’s so culturally entrenched that it didn’t just become a hit song—it spawned a beloved stop-motion movie that gets replayed annually as a kind of unquestioned holiday ritual.

This is a lie.

If you actually listen to the lyrics, or worse, watch the movie, Rudolph is not a story about inclusion or kindness. It is a story about state-sanctioned bullying, conditional acceptance, and the moral philosophy that you are only worthy of dignity if you are useful to power.

Let’s review the facts.

Rudolph is born with a mutation. Not a choice. Not a moral failing. A physical difference he did nothing to earn. His nose glows. That’s it. That’s the crime.

The response?

“All of the other reindeer

Used to laugh and call him names

They never let poor Rudolph

Join in any reindeer games”

This is not subtle. This is open, communal bullying. Not just teasing—systemic exclusion. There is no adult intervention. No North Pole HR department. No reindeer anti-harassment training. Everyone sees this happening and shrugs.

Including Santa.

And this matters, because Santa is not a kindly grandpa in this universe. He is a dictator-for-life, controlling labor, housing, and social standing at the North Pole. He runs a command economy powered by elf labor and reindeer logistics. He absolutely has the authority to shut this down.

He does not.

Instead, the message is clear: conform or suffer.

Rudolph is ostracized, isolated, and taught that his difference is shameful. The song doesn’t even pretend otherwise. It treats this as normal. Character-building, even.

But then—miraculously—a crisis occurs.

Fog.

The supply chain is threatened.

Christmas itself (read: the regime’s legitimacy) is at risk.

And suddenly—suddenly—Rudolph’s mutation is no longer disgusting. It’s strategic.

“Then one foggy Christmas Eve

Santa came to say…”

Note the phrasing. Santa came to say. Not to apologize. Not to reflect. Not to acknowledge years of cruelty. He simply rebrands Rudolph’s condition as an asset now that it is useful.

Rudolph is allowed to participate—not because he deserves dignity as a being, but because his abnormality can be leveraged to achieve state objectives.

This is not redemption. This is instrumentalization.

And yes, Rudolph gets applause at the end. The same reindeer who mocked him now “love him.” But only after he proves his value.

It teaches children that:

Bullying is fine until the bullied person turns out to be valuable.
Authority figures don’t owe you protection—only results.
Difference is tolerated only when it serves power.

Rudolph didn’t change. The world didn’t become kinder. The regime just found a way to exploit what it once despised.

You don’t get acceptance for being different.

You get acceptance for being useful.

If you’re a programmer, this story might feel… familiar.

A lot of us grew up as the weird kids. Too intense. Too quiet. Too literal. Too obsessed with systems, patterns, or ideas no one else cared about. We missed social cues. We asked annoying questions. We didn’t “join in the reindeer games.”

We were tolerated at best. Mocked at worst.

And then, one day, the fog rolled in.

Suddenly the same traits—hyperfocus, pattern recognition, obsession with correctness, discomfort with ambiguity—were no longer liabilities. They were marketable. Billable. Recruitable.

The message didn’t change. The context did.

You weren’t accepted because the world became kinder. You were accepted because your difference could now be leveraged by companies, platforms, and institutions that once would have happily ignored you.

That’s not inclusion. That’s conditional mercy.

This isn’t to say success is bad, or that being valued for your skills is wrong. It’s to say that it’s worth noticing how often dignity arrives after usefulness—and how rarely it arrives on its own.

So no, I don’t sing along anymore.

Because if Rudolph the Red-Nosed Reindeer is a Christmas story, it’s not about goodwill toward all.

It’s about how acceptance works in practice.

And a lot of us deserved better—long before the fog rolled in.

Author’s note: This piece was written collaboratively with an AI. I brought the ideas; it helped me shape them — a process I call vibe thinking.

The Joy of Code in the Age of Vibe Engineering

John Napiorkowski — Sat, 13 Dec 2025 01:44:23 +0000

I’ve always liked programming because I could get the machine to bend to my will.

Programming has a puzzle-like pleasure to it. Breaking a messy problem down into smaller and smaller pieces. Staring at a system long enough that the shape of the bug finally reveals itself. Digging through hundreds or thousands of files and finding the one thing that’s off. When it works, it gives me a real sense of accomplishment — the same kind some people get from crosswords or jigsaw puzzles.

A lot of that joy also came from how I learned to program. I’m entirely self-taught; I never took a programming class in college that I didn’t fail. That doesn’t make me better than anyone else, but it did shape how I think. Learning outside a traditional path forced me to read a lot of other people’s code, to reverse-engineer decisions, and to develop a certain stubborn self-reliance. I think that background gave me edges and perspectives I might not otherwise have had.

Open source software was central to that journey. It’s how I learned, and contributing back has always mattered to me — not as virtue signaling or résumé building, but as reciprocity. I’ve benefited enormously from OSS over the years, and giving something back still matters more to me than credit ever has. Of all the things I’ve done professionally, that’s what I’m most proud of.

For a long time I half-jokingly called myself a bare-knuckles programmer. I’d slog through things out of bloody stubbornness. If I wrote it, I had written every line of it. There was no code in my projects that exceeded my own ability, even if some of it took far longer than it should have when I needed to stretch and expand my ability.

That relationship to code is changing.

From vibe coding to vibe engineering

I don’t love the term vibe coding, because it suggests you just tell an AI what you want and it spits something out. That’s not what my experience has been like at all.

What I’m doing feels more like vibe engineering.

It’s real work. It’s planning, constraint-setting, and taste. It’s knowing how to ask the right questions, how to push back, and how to recognize when something smells wrong. A lot of the effort goes into building a plan collaboratively, then interrogating the output:

Why did you do it this way? What does this code actually mean? What assumptions are hiding here?

The work hasn’t disappeared — it’s moved up a level.

PAGI and the hollow aftertaste

That shift really hit me during my work on PAGI

(https://github.com/jjn1056/pagi).

PAGI wasn’t something I casually prompted into existence. I spent well over a year thinking about it: personal research, research with AI, reading and re-reading existing codebases, staring at designs, backing out of approaches that didn’t feel right, and slowly converging on something I believed was worth building. By the time I started writing serious code, I’d already invested a lot of myself into the problem.

When I did build it, I vibe-engineered essentially the entire project, including some genuinely complex areas around async code and web servers — topics I’m still not an expert in.

On one level, it was intoxicating. I produced something I’d been thinking about for a long time. I worked in a domain I’d historically avoided. The system works. It’s real and I think it's going to be a valuable addition to the Perl OSS ecosystem.

And yet the sense of achievement felt just a little hollow.

Not because it felt dishonest or unearned. More because my relationship to the code was different. Some of the code in PAGI is code I could not have written from scratch at the time I wrote it. I understand it now — deeply, in fact, because part of the vibe-engineering process for me is reviewing everything and asking detailed, sometimes annoying questions — but it still feels different than having typed every line myself.

In the past, there was never any code in my projects that was something I “couldn’t have done.” With PAGI, that line was crossed.

Authorship, credit, and open source discomfort

That crossing raises uncomfortable questions, especially in open source.

Is this really my work? How should I respond to praise for the work? Is AI a tool here, a collaborator, or something closer to ghostwriting?

What makes this tricky is that I genuinely don’t care much about credit. What I care about is contributing something useful back to a community I’ve benefited from enormously. Still, even if the ethics feel sound, there’s an internal discomfort that’s hard to ignore. Praise for cleverness or design lands oddly when you know how much of the implementation was dialogued into existence rather than hand-forged.

I don’t have clean answers here, and I’m not sure I want to pretend that I do.

Mastery, necessity, and selective depth

Part of what complicates all this is realizing that I don’t actually need to master everything anymore.

I don’t have a professional need to be an expert in building secure, performant web servers. That’s never been a core job requirement, and it’s unlikely to become one. In that sense, this isn’t fundamentally different from how I use SQL while knowing relatively little about database internals. And a big part of the reason to write PAGI is to hide a lot of the complexities of asynchronous web programming behind a higher level abstraction so that less knowledgable programmers can actually use it without having to spend a lot of time mastering low level asynchronous primitives.

And yet, there’s still a part of me that wonders whether I would have been happier mastering those topics the old way — line by line, mistake by mistake.

That tension is real. Some of it is about craft. Some of it is about identity. And some of it is about timing. I’m in the final stage of my professional career; I’ll likely be letting go of this work sometime in the next ten years or less. In counterpoint I haven’t been this excited about programming since the late 90s — and that excitement sits right next to a quiet grief for what’s changing.

When vibe engineering feels like mercy

What convinced me this isn’t a simple “AI good / AI bad” story was a very different experience.

At work, I had to translate several thousand lines of dense, tech-debt-laden Perl into our newer Go-based system. It was unpleasant work — the kind of job I like the least. Lots of dead zones, historical baggage, and brittle logic.

Vibe engineering that task didn’t produce any existential angst at all. It produced relief.

The cost of getting it wrong was lower. The emotional burden was lighter. I didn’t feel like I’d lost anything meaningful by not hand-crafting every line. That contrast made something clear: the discomfort isn’t about AI — it’s about where I derive meaning.

Thinking out loud without the paralysis

There’s another gain here that I didn’t fully appreciate at first.

Like a lot of programmers, I can get stuck in decision paralysis, especially around architecture; a mild form of OCD I imagine. I’ll spin on tradeoffs, worried about choosing the “wrong” direction. In the past, the cost of being wrong felt high — not just technically, but personally, because it meant committing a lot of my own effort.

Dialoguing with AI has helped break that cycle.

Talking things out — even with something that isn’t human — helps me externalize the problem. I can explore options, stress-test ideas, and move forward with less anxiety. Because the personal cost of a wrong turn is lower, I don’t freeze as often. I make decisions knowing I can revise them without paying the same psychological toll.

That’s a different kind of joy — quieter than pride, but real.

Where joy lives now

I don’t know what a “great programmer” is anymore. I’m still proudest of my open source work. What feels most unquestionably mine now isn’t every line of code, but the problems I choose, the slant I put on solutions, and the insistence on doing the smallest fix that isn’t dumb and aiming for simple, understandable code and interfaces — something I’ve told more than a few coworkers over the years.

The joy hasn’t disappeared. But it’s changed shape.

It’s less solitary. Less about proving I can do everything myself. More about judgment, framing, and knowing when something is wrong even if I didn’t write it first.

So when I ask whether there’s still joy in coding in the age of vibe engineering, I don’t mean it rhetorically. I mean it honestly.

I think the joy survives — but it asks us to let go of some old certainties about authorship, mastery, and what it means for the machine to bend to our will.

And I’m still learning how to live with that.

Author’s note: This piece was written collaboratively with an AI. I did the thinking; it helped me talk it through; what I'm calling 'vibe thinking'.

PAGI: ASGI For Perl, or the Spiritual Successor to Plack

John Napiorkowski — Tue, 02 Dec 2025 20:13:34 +0000

Introducing PAGI: Async Web Development for Perl

TL;DR: PAGI (Perl Asynchronous Gateway Interface) is a new specification for async Perl web applications, inspired by Python's ASGI. It supports HTTP, WebSockets, and Server-Sent Events natively, and can wrap existing PSGI applications for backward compatibility.

The Problem

Modern web applications need more than traditional request-response cycles. Real-time features like live notifications, collaborative editing, and streaming data require persistent connections. This means:

WebSockets for bidirectional communication
Server-Sent Events for efficient server push
Streaming responses for large payloads
Connection lifecycle management for resource pooling

PSGI, Perl's venerable web server interface, assumes a synchronous world. While frameworks like Mojolicious have built async capabilities on top, there's no shared standard that allows different async frameworks and servers to interoperate.

PAGI aims to fill that gap.

What is PAGI?

PAGI defines a standard interface between async-capable Perl web servers and applications. If you're familiar with Python's ecosystem, think of it as Perl's answer to ASGI.

A PAGI application is an async coderef with three parameters:

use Future::AsyncAwait;
use experimental 'signatures';

async sub app ($scope, $receive, $send) {
    # $scope   - connection metadata (type, headers, path, etc.)
    # $receive - async coderef to get events from the client
    # $send    - async coderef to send events to the client
}

The $scope->{type} tells you what kind of connection you're handling:

Type	Description
`http`	Standard HTTP request/response
`websocket`	Persistent WebSocket connection
`sse`	Server-Sent Events stream
`lifespan`	Application startup/shutdown lifecycle

A Simple HTTP Example

Here's "Hello World" in raw PAGI:

use Future::AsyncAwait;

async sub app ($scope, $receive, $send) {
    die "Unsupported: $scope->{type}" if $scope->{type} ne 'http';

    await $send->({
        type    => 'http.response.start',
        status  => 200,
        headers => [['content-type', 'text/plain']],
    });

    await $send->({
        type => 'http.response.body',
        body => 'Hello from PAGI!',
        more => 0,
    });
}

Run it:

pagi-server --app app.pl --port 5000
curl http://localhost:5000/
# => Hello from PAGI!

The response is split into http.response.start (headers) and http.response.body (content). This separation enables streaming—send multiple body chunks with more => 1 before the final more => 0.

WebSocket Support

WebSockets are first-class citizens in PAGI:

async sub app ($scope, $receive, $send) {
    if ($scope->{type} eq 'websocket') {
        await $send->({ type => 'websocket.accept' });

        while (1) {
            my $event = await $receive->();

            if ($event->{type} eq 'websocket.receive') {
                my $msg = $event->{text} // $event->{bytes};
                await $send->({
                    type => 'websocket.send',
                    text => "Echo: $msg",
                });
            }
            elsif ($event->{type} eq 'websocket.disconnect') {
                last;
            }
        }
    }
    else {
        die "Unsupported: $scope->{type}";
    }
}

The event loop pattern is consistent across all connection types: await events from $receive, send responses via $send.

PSGI Compatibility

One of PAGI's key features is backward compatibility with PSGI. The PAGI::App::WrapPSGI adapter lets you run existing PSGI applications on a PAGI server:

use PAGI::App::WrapPSGI;

# Your existing Catalyst/Dancer/Plack app
my $psgi_app = MyApp->psgi_app;

my $wrapper = PAGI::App::WrapPSGI->new(psgi_app => $psgi_app);
$wrapper->to_app;

The wrapper handles all the translation: building %env from PAGI scope, collecting request bodies, and converting responses back to PAGI events.

This means you can:

Run legacy applications on a PAGI server
Add WebSocket endpoints alongside existing routes
Migrate incrementally from PSGI to PAGI
Share connection pools between old and new code

PAGI::Simple Micro-Framework

For rapid development, PAGI ships with a micro-framework inspired by Express.js:

use PAGI::Simple;

my $app = PAGI::Simple->new(name => 'My API');

$app->get('/' => sub ($c) {
    $c->text('Hello, World!');
});

$app->get('/users/:id' => sub ($c) {
    my $id = $c->path_params->{id};
    $c->json({ user_id => $id });
});

$app->post('/api/data' => sub ($c) {
    my $data = $c->json_body;
    $c->json({ received => $data, status => 'ok' });
});

$app->to_app;

WebSockets are equally clean:

$app->websocket('/chat' => sub ($ws) {
    $ws->on(message => sub ($data) {
        $ws->broadcast("Someone said: $data");
    });
});

PAGI::Simple includes:

Express-style routing with path parameters
JSON request/response helpers
Session management
Middleware support (CORS, logging, rate limiting, etc.)
Static file serving
WebSocket rooms and broadcasting
SSE channels with pub/sub

Current Status

PAGI is currently in early beta. The test suite passes, the examples work, but it hasn't been battle-tested in production.

What exists today:

Complete PAGI specification
Reference server implementation (PAGI::Server)
PAGI::Simple micro-framework
13 example applications
PSGI compatibility layer
483 passing tests

What it needs:

Developers willing to experiment and provide feedback
Real-world testing
Framework authors interested in building on PAGI
Performance profiling and optimization

Getting Started

git clone https://github.com/jjn1056/pagi.git
cd pagi
cpanm --installdeps .
prove -l t/

# Try the examples
pagi-server --app examples/01-hello-http/app.pl --port 5000
pagi-server --app examples/simple-01-hello/app.pl --port 5000

Why This Matters

Perl has excellent async primitives (IO::Async, Future::AsyncAwait), but no shared specification for async web applications. Each framework implements its own approach, which limits interoperability.

PAGI provides that shared foundation. By standardizing on a common interface:

Servers can focus on performance and protocol handling
Frameworks can focus on developer experience
Middleware becomes portable across implementations
The ecosystem can grow together rather than in isolation

If you're interested in the future of async Perl web development, I'd love your feedback. Check out the repository, try the examples, and let me know what you think.

Repository: github.com/jjn1056/pagi

PAGI is not yet on CPAN. It's experimental software—please don't use it in production unless you really know what you're doing.

DEV Community: John Napiorkowski

Perl PAGI Middleware

Middleware in PAGI

The PAGI middleware contract

Logger middleware

Authenticator middleware

ProfileRouter middleware

Assembling the app

Running it

How it lines up with the original

PAGI Distribution Split

Install what you actually run

What's notable in each

Status, and a note

Perl PAGI Project Updates

PAGI::Server, now with HTTP/2!

The Quick Version

"I Have nginx in Front, Why Do I Care?"

Where h2c Matters

A Note on Proxies

HTTP/2 Over TLS -- No Proxy Required

What PAGI::Server Does

Dual-Mode Protocol Detection

WebSocket over HTTP/2 (RFC 8441)

Compliance

Multi-Worker and Tunable

Context in the Perl Ecosystem

What Else Is in 0.001017

Getting Started

Links

PAGI 0.001016: Navigating the Future::IO Configuration Problem

What is Future::IO?

The Problem

What Doesn't Work

The Tradeoffs We Considered

Option 1: Apps Configure Future::IO

Option 2: Extend the PAGI Spec

Option 3: Entry Point Configures

What We Chose

Why This Felt Right (Eventually)

Also in This Release: SSE Query Parameters

This Is Experimental - RFC Welcome

The #1 sentence I add to prompts that makes them better

Prompt Engineering or selling your soul?

Why it works (and why it’s “vibe engineering”)

The kind of questions that save you

A realistic failure mode this prevents

When I don’t use it

Copy/paste template you can steal

PAGI::Server: Stress-Testing an Async Perl HTTP Server the Hard Way

Architecture in one paragraph

An important note: Although PAGI::Server is IO::Async based, that is an implementation detail, not a core requirement of the PAGI specification. That said I build PAGI::Server on IO::Async because it's mature, battle tested and fully featured.

Baseline: fast responses

Streaming test: 2-second responses, 500 concurrent clients

A gotcha: TTY logging will ruin your benchmark

Overload behavior: what happens at 2500 concurrent streams?

Scaling out: 16 workers

The real test: slow clients and backpressure

Slow client test

High-throughput clients

Concurrency + large bodies

The subtle risk we identified (and addressed)

What I did not see (important)

Final assessment

Perl PAGI Project Update

What We Learned Shipping PAGI

Sometimes the Right Code is No Code

Async Error Handling Done Right

Making PAGI Feel Like Perl

What's Next

Get Involved

PAGI::Server Performance and Hardening

In Defense of Rudolph (and Against State-Sanctioned Reindeer Bullying)

The Joy of Code in the Age of Vibe Engineering

From vibe coding to vibe engineering

PAGI and the hollow aftertaste

Authorship, credit, and open source discomfort

Mastery, necessity, and selective depth

When vibe engineering feels like mercy

Thinking out loud without the paralysis