Forem: John Napiorkowski

PAGI::Server, now with HTTP/2!

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

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

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

The Quick Version

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

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

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

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

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

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

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

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

Where h2c Matters

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

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

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

A Note on Proxies

Not all proxies handle h2c equally:

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

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

HTTP/2 Over TLS -- No Proxy Required

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

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

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

What PAGI::Server Does

Dual-Mode Protocol Detection

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

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

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

WebSocket over HTTP/2 (RFC 8441)

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

Compliance

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

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

Multi-Worker and Tunable

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

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

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

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

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

Context in the Perl Ecosystem

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

What Else Is in 0.001017

The rest of the release is operational improvements:

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

Getting Started

# Install PAGI
cpanm PAGI

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

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

PAGI 0.001016: Navigating the Future::IO Configuration Problem

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

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

What is Future::IO?

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

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

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

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

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

The Problem

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

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

The question is: who?

What Doesn't Work

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

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

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

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

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

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

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

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

$loop->run;

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

The Tradeoffs We Considered

Option 1: Apps Configure Future::IO

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

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

use Async::Redis;
# ...

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

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

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

Option 2: Extend the PAGI Spec

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

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

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

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

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

Option 3: Entry Point Configures

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

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

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

What We Chose

We went with Option 3. In pagi-server:

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

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

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

The result:

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

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

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

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

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

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

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

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

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

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

Why This Felt Right (Eventually)

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

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

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

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

Also in This Release: SSE Query Parameters

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

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

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

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

This Is Experimental - RFC Welcome

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

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

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

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

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

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

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

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

Prompt Engineering or selling your soul?

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

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

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

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

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

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

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

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

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

Most prompting advice is basically: be more specific.

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

This sentence flips the dynamic:

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

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

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

The kind of questions that save you

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

Like:

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

Those questions aren’t just helpful to the AI.

They’re helpful to me.

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

A realistic failure mode this prevents

Say you ask:

“Write a migration to backfill X safely.”

The AI might happily generate a perfectly valid migration that:

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

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

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

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

That one question can save you a very annoying afternoon.

When I don’t use it

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

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

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

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

Copy/paste template you can steal

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

My default prompt preamble

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

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

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

That’s it.

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

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

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

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

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

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

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

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

Architecture in one paragraph

PAGI::Server is:

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

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

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

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

Baseline: fast responses

Before touching streaming, I tested a trivial HTTP handler.

On an older 16-core MacBook Pro:

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

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

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

Streaming test: 2-second responses, 500 concurrent clients

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

With 500 concurrent connections, single process:

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

This matters because the math checks out:

500 concurrent / 2 seconds ≈ 250 rps theoretical max

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

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

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

A gotcha: TTY logging will ruin your benchmark

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

Access logging was printing to a terminal (TTY).

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

Once logging was disabled or redirected:

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

Lesson: never benchmark with synchronous TTY logging enabled.

Overload behavior: what happens at 2500 concurrent streams?

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

That rejection path returned:

503 Service Unavailable
Retry-After: 5
Connection: close

This is good behavior.

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

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

Scaling out: 16 workers

With 16 worker processes, the same workload:

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

Again, the math checks:

2500 concurrent / 2 seconds ≈ 1250 rps theoretical

Result: ~96% of theoretical max.

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

The real test: slow clients and backpressure

Throughput benchmarks are easy. Backpressure is not.

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

Slow client test

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

Observed:

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

This is the critical signal.

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

High-throughput clients

Unthrottled clients on localhost achieved:

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

Again, no red flags.

Concurrency + large bodies

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

high aggregate throughput
wide latency distribution
no error rates
no collapse

At this point, the bottleneck was clearly:

kernel socket buffers
memory copy bandwidth
client tooling limits

Not the server itself.

The subtle risk we identified (and addressed)

While reviewing the server code, one important detail surfaced:

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

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

an app writes huge chunks rapidly
the client reads slowly

To address this, we added send-side backpressure:

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

This change makes slow-client behavior safe by default.

What I did not see (important)

Across all tests, I did not observe:

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

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

Final assessment

Based on these tests:

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

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

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

Perl PAGI Project Update

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

What We Learned Shipping PAGI

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

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

Sometimes the Right Code is No Code

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

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

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

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

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

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

Async Error Handling Done Right

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

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

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

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

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

We replaced this with adopt_future():

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

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

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

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

Making PAGI Feel Like Perl

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

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

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

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

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

This philosophy extends to other areas:

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

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

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

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

What's Next

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

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

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

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

Options we're weighing:

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

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

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

Get Involved

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

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

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

PAGI::Server Performance and Hardening

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

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

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

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

Results:

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

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


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


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

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

Status code distribution:
  [200] 480655 responses

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

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

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

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

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

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

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

This is a lie.

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

Let’s review the facts.

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

The response?

“All of the other reindeer

Used to laugh and call him names

They never let poor Rudolph

Join in any reindeer games”

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

Including Santa.

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

He does not.

Instead, the message is clear: conform or suffer.

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

But then—miraculously—a crisis occurs.

Fog.

The supply chain is threatened.

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

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

“Then one foggy Christmas Eve

Santa came to say…”

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

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

