DEV Community: John Napiorkowski

CatalystNext: What Should We Keep, Change, and Rethink?

John Napiorkowski — Tue, 28 Jul 2026 15:51:19 +0000

Suppose we could redesign Catalyst without preserving every compatibility
decision it has accumulated. Which parts would we keep because they still
work? Which would we simplify? Which pain points have experienced Catalyst
developers learned to work around, but should not be inherited by a new
framework?

CatalystNext is the working name for that redesign. This is not a v1
proposal. I want to make the consequential choices visible while Catalyst
users can still challenge them: subroutine attributes or a DSL, chained
dispatch or another routing model, action and controller namespaces,
request-scoped state, services and MVC, and the boundary between a small core
and a complete framework.

PAGI, the Perl Asynchronous Gateway
Interface, would give CatalystNext an async-native execution foundation.
Supporting APIs, WebSockets, streams, MCP, and other current workloads
matters, but modernization is not the main question of this post. The main
question is whether the proposed programming model addresses Catalyst's real
strengths and pain points.

1. What should writing CatalystNext feel like?

Subroutine attributes, a route DSL, or conventions?

Catalyst is, for better or worse, a subroutine-attribute framework. An action
looks like a Perl subroutine with declarations attached to it. That keeps the
route metadata beside the code that handles the route, and it is an important
part of Catalyst's identity.

There are other credible choices.

A dedicated route DSL can show the whole application more clearly and avoid
some of Perl's attribute machinery. Rails demonstrates how much can follow
from a compact resource declaration:
resources :photos expands
into the conventional collection and member routes, named helpers, and
controller actions. At the other end, an explicit route table can make every
method, path, and handler visible without any convention.

FastAPI takes another
path: decorators remain close to the handler, while ordinary Python type
declarations also drive parsing, validation, serialization, and generated
OpenAPI documentation. The interesting part is not the Python syntax; it is
how much useful application metadata becomes available from one declaration.

My instinct is that CatalystNext should remain attribute-driven at its main
user-facing surface. I am not in love with inventing a large new DSL, and I
do not want a supposedly convenient route convention to conceal most of the
application.

Questions I would value feedback on:

Are subroutine attributes still a pleasant and idiomatic way to describe actions in modern Perl?
Is having route information beside the handler more valuable than seeing the complete route tree in one file?
Which declarations should remain explicit even if a Rails-like resource shortcut is available?
Would it be useful for attributes, a DSL, and conventions to be alternative front ends over the same underlying application model, or would that merely recreate Catalyst's “too many ways” problem?

The declaration surface does not settle what those declarations build. That
leads to the dispatch model itself.

What kind of dispatcher?

I am strongly inclined to keep chained dispatch. Chains remain a good way to
express the structure that real applications repeat:

identify tenant
  → authorize user
    → load project
      → load issue
        → perform endpoint

The problem is that Catalyst's historical chained syntax accumulated several
ways to say similar things. Controller namespaces, action namespaces, path
parts, captures, and private action names could all interact. People often
found chaining powerful only after they had survived learning how its pieces
were bolted together.

We are not bound by that compatibility surface in a new framework. The goal
would be to retain chains while separating three things that old Catalyst
often allowed to blur together:

Code origin — the package and subroutine containing the code.
Logical action name — the stable name used for chaining, diagnostics, and reverse lookup.
URL path — the path used for HTTP dispatch.

Here is one deliberately incomplete syntax experiment:

package MyApp::Controller::AddressBook;

# URL: /contacts
sub contacts :Via('/') :At('contacts') {
    # Work shared by the collection.
}

# URL: /contacts/{contact_id}
sub contact :Via('../contacts') :At('{contact_id:\d+}') {
    # Work shared by one contact.
}

# Matches: GET /contacts
sub list :Via('../contacts') :Get('') {
}

# Matches: GET /contacts/{contact_id}
sub show :Via('../contact') :Get('') {
}