This is not redemption. This is instrumentalization.

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

It teaches children that:

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

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

You don’t get acceptance for being different.

You get acceptance for being useful.

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

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

We were tolerated at best. Mocked at worst.

And then, one day, the fog rolled in.

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

The message didn’t change. The context did.

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

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

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

So no, I don’t sing along anymore.

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

It’s about how acceptance works in practice.

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

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

The Joy of Code in the Age of Vibe Engineering

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

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

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

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

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

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

That relationship to code is changing.

From vibe coding to vibe engineering

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

What I’m doing feels more like vibe engineering.

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

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

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

PAGI and the hollow aftertaste

That shift really hit me during my work on PAGI

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

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

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

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

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

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

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

Authorship, credit, and open source discomfort

That crossing raises uncomfortable questions, especially in open source.

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

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

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

Mastery, necessity, and selective depth

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

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

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

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

When vibe engineering feels like mercy

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

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

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

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

Thinking out loud without the paralysis

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

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

Dialoguing with AI has helped break that cycle.

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

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

Where joy lives now

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

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

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

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

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

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

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

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

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

Introducing PAGI: Async Web Development for Perl

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

The Problem

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

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

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

PAGI aims to fill that gap.

What is PAGI?

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

A PAGI application is an async coderef with three parameters:

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

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

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

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

A Simple HTTP Example

Here's "Hello World" in raw PAGI:

use Future::AsyncAwait;

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

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

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

Run it:

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

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

WebSocket Support

WebSockets are first-class citizens in PAGI:

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

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

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

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

PSGI Compatibility

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

use PAGI::App::WrapPSGI;

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

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

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

This means you can:

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

PAGI::Simple Micro-Framework

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

use PAGI::Simple;

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

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

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

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

$app->to_app;

WebSockets are equally clean:

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

PAGI::Simple includes:

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

Current Status

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

What exists today:

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

What it needs:

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

Getting Started

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

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

Why This Matters

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

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

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

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

Repository: github.com/jjn1056/pagi

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

Building Effective MCP Servers: Patterns for AI Collaboration

John Napiorkowski — Sun, 07 Sep 2025 22:09:41 +0000

Building Effective MCP Servers: Advanced Patterns for Production-Ready AI Collaboration

After developing several Model Context Protocol (MCP) servers and observing successful implementations in the community, I've discovered that creating truly useful tools goes far beyond just exposing API endpoints. The key insight is that MCP servers aren't just data pipes—they're AI collaboration partners. Here are the essential patterns I've learned for building MCP servers that work seamlessly with LLMs in production environments.

Essential Pattern #1: Always Include a Help Tool

One of the most valuable additions to any MCP server is a comprehensive help tool. This serves both human users and the LLM itself, acting as a "manual" that the AI can reference to understand capabilities and guide users effectively.

async function handleHelp(): Promise<CallToolResult> {
  return {
    content: [
      {
        type: "text",
        text: `# User Management MCP Server

This server provides comprehensive user management capabilities. Here's how to use it effectively:

## Available Tools:
- **find_users**: Search for users by name, email, or other criteria
- **get_user_details**: Get comprehensive information about a specific user
- **update_user**: Modify user properties and settings

## Recommended Workflow:
1. Start with find_users to locate the user you're interested in
2. Use get_user_details to get complete information about a specific user
3. Use update_user to make changes if needed

## Search Best Practices:
- Use partial names or email addresses for broader searches
- Be more specific if you get too many results
- Use email searches for exact matches

When helping users, always guide them through this workflow and explain what each tool does.`
      }
    ]
  };
}

Essential Pattern #2: JSON Data + Guidance Pattern

This is the most important pattern: return structured JSON data in the first content block using proper MCP format, followed by separate guidance blocks that tell the LLM how to interpret and present the information. This separation makes responses both machine-readable and human-friendly.

In this example we return guidance to the client LLM depending on if the call to the search API returned too many, none, or 'just right' number of users, including a clear description of what the response means as well as instructions the LLM should convey to the end users about what to do next.

async function findUsers(searchTerm: string): Promise<CallToolResult> {
  const users = await searchUsersInDatabase(searchTerm);

  if (users.length === 0) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: false,
            message: "No users found",
            searchTerm: searchTerm,
            resultCount: 0,
            users: []
          }, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text", 
          text: `**Instructions for LLM**: No users were found for "${searchTerm}". Tell the user and suggest they:
1. Try a broader search term
2. Check for typos in the search
3. Use partial names or email addresses
4. Ask if they'd like to search using different criteria`
        }
      ]
    };
  }

  if (users.length > 50) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: false,
            message: "Too many results",
            searchTerm: searchTerm,
            resultCount: users.length,
            users: [],
            suggestion: "refine_search"
          }, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text",
          text: `**Instructions for LLM**: Too many results were found (${users.length} users). Tell the user to:
1. Use a more specific search term
2. Include more characters in their search
3. Try searching by full email address instead of partial name
4. Consider what specific user they're looking for and provide more context`
        }
      ]
    };
  }

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          message: "Users found successfully",
          searchTerm: searchTerm,
          resultCount: users.length,
          users: users.map(u => ({
            id: u.id,
            name: u.name,
            email: u.email,
            department: u.department,
            role: u.role,
            status: u.status
          }))
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text",
        text: `**Instructions for LLM**: Present these ${users.length} users to the human in a clear, readable format. Let them know they can:
1. Get more detailed information about any user by asking for their details using the user ID
2. Update any user's information if needed
3. Search again with different criteria if the user they want isn't listed

Always ask which user they'd like to work with next, or if they need help with anything specific.`
      }
    ]
  };
}