In this experiment, Via refers to a logical action and At contributes a
URL fragment. Get($path) is simply At($path) plus the HTTP GET method.
The same rule would apply to Post, Patch, and the other HTTP verbs.

The logical name of show is /contacts/contact/show. Its URL is
/contacts/{contact_id}. Its Perl package is
MyApp::Controller::AddressBook. Those names are related only because the
author chose them to be readable.

This is a strawman, not a finished grammar. In particular, relative action
references such as Via('../contact') need to remain understandable when an
application has several actions named contact. Ambiguity should be a boot
error, not a load-order rule.

Rails-style resource dispatch has an obvious advantage here: most developers
already know what index, show, create, update, and destroy mean.
Explicit route tables are also easier to explain than an action graph.
Chaining has to earn its additional conceptual machinery.

A second simplification may come from the execution model rather than the
route grammar. If the terminal action returns a response, each intermediate
action can be middleware around the rest of the chain: call the next action
and return its response, transform or replace that response, or return a
response immediately to short-circuit dispatch.

This would be CatalystNext middleware over the context and response values,
not raw PAGI middleware over event channels. It would give authorization,
resource loading, and response decoration one composable shape. The separate
question of whether action return values should acquire this meaning appears
below.

Questions:

Do chains still model something important that middleware, dependency injection, or nested routers do not?
Can a much smaller Via plus At vocabulary make chained dispatch approachable?
Does treating intermediate chain actions as response-value middleware make the chain easier to understand?
Should resourceful CRUD routes be a dispatcher of their own, a convenience that produces a chain, or not part of the core?
Should one application be allowed to combine dispatch strategies, or does a framework need one blessed model?

Even after choosing chains, the framework must decide where the names in those
chains come from.

Should controller namespaces mean anything?

My current leaning is that a controller exists for code organization only.
Its package should tell the loader and the programmer where the code lives;
it should not silently contribute a URL prefix or an action namespace.

This will feel strange to people coming from frameworks where
Admin::UsersController naturally implies an /admin/users area. It also
removes an entire category of accidental coupling: reorganizing a large file
into several controllers would not change routes, reverse-route names, or
authorization behavior.

The action's logical namespace would instead come from its place in the
chain. A route dump would always show code origin, logical action, and URL
together, so the separation is visible rather than magical.

Questions:

Is a purely organizational controller liberating, or does it discard a useful convention?
When code origin and route structure differ, is a good route-inspection command sufficient to keep the application comprehensible?
Should an application be able to opt into package-derived defaults, even if the framework's underlying model keeps the concepts separate?

The authoring model tells us how actions are named and reached. The next layer
is what enters, leaves, and flows between those actions.

2. What flows through the application?

Representations, content negotiation, and schemas

For a long time, content negotiation promised that one resource could produce
HTML, JSON, XML, or another representation based on the request. In practice,
many applications created an HTML site and a separately versioned JSON API.
JSON won a very large part of the API world, while server-rendered HTML has
continued to evolve rather than vanish.

Should one logical action still negotiate among representations? Or is
GET /contacts for HTML conceptually different from
GET /api/v1/contacts for JSON, even when both use the same underlying
service?

Schemas raise a related question. OpenAPI can document and generate clients
for HTTP APIs. MCP tool definitions use JSON Schema for inputs and can declare
schemas for structured outputs. A framework with a reliable model of action
inputs and results could potentially generate much of this rather than asking
the author to describe the same contract several times.

But “generate the schema” can mean several incompatible things:

infer a best-effort schema from Perl code;
require typed request and response declarations;
start with a schema and generate Perl-facing types;
treat schemas as optional metadata which extensions may consume.

Questions:

Is content negotiation still a useful default, or should representations be explicit actions?
How much type and schema information will Perl developers realistically maintain?
Should validation, serialization, OpenAPI, and MCP schemas share one type model?
At what point does schema-driven development stop feeling like Perl?