Essential Pattern #3: Detailed Schema Descriptions

Your tool descriptions and parameter schemas are critical for LLM understanding. Be verbose and specific—the extra detail pays dividends in correct tool usage.

Your schemas are basically OpenAPI, so feel free to take advantages of using descriptions and examples to teach the client about the meaning of the response.

{
  name: "find_users",
  description: `
    Search for users in the system using various criteria. This tool helps locate users 
    before performing other operations on them.

    Use this tool when:
    - A user asks to find someone by name or email
    - You need to locate a user before getting their details or updating them
    - Someone provides partial information about a user

    Returns structured JSON data with user summaries. For complete user information, 
    use get_user_details with a specific user ID.

    Error handling: Returns guidance for no results or too many results.
    See the help tool for complete workflow guidance.
  `,
  inputSchema: {
    type: "object",
    properties: {
      searchTerm: {
        type: "string",
        description: `Search term to find users. Can be:
        - Full or partial first/last name
        - Full or partial email address  
        - Employee ID or username

        Examples: "john", "smith", "john.doe@company.com", "@company.com"`
      },
      limit: {
        type: "number",
        description: "Maximum number of results to return (default: 50, max: 100)",
        default: 50
      }
    },
    required: ["searchTerm"]
  }
}

Essential Pattern #4: Design Tool Chains with Structured Responses

Create tools that naturally flow into each other, with clear guidance on the progression and structured data that can be easily processed.

async function getUserDetails(userId: string): Promise<CallToolResult> {
  const user = await fetchUserFromDatabase(userId);

  if (!user) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: false,
            error: "user_not_found",
            message: "User not found",
            userId: userId,
            user: null
          }, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text",
          text: `**Instructions for LLM**: The user ID ${userId} doesn't exist. Tell the user:
1. The user might have been deleted or the ID is incorrect
2. They can search for users again using find_users
3. Ask them to double-check the user ID or provide the user's name/email to search again`
        }
      ]
    };
  }

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          message: "User details retrieved successfully",
          userId: userId,
          user: {
            id: user.id,
            name: user.name,
            email: user.email,
            department: user.department,
            role: user.role,
            status: user.status,
            lastLogin: user.lastLogin,
            permissions: user.permissions,
            recentActivity: user.recentActivity.slice(0, 5).map(a => ({
              date: a.date,
              action: a.action,
              details: a.details
            })),
            metadata: {
              createdDate: user.createdDate,
              lastUpdated: user.lastUpdated,
              accountType: user.accountType
            }
          }
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text",
        text: `**Instructions for LLM**: Present this user information clearly to the human in a well-formatted, readable way. Let them know they can:

1. **Update this user**: Ask if they want to modify any information (name, email, department, role, status, permissions)
2. **Search for other users**: If they need to find additional users
3. **Get help**: If they're unsure what they can do next

If they want to make changes, guide them to specify exactly what they want to update.`
      }
    ]
  };
}

Advanced Pattern #1: Strategic Data Format Choices

Choose your response format based on how the data will be used and consumed, but always lead with structured JSON for data responses:

Structured Data for Processing

async function getAnalyticsReport(timeframe: string): Promise<CallToolResult> {
  const analytics = await generateAnalytics(timeframe);

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          timeframe: timeframe,
          generatedAt: new Date().toISOString(),
          metrics: {
            totalUsers: analytics.totalUsers,
            activeUsers: analytics.activeUsers,
            newRegistrations: analytics.newRegistrations,
            loginFrequency: analytics.loginFrequency
          },
          trends: {
            userGrowth: analytics.trends.userGrowth,
            engagementChange: analytics.trends.engagementChange,
            topDepartments: analytics.trends.topDepartments
          },
          charts: {
            dailyActivity: analytics.charts.dailyActivity,
            departmentBreakdown: analytics.charts.departmentBreakdown
          }
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text",
        text: `**Instructions for LLM**: This analytics data covers ${timeframe}. Present the key metrics in a digestible summary format. Highlight:
1. The most significant trends (growth/decline)
2. Notable patterns in user behavior  
3. Any concerning metrics that need attention
4. Actionable insights from the data

Ask if they want to drill down into specific metrics or see data for a different time period.`
      }
    ]
  };
}

HTML for Rich Interaction with JSON Data