Schemas describe the public boundary of an action. Chained applications also
need a disciplined way to move values across their internal boundaries.

Request state, services, models, and views

Catalyst's stash was wonderfully flexible. That flexibility also made it easy
for action chains and views to communicate through undocumented hash keys.

I am considering a more structured replacement based on scoped attributes. A
controller could declare an attribute with request scope. Once a chain action
establishes its value, that value would be available to downstream
controllers and to a called view.

Conceptually:

has current_contact => (
    scope => 'request',
    isa   => Contact,
);

That could make the data flowing through a chain explicit and introspectable.
It immediately creates hard questions:

Is the value write-once, replaceable, or lazily built?
Is it visible only downstream or everywhere in the request?
Who performs async construction and cleanup?
Does a view receive it automatically?
Should a model or domain service ever see request-scoped state implicitly, or is that a layering violation?

There is a second naming problem here. “Model” has meant everything from a
database handle to a domain object to an external API client. “View” can mean
a template, serializer, response object, or negotiated representation.

Perhaps the framework should fundamentally understand services with
lifetimes—application, request, connection—and allow models and views to be
useful application-level categories layered on top. Or perhaps abandoning
strong MVC vocabulary would discard one of Catalyst's most helpful organizing
ideas.

I would particularly like examples from larger applications: where did
request-local state help, where did implicit availability cause trouble, and
which resources genuinely needed application, request, or connection scope?

These authoring and data-flow choices should address problems people have
actually encountered in Catalyst applications. They also cannot assume that
the applications we build today look exactly like the applications Catalyst
was originally designed to serve.

3. What else must the redesign support?

When Catalyst first appeared, the central use case was a database-backed,
server-rendered website: templates, forms, sessions, and HTML responses.
That remains important, but “web framework” now covers several workloads with
related but non-identical needs:

server-rendered HTML, forms, redirects, and sessions;
JSON APIs and webhooks;
bidirectional WebSockets and server-sent event streams;
large streaming request and response bodies;
MCP tools, resources, and prompts;
possibly work that outlives one HTTP request.

HTML did not disappear, but a new framework should not assume that every
request ends by selecting a template.

MCP makes the changed landscape especially visible. MCP's data layer is based
on JSON-RPC and exposes primitives such as tools, resources, and prompts.
Remote MCP commonly uses
Streamable HTTP,
but an MCP tool is not naturally an HTTP path. Its identity, input schema,
capabilities, progress notifications, and result types matter more than
inventing a REST-shaped URL for it.

Questions:

Are HTTP, WebSocket, SSE, and MCP several protocol front doors into one application, or separate framework layers sharing services?
Should MCP be a first-class CatalystNext concept or an add-on that consumes the same metadata as HTTP APIs?
What request or connection lifecycle is shared across these protocols?
Where should long-running work stop being a controller action and become a job or service?

These workloads do not need identical controller APIs, but they do need an
execution foundation capable of supporting all of them. That is where PAGI
enters the design.

4. PAGI as the foundation, not necessarily the user interface

PAGI applications receive a connection scope plus asynchronous receive and
send functions. This supports multiple incoming and outgoing events and
makes backpressure visible.

CatalystNext should take advantage of that foundation without forcing every
ordinary database lookup or HTML response to look like low-level protocol
code. “Async-native” needs to become a set of application-level guarantees:

synchronous handlers remain straightforward;
asynchronous handlers compose without blocking the server;
cancellation reaches database queries, streams, and child work where possible;
request and connection resources are reliably cleaned up;
streaming does not require bypassing the framework;
dropping to raw PAGI remains possible at a defined boundary.

The controversial part is how much of that contract belongs in CatalystNext
and how much belongs in PAGI-Tools, an event loop, or service implementations.

Should an action's return value mean something?