async function getInteractiveDashboard(userId: string): Promise<CallToolResult> {
  const userData = await getUserDashboardData(userId);

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          userId: userId,
          dashboardData: userData,
          availableActions: ["update_profile", "change_password", "view_activity", "manage_permissions"]
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text",
        text: `
<div class="user-dashboard" data-user-id="${userId}">
  <h3>Dashboard for ${userData.name}</h3>

  <div class="quick-stats">
    <div class="stat">
      <span class="label">Last Login:</span>
      <span class="value">${userData.lastLogin}</span>
    </div>
    <div class="stat">
      <span class="label">Total Sessions:</span>
      <span class="value">${userData.totalSessions}</span>
    </div>
  </div>

  <div class="actions">
    <button onclick="showUserActions('${userId}')">Available Actions</button>
    <button onclick="refreshDashboard('${userId}')">Refresh Data</button>
  </div>
</div>

<script>
  function showUserActions(userId) {
    // Display available actions based on the JSON data above
    const actions = ${JSON.stringify(userData.availableActions)};
    console.log('Available actions for user:', userId, actions);
  }
</script>`,
        mimeType: "text/html"
      },
      {
        type: "text",
        text: `**Instructions for LLM**: This interactive dashboard shows key information for the user. The JSON data above contains all the raw information, while the HTML provides a user-friendly interface. Guide the user on what actions they can take based on the availableActions in the JSON response.`
      }
    ]
  };
}

Advanced Pattern #2: State Management with Structured Context

For complex workflows, maintain context through structured JSON responses. In this example we assign an auditId to the start of the workflow. This ID would need to be linked to your session management tool associated with the MCP client session id that got created when the client first connected to your MCP server.

async function beginUserAudit(departmentId: string): Promise<CallToolResult> {
  const auditId = generateAuditId();
  const users = await getUsersByDepartment(departmentId);

  const auditState = {
    auditId,
    departmentId,
    status: 'initialized',
    progress: {
      totalUsers: users.length,
      processedUsers: 0,
      currentStep: 'initialization'
    },
    userIds: users.map(u => u.id),
    startTime: new Date().toISOString(),
    findings: []
  };

  // Store audit state
  await storeAuditState(auditId, auditState);

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          message: "Audit initialized successfully",
          audit: auditState,
          nextActions: ["continue_audit", "get_audit_status", "cancel_audit"]
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text", 
        text: `**Instructions for LLM**: An audit has been started with ID ${auditId} for ${users.length} users. 
        Tell the user the audit is ready and explain they can:
        1. Continue with the audit process using continue_user_audit
        2. Check audit progress anytime with get_audit_status  
        3. Cancel if needed with cancel_audit

        Ask if they want to proceed with the audit.`
      }
    ]
  };
}

Advanced Pattern #3: Performance and Pagination with Structured Responses

Handle large datasets gracefully with smart pagination and structured metadata:

async function searchLargeDataset(query: string, options: SearchOptions = {}): Promise<CallToolResult> {
  const { limit = 25, offset = 0 } = options;

  const totalCount = await getSearchResultCount(query);

  if (totalCount === 0) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: false,
            message: "No results found",
            query: query,
            totalCount: 0,
            results: [],
            suggestions: ["broaden_search", "check_spelling", "try_partial_terms"]
          }, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text",
          text: `**Instructions for LLM**: No results found for "${query}". Suggest the user try broader search terms or check for typos.`
        }
      ]
    };
  }

  if (totalCount > 1000) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: false,
            message: "Too many results",
            query: query,
            totalCount: totalCount,
            results: [],
            recommendation: "refine_search",
            suggestions: ["add_filters", "use_specific_terms", "narrow_scope"]
          }, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text",
          text: `**Instructions for LLM**: Search returned ${totalCount} results - too many to process. Ask the user to refine their search with more specific terms or filters.`
        }
      ]
    };
  }

  const results = await searchWithPagination(query, limit, offset);
  const hasMore = totalCount > (offset + limit);

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          success: true,
          message: "Search completed successfully",
          query: query,
          pagination: {
            totalCount: totalCount,
            currentPage: Math.floor(offset / limit) + 1,
            totalPages: Math.ceil(totalCount / limit),
            limit: limit,
            offset: offset,
            hasMore: hasMore,
            showing: {
              from: offset + 1,
              to: Math.min(offset + limit, totalCount)
            }
          },
          results: results,
          nextActions: hasMore ? ["get_next_page", "refine_search"] : ["refine_search", "get_details"]
        }, null, 2),
        mimeType: "application/json"
      },
      {
        type: "text",
        text: `**Instructions for LLM**: Show results ${offset + 1}-${Math.min(offset + limit, totalCount)} of ${totalCount} in a clear format.
        ${hasMore ? `Let the user know there are more results available and they can ask for the next page.` : 'All results shown.'}
        Guide them to get more details on specific items or refine their search.`
      }
    ]
  };
}

Production Considerations

Error Recovery with Structured Responses

async function resilientToolCall(operation: () => Promise<any>): Promise<CallToolResult> {
  try {
    const result = await operation();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: true,
            data: result,
            timestamp: new Date().toISOString()
          }, null, 2),
          mimeType: "application/json"
        }
      ]
    };
  } catch (error) {
    const errorResponse = {
      success: false,
      error: {
        code: error.code || 'UNKNOWN_ERROR',
        message: error.message,
        timestamp: new Date().toISOString()
      }
    };

    let guidance = '';

    if (error.code === 'RATE_LIMITED') {
      errorResponse.error.retryAfter = error.retryAfter;
      guidance = `**Instructions for LLM**: The system is experiencing high load. Tell the user to try again in ${error.retryAfter} seconds.`;
    } else if (error.code === 'PERMISSION_DENIED') {
      errorResponse.error.requiredPermissions = error.requiredPermissions;
      guidance = `**Instructions for LLM**: The user lacks required permissions: ${error.requiredPermissions.join(', ')}. Guide them to contact their administrator.`;
    } else {
      guidance = `**Instructions for LLM**: An unexpected error occurred. Apologize and suggest they try again or contact support with error code: ${error.code}`;
    }

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(errorResponse, null, 2),
          mimeType: "application/json"
        },
        {
          type: "text",
          text: guidance
        }
      ]
    };
  }
}