In Catalyst, an action's return value has no framework meaning. An action
changes the response attached to the context, and the dispatcher ignores
whatever the subroutine returns. The introductory documentation demonstrates
this by setting
$c->res->body
without returning a response.

That has confused people. Every Perl subroutine returns something, even
without an explicit return, yet return $something from a Catalyst action
has no effect on dispatch. The action's real result accumulates elsewhere on
the context.

There is a reasonable case for leaving this alone. A Catalyst action is a
stage in a request lifecycle, not necessarily a function which produces a
result. Several actions and a view can cooperate through the context, and an
accidental final expression cannot unexpectedly become the response.

But CatalystNext could make the terminal action's return value part of its
contract. It would have to return an object which isa PAGI::Response.
CatalystNext could supply a CatalystNext::Response subclass with framework
conveniences while accepting other PAGI response subclasses.

PAGI::Response is a detached
response value, so an action could be tested by inspecting its returned
status, headers, and body without a live connection. Response ownership,
redirects, errors, views, and chain short-circuits would all use the same
explicit value. The dispatcher could reject undef or an unrelated value
instead of guessing whether some other code completed the response.

The cost is a stricter and less forgiving endpoint contract. It may add
ceremony, fit awkwardly with views which build a response in several steps,
and turn Perl's harmless implicit return into a validation error.

Should CatalystNext give an action's return value framework meaning, or is
Catalyst's current behavior a useful consequence of its request lifecycle?

Even with a response-value contract for ordinary endpoints, some applications
will need direct ownership of the PAGI event channels. That is a separate
boundary.

How PAGI-shaped should an action be?

There is still a lower-level question underneath the response-value contract:
should ordinary actions see only the CatalystNext chain described above, or
should a terminal action be able to become a literal PAGI application and an
intermediate action become literal PAGI middleware?

PAGI::Nano provides a useful
precedent. A Nano application is an ordinary PAGI application, but most HTTP
handlers receive a friendly context and return a response value which Nano
sends as PAGI events. Middleware uses the PAGI-shaped
($scope, $receive, $send, $next) contract. A raw route can take ownership
of its response and reach the underlying channels when it needs them.

That gives Nano a “no silo, no cliff” property: application code does not pay
the raw protocol cost for an ordinary JSON response, but it never becomes
trapped above PAGI.

CatalystNext could take a similar approach with an explicit :Raw indicator
(the name is only a strawman). The routing attributes are omitted from this
example so we can focus on execution shape:

# An ordinary endpoint returns a CatalystNext::Response.
async sub show ($self, $c) {
    return $self->view(show => contact => $self->current_contact);
}

# A raw intermediate action might receive the full middleware contract.
async sub observe :Raw (
    $self, $scope, $receive, $send, $next
) {
    my $observed_send = async sub ($event) {
        $self->metrics->increment($event->{type});
        await $send->($event);
    };

    await $next->($scope, $receive, $observed_send);
}

# A raw endpoint owns its response and can emit any PAGI event.
async sub feed :Raw ($self, $c) {
    my $emit = $c->raw_send;
    await $emit->({ type => 'contacts.feed.start' });
    await $emit->({
        type       => 'contacts.updated',
        contact_id => 42,
    });
    await $emit->({ type => 'contacts.feed.end' });
}

Here :Raw changes execution ownership, not routing. On a terminal action it
means that the action must complete the response or protocol exchange. On an
intermediate action it could mean that the action receives the full
around-middleware contract. That second shape can run before and after the rest
of the chain, replace or wrap receive and send, short-circuit dispatch, and
observe errors. It operates at a lower level than ordinary response-value
middleware, which sees the CatalystNext context, next, and the response
returned by the rest of the chain without taking ownership of the event
channels.

Keeping the PAGI event channels reachable also creates an extension seam
which response values alone cannot provide. A handler might emit a semantic
custom event such as contacts.updated.

A surrounding middleware could observe that event for metrics or tracing,
reject it, enrich it, or translate it into SSE, NDJSON, or some future wire
protocol. The handler can speak in application events while the wrapper owns
the representation. PAGI::Nano already
demonstrates this pattern
with custom send events rendered into more than one wire format.
Whether multiple wire formats should share one logical action is the
content-negotiation question discussed above.

The risk is making every CatalystNext action reason in transport-level terms.
Raw receive and send are flexible, but they also expose event ordering,
response ownership, awaiting every send, and protocol-specific failure modes.
The framework is supposed to design those footguns out of ordinary application
code.

So the question may not be whether CatalystNext is built from PAGI apps and
middleware—it almost certainly will be—but where that fact becomes visible:

Should every endpoint and intermediate action directly implement a PAGI contract?
Should ordinary actions receive a CatalystNext context and compile into PAGI apps or middleware, with :Raw as the explicit ownership escape hatch?
Can :Raw sensibly mean terminal PAGI application on an endpoint and PAGI middleware on an intermediate action, or are those different concepts which deserve different indicators?
Should every ordinary intermediate chain action receive next and behave as response-value middleware, or should the framework also have simpler one-way setup stages?
Should custom event types be registered in the metamodel so extensions and tooling can discover them, or remain an intentionally open convention?

PAGI determines what CatalystNext can execute, but it does not determine the
right size of the framework or how much of Catalyst's existing shape a
redesign should preserve. Those are product decisions rather than protocol
decisions.

5. Where is the framework boundary?

How much compatibility should the name “Catalyst” imply?

I do not want to preserve awkward syntax solely because Catalyst had to remain
compatible with itself. A clean design needs permission to remove duplicate
spellings and historical namespace behavior.

At the same time, a framework called CatalystNext creates a reasonable
expectation that Catalyst developers can recognize its concepts and migrate
incrementally. PAGI can host existing PSGI applications through an adapter,
which creates possibilities for gradual migration at the application
boundary. It does not automatically provide source compatibility inside a
controller.

What matters most to potential users: familiar concepts, compatible
controller code, coexistence with an old application, migration tooling, or
simply a clear explanation of the break?

Even with permission to break old syntax, we still need to decide how much
belongs in the new core.

Small core or complete framework?

There is a perennial framework argument underneath all of this: should the
core be small and composable, or should a new application receive a coherent
answer for routing, configuration, services, validation, sessions,
authentication, rendering, errors, testing, and deployment?

A tiny core is easier to understand and less likely to freeze yesterday's
choices. It can also leave every application assembling a subtly incompatible
stack. A batteries-included framework creates shared vocabulary and better
out-of-the-box tooling, but every additional blessed subsystem raises the
cost of maintenance and makes alternative choices feel second-class.

My leaning is that CatalystNext should be small but complete and flexible.
That was one of Catalyst's strengths. It supplied enough shared structure for
an application to feel like one system, without insisting that every useful
idea had to live inside the core distribution.

“Complete” does not mean incorporating every fashionable application model.
It means defining a coherent application model, lifecycle, routing and
dispatch contract, service boundary, error path, and extension surface.
People should then be able to build more opinionated experiences on top:
Livewire- or LiveView-like stateful UI frameworks, API-focused stacks, MCP
tooling, or ideas none of us have named yet.

That still leaves a difficult boundary. Is schema generation a layer? Are
sessions? Are HTML views? Does authentication belong in the action model, in
middleware, or entirely in application code? How much must the core
standardize so independently developed extensions compose rather than merely
coexist?

I would like to hear which facilities must work together on day one for
CatalystNext to deserve the word “framework,” and which should remain
replaceable integrations.

Being both complete and extensible requires a shared structural vocabulary.
That is what keeps pulling me toward a metamodel rather than a collection of
unrelated hooks.

My current architectural leaning: build around a metamodel

The idea I keep returning to is a standalone application metamodel: something
structural and extensible, somewhat MOP-like in spirit but not based on Moose
and not limited to implementing CatalystNext.