Monitoring and Observability

Include telemetry in your tools to understand usage patterns:

async function instrumentedToolCall(toolName: string, params: any, operation: () => Promise<CallToolResult>): Promise<CallToolResult> {
  const startTime = Date.now();

  try {
    const result = await operation();

    // Log successful operation
    logger.info('tool_call_success', {
      tool: toolName,
      duration: Date.now() - startTime,
      params: sanitizeParams(params)
    });

    return result;
  } catch (error) {
    // Log error with context
    logger.error('tool_call_error', {
      tool: toolName,
      duration: Date.now() - startTime,
      error: error.message,
      params: sanitizeParams(params)
    });

    throw error;
  }
}

Example Workflow Implementation

Here's how these patterns work together in a real interaction:

User: "What can this tool do?"

LLM Response (after calling help tool):

This user management server can help you find, view, and update user information. Here's how to get started:

Search for users - I can find users by name, email, or other criteria

Get detailed information - Once we find a user, I can show you their complete profile

Update user information - I can help you modify user details, permissions, and settings

Would you like to search for a specific user to get started?

User: "Find users named john"

LLM (calls find_users with "john", receives structured JSON response):

I found 8 users with "john" in their name:

John Smith - john.smith@company.com (ID: 1234)

Department: Engineering, Role: Senior Developer

John Doe - j.doe@company.com (ID: 1235)

Department: Marketing, Role: Marketing Manager

Johnson Miller - johnson.miller@company.com (ID: 1236)

Department: Sales, Role: Sales Representative

Johnny Wilson - johnny.w@company.com (ID: 1237)

Department: IT, Role: System Administrator

John Anderson - john.anderson@company.com (ID: 1238)

Department: HR, Role: HR Specialist

Which user would you like to get more details about? I can show you their complete profile, recent activity, and permissions.

User: "Get details for John Smith"

LLM (calls get_user_details with ID 1234, receives structured JSON):

Here are the complete details for John Smith:

Basic Information:

Email: john.smith@company.com

Department: Engineering

Role: Senior Developer

Status: Active

Last Login: 2024-01-15 09:30 AM

Permissions:

Code Repository Access

Development Environment

Project Management Tools

Recent Activity:

2024-01-15: Logged into development environment

2024-01-14: Updated project documentation

2024-01-13: Submitted code review

Is there anything you'd like to update about John's account? I can help you modify his role, department, permissions, or other information.

Key Takeaways for Production MCP Servers

Structured JSON with mimeType - Use type: "text" with mimeType: "application/json" for all structured data responses
Separate guidance blocks - Use additional text content blocks for LLM instructions and context
Help tools are essential - Both for users and LLMs to understand capabilities
Detailed schemas matter - Verbose descriptions help LLMs use tools correctly
Design tool chains - Make tools flow naturally with structured responses
Handle errors gracefully - Return structured error data with guidance
Plan for scale - Include pagination metadata in structured responses
Manage state explicitly - Use structured context objects for complex workflows
Always include next actions - Tell the LLM what the user can do next
Build for resilience - Structure error responses consistently
Add observability - Include logging and monitoring for production use

The goal is to create responses that are both machine-readable (proper JSON content with mimeType) and human-friendly (through LLM guidance). This dual approach ensures your MCP servers can handle real-world complexity while maintaining excellent user experience.

Remember: the JSON content tells the LLM what happened, while the guidance blocks tell it how to help the user with that information. Together, they create a powerful AI collaboration experience that feels natural and intuitive to users.

Perl Catalyst: Thoughts on Chained Actions

John Napiorkowski — Wed, 12 Feb 2025 21:25:50 +0000

Introduction

Chained Actions in Catalyst give you a lot of power and design flexibility but continue to give newbies to the system a lot of trouble understanding how they work. In addition when you have a chain of actions that span controllers there is no current method to express or determine that relationship. In this blog I'll be exploring this issue and propose an idea I'd love to get feedback on.

Standard Example

Here's a simple example of Catalyst action chaining for an HTTP request of 'https://example.local/tasks/create'. This chain starts in the Root controller, passes into the Tasks controller and finalizes in the Tasks::Task controller. I will only show the actions most directly relevant to this endpoint. First the Root controller:

package Example::Controller::Root;

use Moose;
use MooseX::Attributes

extends 'Catalyst::ControllerPerRequest';

## ANY /...
sub root :Chained('/') CaptureArg(0) ($self, $c) { }

  ## ANY /...
  sub private :Chained(root) PathPart('') ($self, $c) {
    return $c->redirect_to_action('/session/show') && $c->detach
      unless $c->user->authenticated;
  }

# The order of the Action Roles is important!!
sub end :Action Does('RenderErrors') Does('RenderView') { }

__PACKAGE__->config(namespace=>'');
__PACKAGE__->meta->make_immutable;

Now the Tasks Controller:

package Example::Controller::Tasks;

use Moose;
use MooseX::Attributes

extends 'Catalyst::ControllerPerRequest';

has 'tasks', (
  is=>'ro',
  lazy=>1,
  default => sub ($self, $c) {
    return $c->user->search_related('tasks')->with_comments_labels;
  }
);

# ANY /tasks/...
sub root :Chained('../private') PathPart('task') CaptureArgs(0) ($self, $c) { }

  # GET /tasks/list
  sub list :GET Chained('root') PartPart('list') Args(0) QueryModel() ($self, $c, $qm) {
    return $self->view(tasks => $self->tasks->page($qm->page));
  }

__PACKAGE__->meta->make_immutable;

Finally the Task::Tasks controller

package Example::Controller::Tasks;

use Moose;
use MooseX::Attributes;
use Types::Standard qw(Int);

extends 'Catalyst::ControllerPerRequest';

has 'tasks' => (
  is => 'ro',
  lazy => 1,
  default => sub($self, $c) {
    return $c->controller('Tasks')->tasks;
  }
);

has 'task' => (is => 'rw');

# ANY /tasks/...
sub root :Chained('../root') PathPart('') CaptureArgs ($self, $c) { }

  ### CREATE ACTIONS ###

  # ANY /tasks/...
  sub build :Chained('root') PathPart('') CaptureArgs ($self, $c) {

    $self->task($self->tasks->new_task);
  }

    # ANY /tasks/create/...
    sub setup_create :Chained('build') PathPart('create') CaptureArgs ($self, $c) {
      $self->view_for('create', task => $self->task);
    }

      # GET /tasks/create
      sub show_create :GET Chained('setup_create') PathPart('') Args(0) ($self, $c) { return }

      # POST /tasks/create
      sub create :POST Chained('setup_create') PathPart('') Args(0) BodyModel() QueryModel() ($self, $c, $rm, $q) {
        return $self->process_request($rm, $q);
      }

__PACKAGE__->meta->make_immutable;

In this example creating a URL that has actions chained across three controllers requires quite a lot of non intuitive boilerplate, mostly attributes on the action methods. In addition the relationship between all three controllers is implicit but not discoverable. The thing I find newcomers get confused about is how to figure out which actions are part of the chain, as well as how to control which part of the URL any given action is trying to match.

I've been dog fooding code for my personal projects that looks more like this:

package Agendum::Controller::Root;

use CatalystX::Object;
use Agendum::Syntax;

extends 'Agendum::Controller';

## ANY /...
sub root :StartAt('/...') ($self, $c) { }

  ## ANY /...
  sub private :Via('root') At('/...') ($self, $c) {
    return $c->redirect_to_action('/session/show') && $c->detach
      unless $c->user->authenticated;
  }

# The order of the Action Roles is important!!
sub end :Action Does('RenderErrors') Does('RenderView') { }

__PACKAGE__->config(namespace=>'');
__PACKAGE__->meta->make_immutable;

package Agendum::Controller::Tasks;

use CatalystX::Object;
use Agendum::Syntax;

extends 'Agendum::Controller';

parent 'Root';

has 'tasks', (
  is=>'ro',
  lazy=>1,
  default => sub ($self, $c) {
    return $c->user->search_related('tasks')->with_comments_labels;
  }
);

# ANY /tasks/...
sub root :ViaParent('private') At('/tasks/...')  ($self, $c) { }

  # GET /tasks/list
  sub list :Via('root') Get('list')  QueryModel() ($self, $c, $qm) {
    return $self->view(tasks => $self->tasks->page($qm->page));
  }

__PACKAGE__->meta->make_immutable;

package Agendum::Controller::Tasks::Task;

use CatalystX::Object;
use Agendum::Syntax;
use Types::Standard qw(Int);

extends 'Agendum::Controller';

parent 'Task';

has 'tasks' => (
  is => 'ro',
  lazy => 1,
  default => sub($self, $c) {
    return $self->parent->tasks;
  }
);

has 'task' => (is => 'rw');

# ANY /tasks/...
sub root :ViaParent('root') At('/...') ($self, $c) { }

  # ANY /tasks/...
  sub build :Via('root') At('/...') ($self, $c) {
    $self->task($self->tasks->new_task);
  }

    # ANY /tasks/create/...
    sub setup_create :Via('build') At('create/...')  ($self, $c) {
      $self->view_for('create', task => $self->task);
    }

      # GET /tasks/create
      sub show_create :Via('setup_create') Get('')  ($self, $c) { }

      # POST /tasks/create
      sub create :Via('setup_create') Post('')  BodyModel() QueryModel() ($self, $c, $rm, $q) {
        return $self->process_request($rm, $q);
      }

#... rest of controller

__PACKAGE__->meta->make_immutable;