It might contain concepts along these lines:

Meta::App
  Meta::Controller
    Meta::Action
  Meta::Dispatcher
  Meta::Service
  Meta::View
  Meta::Attribute

The exact class list is not the important part yet. The important separation
is between describing an application and turning that description into a
running PAGI app.

Subroutine attributes could build the model. A dedicated DSL or a
resource-routing convention could also build the model. Dispatchers could
compile actions into executable routing graphs. Extensions could inspect or
contribute metadata for OpenAPI, MCP, authorization, or developer tooling.
An application could fail at boot when routes collide or a chain consumes a
value nobody provides.

Spring WebFlux
is one useful precedent for separating these concerns: it supports both
annotated controllers and functional endpoint routing over the same reactive
web foundation. That does not mean CatalystNext should expose every possible
frontend. “They all compile to metadata” is an architectural capability, not
an excuse to avoid choosing one good default.

My hope is that the metamodel gives CatalystNext a sane, stable, introspectable
API for extension. Routes, actions, dispatchers, services, views, and scoped
attributes should be discoverable through documented objects rather than by
reverse-engineering controller packages or mutating framework internals.
Extensions should be able to contribute metadata, validate the application
model, and participate in compilation at defined points, while CatalystNext
still provides one opinionated default experience.

The metamodel also should not become a stealth decision about how application
objects are written. Ideally plain Perl, Moo, Moose, Object::Pad, and core
class code could participate through a structural contract. I am less sure
how far that neutrality can go before useful features become lowest-common-
denominator abstractions.

This is still only a direction. A metamodel can make routes inspectable and
extensions cleaner, but it can also become an abstract architecture project
that never produces a pleasant application framework. The user-facing
experience has to come first.

What feedback would help

I am not looking for a vote on whether every idea above is good. I would most
value reports from experience: what hurt, what scaled, and what you would not
want a redesign to lose.

Which Catalyst behavior proved valuable in a large application, even if its syntax was confusing?
Which Catalyst pain points have you learned to tolerate or work around?
Which routing model do you find easiest to understand six months after writing it?
Should an action's return value have framework meaning? If terminal actions return a PAGI::Response, does treating intermediate chain actions as middleware make chains clearer?
Where have framework conventions saved work, and where have they hidden too much?
How have you successfully handled request-scoped values and async resource lifetimes?
Would typed request and response declarations earn their cost through validation, OpenAPI, and MCP integration?
What kinds of Perl web applications are you building—or would you build if the framework support existed?
Where has direct access to an async protocol or custom event stream been useful, and where did it leak too much machinery into application code?
Which facilities must be integrated before a framework is meaningfully more useful than a router and middleware collection?
What would a Livewire- or LiveView-like layer need from the core in order to remain an extension rather than a fork?
Should CatalystNext impose an object system, favor one without requiring it, or remain completely structurally typed?
Does a reusable metamodel sound like a useful foundation, or like premature generalization?

Please feel free to answer one narrow part. A detailed objection to one
assumption is more useful at this stage than general encouragement.

I have spent enough time trying to imagine the perfect v1 in isolation. I
would rather find the shape of the problem with the community before turning
these experiments into promises.

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'.

DEV Community: John Napiorkowski

CatalystNext: What Should We Keep, Change, and Rethink?

1. What should writing CatalystNext feel like?

Subroutine attributes, a route DSL, or conventions?

What kind of dispatcher?

Should controller namespaces mean anything?

2. What flows through the application?

Representations, content negotiation, and schemas

Request state, services, models, and views

3. What else must the redesign support?

4. PAGI as the foundation, not necessarily the user interface

Should an action's return value mean something?

How PAGI-shaped should an action be?

5. Where is the framework boundary?

How much compatibility should the name “Catalyst” imply?

Small core or complete framework?

My current architectural leaning: build around a metamodel

What feedback would help

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)