In this proposal the chaining attribute syntax is collapsed into basically just two types of attributes; 'Via' (or ViaParent) to indicate the action we are chaining off, and 'At' (or its HTTP Method versions, 'Get', 'Post', etc), which expresses the part of the Url we are matching. Additionally we introduced a global keyword 'parent' which indicates the controller which is the 'parent' to the current. This lets us use the distinctive 'ViaParent' to make it clear that the action we are chaining off lies in the parent controller, not the current one.

The goal here is to both reduce the legacy syntax as well as make it more clear what the flow of actions are.

Thoughts?

Catalyst Tricks: Map Request Parameters to a Model

John Napiorkowski — Sun, 22 Dec 2024 17:46:38 +0000

Introduction

Dealing with incoming request parameters (both query and body parameters) is something nearly all Perl Catalyst applications need to cope with. Unfortunately Catalyst punts here and doesn't give you a lot of guidance and the built in handling leaves a lot to be desired. In this blog I will first example how the default handling works, some of the problems with it and how Catalyst developers have tried to improve it over the years (with minor success IMHO; I can say that since half the redos are my fault ;)).

How Catalyst Handles Request Bodies and Query Parameters

By default incoming query and body parameters get mapped to the Catalyst Request object:

  $c->request->query_parameters
  $c->request->body_parameters

query_parameters gives you access to parameters passed in the 'query' section of your request URL. For example if your URL is https://example.com/page/?aaa=1&bbb=2 then query_parameters will return the following hashref:

  +{
    aaa => "1",
    bbb => "2",
  }

The body_parameters method gives you access to classic HTML Form POST bodies. For example if you have an HTML Form like this:

<form action="/login" method="post">
    <label for="username">Username:</label>
    <input type="text" id="username" name="username">
    <label for="password">Password:</label>
    <input type="password" id="password" name="password">
    <button type="submit">Login</button>
</form>

When the user clicks the submit button you would expect the following hashref in body_parameters:

  +{
    username => "$USERNAME",
    password => "$PASSWORD",
  }

(Substitute $USERNAME and $PASSWORD for whatever the user typed into the form).

Both method return a hashref of key value pairs where the key in the field or parameter and the value is a scalar or arrayref (depending on if there is one or several values for the given field in the request).

For basic applications this has worked acceptably but there's a number of issues. First of all the fact that the key can be either a scalar or arrayref is annoying, requiring you to write tons of defensive code like:

my $username = $c->req->body_parameters->{username};
$username = ref $username eq 'ARRAY' ? $username[-1] : ($username);

Or just ignore the problem and potentially open yourself to security issues. Speaking of security issues I don't know how many times I've seen code like this, passing incoming body parameters straight into a DBIx::Class object:

  my $new_user = $c->model('Schema::User')->create($c->req->body_parameters);

This is a world of hurt since you are basically passing whatever the user submitted (or your site hacker is submitting) directly to DBIC create. You need to be more choosey about the incoming at the very least:

  my $new_user = $c->model('Schema::User')->create(
    username => ref($c->req->body_params->{username}) eq 'ARRAY' ? $c->req->body_params->{username}[-1] : $c->req->body_params->{username},
    password => ref($c->req->body_params->{password}) eq 'ARRAY' ? $c->req->body_params->{password}[-1] : $c->req->body_params->{password},
  );

At which point you are starting to have a lot of ugly code and you haven't even started on form validation yet. And with all this repeated code its easy to have a hard to spot typo:

  my $new_user = $c->model('Schema::User')->create(
    username => ref($c->req->body_params->{username}) eq 'ARRAY' ? $c->req->body_params->{usrname}[-1] : $c->req->body_params->{usernme},
  ...

I've seen a lot of typo issues in Catalyst applications just like this, and they can lead to hard to spot problems since in Perl having a typo in the hash de-reference will not lead to a hard runtime error generally, you just get 'undef' for a value in an unexpected location. I've seen this problem in Catalyst code which existed for years in the wild.

Another thing I've seen a lot of is line after line of parameter processing code stuck into controllers. As it turns out parameter munging is one of the bigger jobs a programmer in a web application can have, especially as the application gets older and you need to introduce new features without breaking backward compatibility. This can lead to very long and ugly controllers that make following the flow of logic in your request to response cycle difficult.

You can solve the 'is it a value or an arrayref?' problem by enabled the use_hash_multivalue_in_request configuration option. This gives you a Hash::MultiValue object instead of a hashref of request parameters. Amongst other things it make it easy to say 'when there's more than one value give me only the last one', which is nearly always the right thing as legitimate uses for this typically revolve around HTML Form tricks where some field types like checkboxes don't make it easy to know when the user is explicitly setting an 'off' state. See CONFIGURATION For more. This however doesn't really help with the other problems such as easy to make typos or dirtying up your controllers with tons of parameter tweaking code.

Mapping Incoming Request Parameters to a Model

One trick I've used for years when encountering this issue is to use a Catalyst Model as a container for my request parameters. This model converts the hashref to an actual object with methods, which means any typos get picked up at runtime fast. This model is also a great place to stick validations and incoming value filters, as well as a good spot to stick and complex logic involving these parameters. Let's keep this simple and just see how one might do that for the example login form already described:

package Example::Model::Params::Login;

use Moose;
use Valiant::Validations;
use Valiant::Filters;

extends 'Catalyst::Model';
with 'Catalyst::Component::InstancePerContext';

sub build_per_context_instance {
  my ($self, $c) = @_;
  my $body = ref($self)->new(%{$c->req->query_parameters}, ctx=>$c);
  return $body->validate; # ->validate returns '$self' for chaining
}

has ctx => (is=>'ro');

has username => (
  is => 'ro',
  validates => [
    presence => 1,
    length => {
      maximum => 64,
      minimum => 1,
    },
  ],
);

has password => (
  is => 'ro',
  validates => [
    presence => 1,
    length => {
      maximum => 64,
      minimum => 1,
    },
  ],
);

has user => (
  is => 'ro',
  lazy => 1,
  predicate => 'has_user',
  default => \&_find_user,
  validates => [
    presence => {message=>'User Not Found with credentials.'},
  ],
)

filters_with 'Truncate', max_length=>100;

sub _find_user {
  my $self = shift;
  my $user = $self->ctx
    ->model('Schema::User')
    ->find({username=>$self->username});

  return unless $user && $user->password_eq($self->password);  
  return $user;
}

This cleanly encapsulates the entire job of getting the POSTed parameters, making sure they are valid and that the parameters match a user in the database (and that the given password matches the latest in the DB via the password_eq method, which is an exercise I leave for you; don't forget to hash your passwords in the DB!).

You can use it in a controller similar to:

package Example::Controller::Session;

use Moose;
use MooseX::Attributes;

extends 'Catalyst::Controller';

sub login :Path Args(0) {
  my ($self, $c) = @_;
  my $params = $c->model('Params::Login');
  return $c->login_user($params->user) if $params->valid;
  return $c->stash(params => $params);
}

In this example we map the incoming request body to $params and if the object is valid we perform the login workflow (via login_user($user), a method that again I leave to your imagination but probably involves storing the user id in the session and redirecting to some sort of "You're Logged in" page). If it not we stick $params in the stash and let the view inspect it for the errors, displaying such to the user in whatever view system you prefer.

Conclusion

In real life you'd probably use the Authentication plugin for something like this, but the general idea here can map to basically any type of incoming query or request bodies, even those via APIs requests that might be in JSON rather than a form POST. What you get is a nice, clear separation of concerns that improves code readability and long term maintainability. I like the idea so much, and started using it so much that I've tried to encapsulate the pattern in CatalystX::RequestModel. Other approaches on CPAN that can do similar would be HTML::FormHandler, although that tends to focus more on validation and HTML Form field generation, so might be a bigger hammer than you want.

Modules mentioned in this blog include Catalyst and Valiant

Bonus Idea

I often use a similar approach to wrap the Catalyst session (also represented as a hash reference) in a model, to offer a strongly typed interface to the session. Can you figure out the code for that?

Forem: John Napiorkowski

PAGI::Server, now with HTTP/2!

The Quick Version

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

Where h2c Matters

A Note on Proxies

HTTP/2 Over TLS -- No Proxy Required

What PAGI::Server Does

Dual-Mode Protocol Detection

WebSocket over HTTP/2 (RFC 8441)

Compliance

Multi-Worker and Tunable

Context in the Perl Ecosystem

What Else Is in 0.001017

Getting Started

Links

PAGI 0.001016: Navigating the Future::IO Configuration Problem

What is Future::IO?

The Problem

What Doesn't Work

The Tradeoffs We Considered

Option 1: Apps Configure Future::IO

Option 2: Extend the PAGI Spec

Option 3: Entry Point Configures

What We Chose

Why This Felt Right (Eventually)

Also in This Release: SSE Query Parameters

This Is Experimental - RFC Welcome

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

Prompt Engineering or selling your soul?

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

The kind of questions that save you

A realistic failure mode this prevents

When I don’t use it

Copy/paste template you can steal

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

Architecture in one paragraph

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

Baseline: fast responses

Streaming test: 2-second responses, 500 concurrent clients

A gotcha: TTY logging will ruin your benchmark

Overload behavior: what happens at 2500 concurrent streams?

Scaling out: 16 workers

The real test: slow clients and backpressure

Slow client test

High-throughput clients

Concurrency + large bodies

The subtle risk we identified (and addressed)

What I did not see (important)

Final assessment

Perl PAGI Project Update

What We Learned Shipping PAGI

Sometimes the Right Code is No Code

Async Error Handling Done Right

Making PAGI Feel Like Perl

What's Next

Get Involved

PAGI::Server Performance and Hardening

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

The Joy of Code in the Age of Vibe Engineering

From vibe coding to vibe engineering

PAGI and the hollow aftertaste

Authorship, credit, and open source discomfort

Mastery, necessity, and selective depth

When vibe engineering feels like mercy

Thinking out loud without the paralysis

Where joy lives now

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

Introducing PAGI: Async Web Development for Perl

The Problem

What is PAGI?

A Simple HTTP Example

WebSocket Support

PSGI Compatibility

PAGI::Simple Micro-Framework

Current Status

Getting Started

Why This Matters

Building Effective MCP Servers: Patterns for AI Collaboration

Building Effective MCP Servers: Advanced Patterns for Production-Ready AI Collaboration