NAME

PAGI::Tutorial - Learn the PAGI protocol for async Perl web applications

DESCRIPTION

PAGI (Perl Asynchronous Gateway Interface) is a protocol, not a framework. It is a small, well-defined contract for hooking an asynchronous Perl application up to an asynchronous server: your application is an async sub that receives a connection scope and two coderefs (one to receive events from the client, one to send events back), and that is essentially the whole specification. PAGI also defines a loop-agnostic way to model custom asynchronous events (HTTP, WebSocket, Server-Sent Events, lifespan, and your own), so the same application code runs unchanged on any conforming server, under any event loop.

This tutorial teaches the protocol itself. To run the examples you need a server, and we use PAGI::Server (the reference implementation, from the PAGI-Server distribution) because it is a complete, fully-featured PAGI server. Nothing in the protocol depends on it; any conforming server would do.

The only hard requirement for a PAGI application is Future::AsyncAwait for async/await syntax. The event loop (IO::Async, in PAGI::Server's case) is an implementation detail of the server, not of your application.

Along the way we occasionally point at the PAGI-Tools distribution, which provides convenience helpers (middleware, routers, request/response sugar, ready-made apps). Those are entirely optional: ordinary PAGI applications and helpers built on top of the protocol, never required to write a complete PAGI application. For a guide to them, see PAGI::Tools::Tutorial.

PART 1: GETTING STARTED

1.1 Introduction

What is PAGI?

PAGI (Perl Asynchronous Gateway Interface) is a protocol for building asynchronous web applications in Perl: a specification for how an async application and an async server talk to each other. It is a spiritual successor to PSGI that embraces modern async/await patterns using Future::AsyncAwait and provides first-class support for WebSockets, Server-Sent Events, and HTTP/1.1.

Unlike traditional synchronous web frameworks, PAGI allows your application to handle multiple concurrent connections efficiently without blocking, making it ideal for:

WebSocket applications (real-time chat, live updates)
Server-Sent Events (SSE) for streaming data
Long-polling and streaming responses
High-concurrency applications
Applications that make multiple I/O calls per request

Why Async?

Traditional synchronous web frameworks handle one request at a time per process. When your application waits for a database query, an external API call, or file I/O, the entire process is blocked and can't handle other requests.

The Traditional Solution: Forking Servers

Perl web applications have traditionally used pre-forking servers like Starman to achieve concurrency. Starman spawns multiple worker processes, each handling one request at a time. This approach works well and has served the Perl community for years:

Approach        | Forking (Starman)           | Async (PAGI)
----------------|-----------------------------|--------------------------
Concurrency     | Multiple processes          | Single process, event loop
Memory          | Each worker copies app      | Shared memory, lower usage
Connections     | Limited by worker count     | Thousands per process
WebSocket/SSE   | Impractical (ties up worker)| Natural fit
Blocking I/O    | Fine (isolated per worker)  | Must use async libraries
CPU-bound work  | Fine (isolated per worker)  | Blocks event loop (use workers)
Debugging       | Simpler (sequential code)   | Trickier (async flow)
Existing code   | Works as-is                 | May need async adapters

When to use which:

Starman/forking - CPU-heavy work, existing sync codebases, simple request/response apps, blocking database drivers
PAGI/async - WebSockets, SSE, long-polling, high connection counts, I/O-bound apps, real-time features

Many applications benefit from both the async model (for real-time endpoints like WebSocket and SSE) and pre-forking (for CPU-bound request/response work). The reference server, PAGI::Server, combines them with its worker mode (--workers N): several pre-forked workers, each running the async event loop. That is a feature of the server, not of the PAGI protocol.

The Async Advantage

Asynchronous programming allows your application to handle multiple requests concurrently in a single process. When one request is waiting for I/O, the event loop can switch to another request, dramatically improving resource utilization and response times.

This is especially important for:

Real-time bidirectional communication (WebSockets)
Keeping connections open for streaming (SSE)
Applications that make multiple external API calls
High-traffic applications where blocking I/O is a bottleneck

PAGI vs PSGI

If you're familiar with PSGI, here are the key differences:

Feature          | PSGI                    | PAGI
-----------------|-------------------------|---------------------------
Execution Model  | Synchronous             | Asynchronous (async/await)
Application Sig  | sub { $env }            | async sub { $scope, $receive, $send }
Request Metadata | %env hash               | %scope hash
Request Body     | $env->{'psgi.input'}    | await $receive->()
Response         | [\@status, \@headers, \@body] | await $send->({...})
WebSocket        | Not supported           | First-class support
SSE              | Hacky streaming         | First-class support
Backpressure     | No explicit control     | Explicit via Futures

The async model means you can write code that looks synchronous (thanks to async/await) while getting all the benefits of non-blocking I/O.

Prerequisites

To use PAGI, you'll need:

Perl 5.18 or later - the floor for the PAGI distributions (the specification, the reference server, and the toolkit)
Future::AsyncAwait - Provides async/await syntax
Basic understanding of Futures and async programming (we'll cover the essentials)

Note: A bare PAGI application's only hard dependency is Future::AsyncAwait (for async/await syntax), which supports Perl back to 5.16; the event loop (IO::Async) is an implementation detail of the server, and using Future::IO for timers and I/O keeps your code portable across servers. In practice, though, you run on something: the specification, the reference server PAGI::Server, and the PAGI-Tools toolkit all require Perl 5.18 or later, and another server or a higher-level framework may require a newer Perl still. The minimum version you need is the floor of whatever you build on.

1.2 Installation

Installing PAGI from CPAN:

cpanm PAGI

Or from source:

git clone https://github.com/jjn1056/pagi.git
cd PAGI
cpanm --installdeps .

To include development dependencies (for testing):

cpanm --installdeps . --with-develop

Verify the installation:

pagi-server --version

Installing PAGI currently also pulls in the PAGI-Server reference server and the PAGI-Tools helpers for backward compatibility during the transition; see "INSTALLATION AND BACKWARD COMPATIBILITY" in PAGI.

About pagi-server

Throughout this tutorial, we'll use pagi-server to run our examples. PAGI::Server is the reference implementation of a PAGI server - it's a fully-featured async HTTP server built on IO::Async that supports HTTP/1.1, WebSockets, Server-Sent Events, TLS, and multi-worker mode.

At the time of writing, pagi-server is the only PAGI-compatible server available. However, the PAGI specification is designed to be server-agnostic, so future servers (perhaps built on different event loops like Mojo::IOLoop or AnyEvent) could run the same application code without modification.

1.3 Your First PAGI App

Let's create a simple "Hello, World!" application. Create a file called hello.pl:

use strict;
use warnings;
use Future::AsyncAwait;

async sub app {
    my ($scope, $receive, $send) = @_;

    # Only handle HTTP requests (server also sends lifespan events)
    die "Expected http scope" unless $scope->{type} eq 'http';

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

    # Send the response body
    await $send->({
        type => 'http.response.body',
        body => 'Hello, World!',
    });
}

# Return a reference to the app subroutine
\&app;

Let's break down what's happening:

1. async sub app - Declares an asynchronous subroutine using Future::AsyncAwait

2. ($scope, $receive, $send) - The three parameters every PAGI app receives:

$scope - Hash reference containing request metadata (method, path, headers, etc.)
$receive - Async code reference for receiving events from the client
$send - Async code reference for sending events to the client

3. die "Expected http scope" unless $scope->{type} eq 'http' - The server calls your app for different event types (HTTP requests, WebSocket, lifespan). Applications must throw an exception for unrecognized scope types to prevent silent protocol mismatches.

4. await $send->({...}) - Sends events asynchronously, waiting for each to complete

5. \&app - Returns a reference to the application subroutine

Run your application:

pagi-server hello.pl --port 5000

Test it:

curl http://localhost:5000/

You should see:

Hello, World!

Try accessing it from a browser by visiting http://localhost:5000/.

Environment Modes

pagi-server supports environment modes that control middleware behavior:

development (default when running interactively): Auto-enables PAGI::Middleware::Lint with strict mode, which catches PAGI specification violations early and provides helpful error messages. Note that Lint lives in the PAGI-Tools distribution: pagi-server applies it only when PAGI-Tools is installed, and otherwise prints a reminder that you can install PAGI-Tools to enable it and runs without it.
production (default when running non-interactively): No middleware is auto-enabled, and access logging is disabled for maximum performance. This is the default when running under systemd, docker, cron, or any non-TTY environment. Use --access-log FILE or --access-log FILE to enable logging.
none: Explicit opt-out of all auto-middleware, regardless of TTY detection.

Mode is determined by (in order of precedence):

1. -E / --env command line flag
2. PAGI_ENV environment variable
3. Auto-detection: TTY = development, no TTY = production

After determining the mode, pagi-server sets PAGI_ENV to the resolved value. Your app can check $ENV{PAGI_ENV} to know what mode it's running in, similar to Plack's PLACK_ENV.

Examples:

# Auto-detect mode (TTY = development)
pagi-server hello.pl

# Explicit production mode
pagi-server -E production hello.pl

# Via environment variable
PAGI_ENV=production pagi-server hello.pl

# Disable auto-middleware even in development
pagi-server --no-default-middleware hello.pl

The development mode Lint middleware helps catch common mistakes like forgetting to await your $send calls or returning without sending a response.

Inspecting the Scope

The $scope hash contains metadata about the current connection - similar to PSGI's $env hash. It tells you everything about the request before you read the body: the HTTP method, path, headers, query string, client address, and more. Unlike PSGI where everything is in one flat hash, PAGI separates the metadata ($scope) from the body (read via $receive).

Let's modify the app to show what's in $scope:

use strict;
use warnings;
use Future::AsyncAwait;
use Data::Dumper;

async sub app {
    my ($scope, $receive, $send) = @_;

    die "Expected http scope" unless $scope->{type} eq 'http';

    my $body = Dumper($scope);

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

    await $send->({
        type => 'http.response.body',
        body => $body,
    });
}

\&app;

Run this and visit http://localhost:5000/test?foo=bar. You'll see the scope hash which includes:

type - Connection type (http, websocket, sse, lifespan)
method - HTTP method (GET, POST, etc.)
path - URL path (decoded UTF-8)
raw_path - URL path (raw bytes)
query_string - Query string (raw bytes)
headers - Array reference of [name, value] pairs
server - Server address and port
And more...

1.4 Understanding the Event Loop: Blocking vs Non-Blocking

Understanding the event loop is crucial to writing efficient PAGI applications. Let's visualize how it works.

The Event Loop

PAGI servers use an event loop to manage asynchronous operations. Here's a simplified view of how the event loop handles multiple connections:

Single-Threaded Event Loop

Time -->

Request A: [======API Call (async)======]----[Process]--[Send]
Request B:     [--DB Query (async)--]--------[Process]--------[Send]
Request C:         [Timer (async)]----[Process]----[Send]

Event Loop: [A][B][C][A][B][C][B][A][C][B][A][C][A][B]
            |  |  |  |  |  |  |  |  |  |  |  |  |  |
            Continuously switching between requests as they wait

When you use await, you're telling the event loop "I'm waiting for something, go handle other requests until this completes." The event loop can then switch to another request, making efficient use of CPU time.

Non-Blocking Operations (GOOD)

These operations yield control to the event loop:

use Future::AsyncAwait;
use Future::IO;

async sub good_app {
    my ($scope, $receive, $send) = @_;

    # Good: Async sleep (doesn't block) - loop-agnostic!
    await Future::IO->sleep(5);

    # Good: Async HTTP client (doesn't block)
    # Use Net::Async::HTTP, HTTP::Tiny::Async, or similar
    # my $response = await $http->GET('https://api.example.com/data');

    # Good: Async database query (using an async DB driver)
    # my $row = await $db->selectrow_async('SELECT * FROM users WHERE id = ?', $user_id);

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

    await $send->({
        type => 'http.response.body',
        body => 'Non-blocking operations completed!',
    });
}

\&good_app;

Blocking Operations (BAD)

These operations block the entire process:

use Future::AsyncAwait;
use LWP::UserAgent;  # Synchronous HTTP client
use DBI;             # Most DBI drivers are synchronous

async sub bad_app {
    my ($scope, $receive, $send) = @_;

    # BAD: Blocks for 5 seconds, prevents other requests from being handled
    sleep 5;

    # BAD: Synchronous HTTP request blocks until complete
    my $ua = LWP::UserAgent->new;
    my $response = $ua->get('https://api.example.com/data');

    # BAD: Synchronous database query blocks
    # my $dbh = DBI->connect(...);
    # my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE id = ?', undef, $user_id);

    # BAD: Expensive CPU operation blocks (e.g., bcrypt password hashing)
    # my $hashed = bcrypt_hash($password);  # Takes ~100ms

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

    await $send->({
        type => 'http.response.body',
        body => 'Blocking operations completed (badly)!',
    });
}

\&bad_app;

Why Blocking is Bad

Let's do the math:

You have 1,000 concurrent connections
Each request needs to make a synchronous database query that takes 100ms
With a blocking operation, each connection is stuck for 100ms
1,000 connections x 100ms = 100 seconds of total blocked time
With async operations, all 1,000 queries can be in-flight simultaneously

In a single-threaded event loop, one blocking operation prevents ALL other connections from making progress. A single sleep(5) will freeze your entire application for 5 seconds!

Solutions for Blocking Operations

When you must use blocking operations, you have options:

1. Use Async Libraries

Prefer async alternatives when available:

Future::IO->sleep($secs) instead of sleep() - loop-agnostic!
Net::Async::HTTP instead of LWP::UserAgent
Net::Async::Redis instead of synchronous Redis clients
Database::Async for async database access (PostgreSQL, MySQL, SQLite)

2. Use a Worker Pool for CPU-bound Work

For CPU-intensive operations (password hashing, image processing), offload to a subprocess. See PAGI::Cookbook for patterns using IO::Async::Function or external job queues.

What about worker mode? Running with --workers N does NOT solve blocking for individual connections. If a worker has a WebSocket connection and does a blocking operation, that WebSocket will freeze until the operation completes. Worker mode only means other connections on other workers aren't affected. See section 1.5 for when worker mode is actually useful.

1.5 Worker Mode

PAGI::Server supports two deployment modes: single-process and multi-worker.

Single Process vs Worker Mode

Single Process Mode:

[Master Process]
  |
  +-- Runs event loop
  +-- Handles all connections
  +-- Good for: async apps, development, low-medium traffic


Worker Mode:

[Master Process]
  |
  +-- [Worker 1] (handles connections)
  +-- [Worker 2] (handles connections)
  +-- [Worker 3] (handles connections)
  +-- [Worker 4] (handles connections)

Good for: multi-core utilization, crash isolation, high traffic

When to Use Worker Mode

Scenario                           | Single Process | Worker Mode
-----------------------------------|----------------|-------------
Pure async app (no blocking)       | Yes            | Yes
Multi-core server in production    | Wastes cores   | Yes
Crash isolation needed             | No             | Yes
WebSocket/SSE with shared state    | Yes            | Needs PubSub
Development/testing                | Yes            | Optional

Important: Worker mode does NOT fix blocking operations. Each worker still runs a single-threaded event loop. If you do a blocking operation in a worker, ALL connections on that worker freeze (including any WebSocket or SSE connections). To avoid blocking, use async libraries as described in section 1.4.

Running with Workers

Start the server with multiple worker processes:

pagi-server hello.pl --port 5000 --workers 4

This creates:

1 master process that accepts connections
4 worker processes that handle requests
Automatic worker respawning if a worker crashes

The number of workers should typically match your CPU core count:

# Check your CPU core count and set workers accordingly
# On Linux: nproc   On macOS: sysctl -n hw.ncpu
pagi-server hello.pl --port 5000 --workers 4

Worker Isolation

Important: Each worker process is isolated. They do NOT share:

Memory (variables are per-worker)
Database connections
WebSocket connections
Application state

Wrong: Shared State in Memory

This will NOT work correctly across workers:

# DON'T DO THIS in worker mode!
my $counter = 0;  # Each worker has its own $counter

async sub app {
    my ($scope, $receive, $send) = @_;

    $counter++;  # Only increments in THIS worker

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

    await $send->({
        type => 'http.response.body',
        body => "Counter: $counter",  # Will show different values per worker
    });
}

\&app;

Right: External State Storage

Use a shared backend for state. For example with Redis (see PAGI::Cookbook for complete Redis examples):

use Future::AsyncAwait;

# Assume $redis is set up during lifespan startup
# See PAGI::Cookbook for Redis connection patterns

async sub app {
    my ($scope, $receive, $send) = @_;

    # Increment counter in Redis (shared across all workers)
    my $counter = await $redis->incr('request_counter');

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

    await $send->({
        type => 'http.response.body',
        body => "Counter: $counter",  # Accurate across all workers
    });
}

\&app;

For WebSocket applications that need to broadcast messages across workers, use an external message broker like Redis pub/sub.

PART 2: UNDERSTANDING RAW PAGI

In Part 1, we covered the basics of PAGI applications and the event loop. Now we'll dive deeper into the raw PAGI protocol, exploring how to work directly with the three arguments ($scope, $receive, and $send) before introducing higher-level abstractions.

Understanding raw PAGI is important because:

It helps you understand what's happening under the hood
You can build custom middleware and utilities
You'll appreciate what frameworks like PAGI::Endpoint::Router do for you
You can handle edge cases that frameworks might not cover

2.1 The Three Arguments

Every PAGI application receives exactly three arguments:

async sub app {
    my ($scope, $receive, $send) = @_;
    # ... your code here
}

Let's examine each in detail.

$scope - Connection Metadata

$scope is a hash reference containing metadata about the connection and request. The contents vary depending on the connection type.

For HTTP requests (type => 'http'):

{
    type => 'http',
    method => 'GET',               # HTTP method
    path => '/users/123',          # URL path (decoded UTF-8)
    raw_path => '/users/123',      # URL path (raw bytes)
    query_string => 'foo=bar',     # Query string (raw bytes)
    headers => [                   # Array of [name, value] pairs
        ['host', 'localhost:5000'],
        ['user-agent', 'curl/7.68.0'],
        ['content-type', 'application/json'],
    ],
    server => ['127.0.0.1', 5000], # Server address and port
    client => ['127.0.0.1', 54321],# Client address and port
    scheme => 'http',              # 'http' or 'https'
    http_version => '1.1',         # HTTP version
    extensions => { ... },         # PAGI extensions
}

For WebSocket connections (type => 'websocket'):

{
    type => 'websocket',
    path => '/ws',
    headers => [ ... ],
    subprotocols => ['chat', 'superchat'],  # Requested subprotocols
    # ... other fields similar to http
}

For SSE connections (type => 'sse'):

{
    type => 'sse',
    path => '/events',
    headers => [ ... ],
    # ... other fields similar to http
}

For lifespan events (type => 'lifespan'):

{
    type => 'lifespan',
}

$receive - Receiving Client Events

$receive is an asynchronous code reference that returns a Future. Call it to receive the next event from the client:

my $event = await $receive->();

The structure of $event depends on the connection type and what's happening.

For HTTP requests, you receive body chunks:

{
    type => 'http.request',
    body => '{"name":"John"}',  # Raw bytes
    more => 0,                  # 0 = last chunk (default), 1 = more coming
}

For WebSocket, you receive messages and disconnect events:

# Message received
{
    type => 'websocket.receive',
    text => 'Hello!',           # For text messages
    # OR
    bytes => "\x00\x01\x02",    # For binary messages
}

Why separate text and bytes keys? The WebSocket protocol itself distinguishes text frames (must be valid UTF-8) from binary frames (arbitrary bytes) at the wire level. Having separate keys provides three benefits: (1) you can use both on the same connection - e.g., text for JSON commands, binary for audio streams; (2) type safety - you know exactly what you received without ambiguity; (3) you can't accidentally mishandle encoding. If you don't care about the distinction: my $data = $event->{text} // $event->{bytes}. The PAGI::WebSocket helper class abstracts this for most use cases.

# Connection closed
{
    type => 'websocket.disconnect',
    code => 1000,               # Close code
    reason => 'Normal closure', # Close reason
}

For lifespan, you receive startup and shutdown events:

{ type => 'lifespan.startup' }
{ type => 'lifespan.shutdown' }

$send - Sending Events to Client

$send is an asynchronous code reference that sends events to the client. It returns a Future that completes when the event has been sent:

await $send->({ type => 'http.response.start', status => 200, headers => [...] });
await $send->({ type => 'http.response.body', body => 'Hello' });

The events you send depend on the connection type.

2.2 Scope Types

PAGI defines four scope types, each representing a different kind of connection or event.

http - Standard HTTP Requests

The most common type. Used for normal HTTP request/response cycles.

Check for it:

if ($scope->{type} eq 'http') {
    # Handle HTTP request
}

websocket - WebSocket Connections

Used for bidirectional real-time communication. WebSocket connections start as HTTP upgrade requests.

Check for it:

if ($scope->{type} eq 'websocket') {
    # Handle WebSocket connection
}

See PAGI::WebSocket for WebSocket utilities.

sse - Server-Sent Events

A PAGI extension for server-to-client streaming. SSE allows the server to push updates to the client over a long-lived HTTP connection.

Check for it:

if ($scope->{type} eq 'sse') {
    # Handle SSE connection
}

See PAGI::SSE for SSE utilities.

lifespan - Application Lifecycle Events

Used for application startup and shutdown events. This allows your application to initialize resources (database connections, caches, etc.) when it starts and clean them up when it shuts down.

Check for it:

if ($scope->{type} eq 'lifespan') {
    # Handle startup/shutdown
}

Note: PAGI::Endpoint::Router handles this via on_startup and on_shutdown callbacks.

2.3 HTTP Request/Response Cycle (Raw)

Let's build a complete HTTP request handler that reads the request body and echoes it back.

use strict;
use warnings;
use Future::AsyncAwait;

async sub app {
    my ($scope, $receive, $send) = @_;

    # Only handle HTTP requests
    die "Expected http scope" unless $scope->{type} eq 'http';

    # Read the entire request body
    # NOTE: This loop does NOT block the event loop! The 'await' keyword
    # yields control while waiting for data, allowing other requests to
    # be processed. The loop only runs when there's actually data.
    my $body = '';
    while (1) {
        my $event = await $receive->();
        $body .= $event->{body} if defined $event->{body};
        last unless $event->{more};  # Stop when no more chunks
    }

    # Prepare response body
    my $response_body = "You sent: " . (length($body) ? $body : "(empty)");

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

    # Send response body (more => 0 is the default, so can be omitted)
    await $send->({
        type => 'http.response.body',
        body => $response_body,
    });
}

\&app;

Test it:

# Terminal 1: Start server
pagi-server echo.pl --port 5000

# Terminal 2: Send a request with body
curl -X POST -d "Hello, PAGI!" http://localhost:5000/

# Output: You sent: Hello, PAGI!

Key points:

Always check more to know when the request body is complete
Send http.response.start before sending any body
more => 0 is the default for final chunks (can be omitted)
The request body is raw bytes (you may need to decode it)

2.4 WebSocket (Raw)

WebSocket enables bidirectional real-time communication. Here's a simple echo server:

use strict;
use warnings;
use Future::AsyncAwait;

async sub app {
    my ($scope, $receive, $send) = @_;

    # Only handle WebSocket connections
    die "Expected websocket scope" unless $scope->{type} eq 'websocket';

    # Accept the WebSocket connection
    await $send->({
        type => 'websocket.accept',
        # Optional: specify a subprotocol from $scope->{subprotocols}
        # subprotocol => 'chat',
    });

    # Echo loop: receive messages and send them back
    # NOTE: This loop does NOT block! The 'await' yields to the event
    # loop while waiting, allowing other connections to be processed.
    while (1) {
        my $event = await $receive->();

        # Handle disconnection
        if ($event->{type} eq 'websocket.disconnect') {
            warn "Client disconnected: code=$event->{code}, reason=$event->{reason}\n";
            last;
        }

        # Echo text messages
        if (defined $event->{text}) {
            await $send->({
                type => 'websocket.send',
                text => "Echo: $event->{text}",
            });
        }
        # Echo binary messages
        elsif (defined $event->{bytes}) {
            await $send->({
                type => 'websocket.send',
                bytes => $event->{bytes},
            });
        }
    }
}

\&app;

Test it with a WebSocket client:

# JavaScript in browser console:
const ws = new WebSocket('ws://localhost:5000/');
ws.onmessage = (event) => console.log('Received:', event.data);
ws.onopen = () => ws.send('Hello, WebSocket!');

// You should see: Received: Echo: Hello, WebSocket!

Key points:

Must send websocket.accept before sending any messages
Check type eq 'websocket.disconnect' to detect when the client closes the connection
Messages can be text (text) or binary (bytes)
The receive loop blocks waiting for the next message

See PAGI::WebSocket for higher-level utilities that make WebSocket handling easier.

To reject a handshake, send websocket.close before websocket.accept (a bare 403), or -- where the server advertises the websocket.http.response extension -- a websocket.http.response.start/.body pair for a custom response such as a 401. See the cookbook's "Rejecting a handshake with a custom response" and "WebSocket Denial Response (extension)" in PAGI::Spec::Www.

2.5 SSE (Raw)

Server-Sent Events allow the server to push updates to clients over HTTP. Here's a clock that sends the current time every second:

use strict;
use warnings;
use Future::AsyncAwait;
use Future::IO;

async sub app {
    my ($scope, $receive, $send) = @_;

    # Only handle SSE connections
    die "Expected sse scope" unless $scope->{type} eq 'sse';

    # Start the SSE response
    await $send->({
        type => 'sse.response.start',
        status => 200,
        headers => [
            ['cache-control', 'no-cache'],
            ['x-custom-header', 'example'],
        ],
    });

    # Send the current time every second (loop-agnostic!)
    while (1) {
        await $send->({
            type => 'sse.response.body',
            data => scalar(localtime()),
            # Optional fields:
            # event => 'clock',     # Event type
            # id => '123',          # Event ID
            # retry => 5000,        # Retry interval in ms
        });

        # Wait 1 second before next event
        await Future::IO->sleep(1);
    }
}

\&app;

Test it:

# Terminal 1: Start server
pagi-server clock.pl --port 5000

# Terminal 2: Connect with curl
curl http://localhost:5000/

# Output (streaming):
# data: Mon Dec 23 10:30:00 2025
#
# data: Mon Dec 23 10:30:01 2025
#
# data: Mon Dec 23 10:30:02 2025
# ...

JavaScript client:

const eventSource = new EventSource('http://localhost:5000/');
eventSource.onmessage = (event) => {
    console.log('Time:', event.data);
};

Key points:

Send sse.response.start first with headers
Send sse.response.body events with data field
Optional fields: event (event type), id (event ID), retry (reconnect interval)
Connection stays open for streaming
SSE is unidirectional (server to client only)

See PAGI::SSE for higher-level SSE utilities.

2.6 Streaming Responses

You can stream HTTP response bodies by sending multiple http.response.body events:

use strict;
use warnings;
use Future::AsyncAwait;
use Future::IO;

async sub app {
    my ($scope, $receive, $send) = @_;

    die "Expected http scope" unless $scope->{type} eq 'http';

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

    # Send chunks over time
    for my $i (1..5) {
        await $send->({
            type => 'http.response.body',
            body => "Chunk $i\n",
            more => 1,  # More chunks coming
        });

        # Wait 1 second between chunks (loop-agnostic!)
        await Future::IO->sleep(1);
    }

    # Send final chunk (more => 0 is the default, so can be omitted)
    await $send->({
        type => 'http.response.body',
        body => "Done!\n",
    });
}

\&app;

Test it:

curl http://localhost:5000/

# Output (appears gradually):
# Chunk 1
# Chunk 2
# Chunk 3
# Chunk 4
# Chunk 5
# Done!

Key points:

Use transfer-encoding: chunked or omit content-length
Set more => 1 on all chunks except the last
Omit more on the final chunk (defaults to 0)
Useful for large files, real-time data, or progressive rendering

Streaming raises a question: what happens when you produce faster than the client can read? The server buffers the overflow, and PAGI lets you see and act on that backlog through $scope->{'pagi.transport'} -- the server-side analogue of the browser's WebSocket.bufferedAmount. buffered_amount reports the bytes queued but not yet on the wire; high_water_mark and low_water_mark bound the backpressure band; and the on_high_water/on_drain callbacks let an event-driven producer pause and resume. Use it to conflate a live feed -- skipping stale frames so a slow client stays current -- or to throttle a source you cannot pace by awaiting. The handle is optional: a server that cannot measure its buffer omits it, so guard for undef.

For a runnable demonstration see examples/13-flow-control, the Flow Control recipes in PAGI::Cookbook, and "Transport Flow Control" in PAGI::Spec::Www for the full interface.

2.7 Lifespan Protocol (Application Lifecycle)

The lifespan protocol allows your application to initialize resources on startup and clean them up on shutdown. The key feature is $scope->{state} - a hash for sharing resources (database pools, caches) from startup with every request in a worker process.

Each request scope receives a shallow copy of this hash: the values you store -- a database pool, a cache handle -- are shared by reference with every request, but the top-level keys are private to each copy. So store your shared resources once at startup and use them through their references; do not expect a top-level key you assign in a request (or reassign in the lifespan once requests are running) to be seen elsewhere. See "Lifespan State" in PAGI::Spec::Lifespan.

Important: In worker mode (--workers N), each worker runs lifespan independently after forking. This means each worker initializes its own database connections, cache handles, etc. This is actually good - most database connections can't be shared across forks anyway.

use strict;
use warnings;
use Future::AsyncAwait;

async sub app {
    my ($scope, $receive, $send) = @_;

    # Handle lifespan events (startup then shutdown - a fixed sequence)
    if ($scope->{type} eq 'lifespan') {
        my $state = $scope->{state};  # store resources here; shared by reference with every request

        # Wait for startup event
        my $event = await $receive->();

        if ($event->{type} eq 'lifespan.startup') {
            eval {
                # Store resources in $state - available to all requests
                $state->{db} = MyDB->connect('dbi:Pg:dbname=myapp');
                $state->{cache} = Cache::Memcached->new(servers => ['localhost:11211']);
                warn "Application started successfully\n";
                await $send->({ type => 'lifespan.startup.complete' });
            };
            if ($@) {
                await $send->({ type => 'lifespan.startup.failed', message => $@ });
                return;
            }
        }

        # Wait for shutdown event
        $event = await $receive->();

        if ($event->{type} eq 'lifespan.shutdown') {
            eval {
                $state->{db}->disconnect if $state->{db};
                $state->{cache}->disconnect_all if $state->{cache};
                warn "Application shut down successfully\n";
                await $send->({ type => 'lifespan.shutdown.complete' });
            };
            if ($@) {
                await $send->({ type => 'lifespan.shutdown.failed', message => $@ });
            }
        }

        return;
    }

    # Handle HTTP requests
    if ($scope->{type} eq 'http') {
        my $state = $scope->{state};  # shallow copy of lifespan state; $db comes through by reference
        my $db = $state->{db};

        my $data = $db->selectrow_hashref('SELECT * FROM users LIMIT 1');

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

        await $send->({
            type => 'http.response.body',
            body => "Database connected: " . (defined $data ? 'yes' : 'no'),
        });
    }
}

\&app;

Key points:

Lifespan events are sent to the same application entry point
Handle lifespan.startup to initialize resources (database, cache, etc.)
Handle lifespan.shutdown to clean up resources
Must respond with complete or failed for each event
PAGI::Endpoint::Router provides on_startup and on_shutdown callbacks to make this easier

Example using PAGI::Endpoint::Router:

use PAGI::Endpoint::Router;

my $db;

my $router = PAGI::Endpoint::Router->new(
    on_startup => async sub {
        my ($scope) = @_;
        $db = MyDB->connect('dbi:Pg:dbname=myapp');
        warn "Database connected\n";
    },
    on_shutdown => async sub {
        my ($scope) = @_;
        $db->disconnect;
        warn "Database disconnected\n";
    },
);

# ... define routes ...

$router->to_app;

2.8 UTF-8 Handling

PAGI follows specific rules for UTF-8 encoding/decoding:

Request Paths

$scope->{path}       # UTF-8 decoded string (use this for display/matching)
$scope->{raw_path}   # Raw bytes (preserves original encoding)

PAGI uses Mojolicious-style path decoding: percent-encoded bytes are first URL-decoded, then UTF-8 decoded. If UTF-8 decoding fails (invalid byte sequences), the original URL-decoded bytes are preserved as-is.

Example:

# URL: /users/%E4%B8%AD%E6%96%87
$scope->{path} = '/users/中文'                    # (decoded)
$scope->{raw_path} = '/users/%E4%B8%AD%E6%96%87'  # (raw bytes)

# Invalid UTF-8: /users/%FF%FE
$scope->{path} = '/users/\xFF\xFE'                # (falls back to bytes)
$scope->{raw_path} = '/users/%FF%FE'              # (raw bytes)

Query Strings

Query strings are raw bytes. Use URI to parse them properly:

use strict;
use warnings;
use Future::AsyncAwait;
use URI;
use Encode qw(encode_utf8);

async sub app {
    my ($scope, $receive, $send) = @_;

    die "Expected http scope" unless $scope->{type} eq 'http';

    # Use URI to parse query string (handles decoding automatically)
    my $uri = URI->new('?' . ($scope->{query_string} // ''));
    my %params = $uri->query_form;

    my $name = $params{name} // 'World';

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

    await $send->({
        type => 'http.response.body',
        body => encode_utf8("Hello, $name!"),
    });
}

\&app;

Request Bodies

Request bodies are always raw bytes:

my $event = await $receive->();
my $raw_bytes = $event->{body};  # Raw bytes

# If you know it's UTF-8 JSON:
use Encode qw(decode_utf8);
use JSON::MaybeXS;

my $text = decode_utf8($raw_bytes);
my $data = decode_json($text);

Response Bodies

Response bodies must be encoded to bytes:

use Encode qw(encode_utf8);

my $text = "Hello, 世界!";  # Perl string (characters)
my $bytes = encode_utf8($text);  # Bytes

await $send->({
    type => 'http.response.body',
    body => $bytes,  # Must be bytes, not characters
});

Complete UTF-8 Example

use strict;
use warnings;
use Future::AsyncAwait;
use Encode qw(encode_utf8 decode_utf8);
use URI::Encode qw(uri_decode);

async sub app {
    my ($scope, $receive, $send) = @_;

    die "Expected http scope" unless $scope->{type} eq 'http';

    # 1. Path is already decoded
    my $path = $scope->{path};  # UTF-8 string

    # 2. Query string needs decoding
    my $query = $scope->{query_string} // '';
    my ($key, $value) = split /=/, $query, 2;
    $value = decode_utf8(uri_decode($value // '')) if defined $value;

    # 3. Request body is raw bytes
    # NOTE: This loop does NOT block - await yields to event loop
    my $body_bytes = '';
    while (1) {
        my $event = await $receive->();
        $body_bytes .= $event->{body} if defined $event->{body};
        last unless $event->{more};
    }
    my $body_text = decode_utf8($body_bytes);  # Decode to string

    # 4. Build response (as string)
    my $response = "Path: $path\n";
    $response .= "Param: $value\n" if defined $value;
    $response .= "Body: $body_text\n" if length $body_text;

    # 5. Encode response to bytes
    my $response_bytes = encode_utf8($response);

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

    await $send->({
        type => 'http.response.body',
        body => $response_bytes,  # Bytes, not string
    });
}

\&app;

Using High-Level Helpers

PAGI::Request and PAGI::Response handle UTF-8 encoding/decoding automatically:

use PAGI::Request;
use PAGI::Response;

async sub app {
    my ($scope, $receive, $send) = @_;

    die "Expected http scope" unless $scope->{type} eq 'http';

    my $req = PAGI::Request->new($scope, $receive);
    my $res = PAGI::Response->new($scope, $send);

    # Path is already decoded
    my $path = $req->path;

    # Query params are automatically decoded
    my $name = $req->query_parameters->get('name') // 'World';

    # Body is automatically decoded (if content-type indicates UTF-8)
    my $body = await $req->body;

    # Response automatically encodes to UTF-8 bytes
    await $res->text("Hello, $name!");
}

\&app;

Key points:

$scope->{path} is decoded UTF-8; $scope->{raw_path} is bytes
Query strings and request bodies are raw bytes (decode them yourself)
Response bodies must be encoded to bytes before sending
Use Encode for explicit encoding/decoding
PAGI::Request and PAGI::Response handle this automatically

2.9 Async Patterns and Pitfalls

Understanding PAGI's async model is crucial to avoiding subtle bugs. This section covers common patterns and the most important pitfall to avoid.

The Completion Contract

Your app's returned Future signals "I'm done." When your async sub returns (its Future resolves), the server considers the response complete and may:

Close the connection
Write access logs
Handle the next request (keep-alive)

This means you must await all $send calls before your app returns.

The Most Common Mistake

This pattern looks reasonable but is broken:

# WRONG - DO NOT DO THIS
async sub app {
    my ($scope, $receive, $send) = @_;

    # Schedule work for later without awaiting...
    Future::IO->sleep(1)->then(sub {
        $send->({
            type    => 'http.response.start',
            status  => 200,
            headers => [['content-type', 'text/plain']],
        });
        $send->({
            type => 'http.response.body',
            body => 'Hello after 1 second',
        });
    })->retain;  # Keep the future alive

    return;  # App returns immediately!
}

What goes wrong:

1. App returns immediately (Future resolves)
2. Server thinks response is done (but nothing was sent!)
3. The sleep callback runs 1 second later
4. By then, the connection may be closed or reused
5. Result: empty response, corrupted response, or race condition

Why ->retain doesn't help: The retain method keeps the Future in memory, but the server doesn't know about it. The server only waits for your app's main Future - retained futures are invisible to it.

The Correct Pattern

Always await all response-affecting work:

# CORRECT - await the delay
async sub app {
    my ($scope, $receive, $send) = @_;

    # Wait for the delay
    await Future::IO->sleep(1);

    # Now send response (still within the app's Future)
    await $send->({
        type    => 'http.response.start',
        status  => 200,
        headers => [['content-type', 'text/plain']],
    });

    await $send->({
        type => 'http.response.body',
        body => 'Hello after 1 second',
    });
}

Detecting This Problem

PAGI::Test::Client will die with a clear error:

App returned without sending response. Did you forget to 'await' your $send calls?

PAGI::Middleware::Lint will warn (or die in strict mode):

HTTP app completed without sending http.response.start. This usually means
you forgot to 'await' your $send calls, or used ->retain for response-affecting work.

Enable Lint during development:

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'Lint', strict => 1;  # Die on violations
    $my_app;
};

The Future Tree Mental Model

Think of your app's Futures as a tree:

App Future (root)
├── await $send->({ response.start })
├── await $some_async_operation()
│   └── await $send->({ response.body })
└── (app returns when tree is complete)

Everything in the tree is awaited. The server waits for the root Future.

When you use ->retain, you're creating a detached Future outside the tree:

App Future (root)          Detached (invisible to server!)
└── (returns immediately)   └── delay_future->then($send)

The server only sees the tree. Detached futures are orphaned.

A Scope Key Set in Middleware "Vanishes"

If you set a plain value on $scope in one middleware and try to read it in another, you may find it missing. Middleware clone the scope before modifying it, and the clone is shallow: a top-level scalar set in one layer does not propagate to the others. To share per-request state across layers on purpose, mutate through a reference (or use the stash) rather than setting a top-level scalar. The full model -- and why it works this way -- is in "Scope is cloned per layer, not shared" in PAGI::Building.

Summary

Always await $send calls and any async work that affects the response
Never use ->retain for response-affecting work
Use Lint middleware to catch mistakes early
->retain is only safe after the response is completely sent

BEYOND THE PROTOCOL: OPTIONAL CONVENIENCES

Everything above is the PAGI protocol: the complete contract between an async application and an async server. You can build any PAGI application with nothing more than what you have seen here: an async sub, $scope, $receive, $send, and Future::AsyncAwait.

The PAGI-Tools distribution provides optional convenience helpers on top of the protocol: middleware (logging, sessions, CORS, compression, and more), request and response sugar (PAGI::Request, PAGI::Response), WebSocket and SSE helpers, routers, and ready-made applications. None of it is required; it exists to save boilerplate when you want it. Every piece is an ordinary PAGI application or a plain wrapper around the $scope/$receive/$send protocol, so you can read, replace, or ignore any of it.

For a guide to those helpers, see PAGI::Tools::Tutorial.

PART 3: REFERENCE

3.1 Scope Reference

The $scope hashref contains connection metadata:

Async Operations Without Loop Access

For async operations like delays, use Future::IO which is loop-agnostic:

use Future::IO;
await Future::IO->sleep(5);  # Works with any event loop

This keeps your application code portable across different PAGI server implementations.

Common Fields (All Types)

$scope->{type}         # 'http', 'websocket', 'sse', 'lifespan'

HTTP Scope

$scope->{type}         # 'http'
$scope->{method}       # 'GET', 'POST', etc.
$scope->{path}         # URL path (decoded UTF-8)
$scope->{raw_path}     # URL path (raw bytes)
$scope->{query_string} # Query string (raw bytes)
$scope->{headers}      # Arrayref of [name, value] pairs
$scope->{scheme}       # 'http' or 'https'
$scope->{http_version} # '1.0' or '1.1'
$scope->{client}       # [ip, port] of client
$scope->{server}       # [ip, port] of server

WebSocket Scope

$scope->{type}         # 'websocket'
$scope->{path}         # URL path
$scope->{query_string} # Query string
$scope->{headers}      # Request headers
$scope->{subprotocols} # Arrayref of requested subprotocols
$scope->{client}       # [ip, port] of client

SSE Scope

$scope->{type}         # 'sse'
$scope->{path}         # URL path
$scope->{query_string} # Query string
$scope->{headers}      # Request headers
$scope->{client}       # [ip, port] of client

Lifespan Scope

$scope->{type}         # 'lifespan'

3.2 Event Reference

HTTP Events

Receive:

{ type => 'http.request', body => $bytes, more => 1 }
{ type => 'http.disconnect' }

Send:

{ type => 'http.response.start', status => 200, headers => [...] }
{ type => 'http.response.body', body => $bytes, more => 0 }

WebSocket Events

Receive:

{ type => 'websocket.connect' }
{ type => 'websocket.receive', text => $text }
{ type => 'websocket.receive', bytes => $bytes }
{ type => 'websocket.disconnect', code => 1000, reason => '' }

Send:

{ type => 'websocket.accept', subprotocol => 'optional' }
{ type => 'websocket.send', text => $text }
{ type => 'websocket.send', bytes => $bytes }
{ type => 'websocket.close', code => 1000, reason => '' }

SSE Events

Receive:

{ type => 'sse.connect' }
{ type => 'sse.disconnect' }

Send:

{ type => 'sse.response.start', status => 200, headers => [...] }
{ type => 'sse.response.body', data => $text, event => 'name', id => '1' }

Lifespan Events

Receive:

{ type => 'lifespan.startup' }
{ type => 'lifespan.shutdown' }

Send:

{ type => 'lifespan.startup.complete' }
{ type => 'lifespan.startup.failed', message => $error }
{ type => 'lifespan.shutdown.complete' }
{ type => 'lifespan.shutdown.failed', message => $error }

NEXT STEPS

You've covered the PAGI protocol! For more information:

PAGI::Cookbook - Worked, runnable recipes for each protocol feature
PAGI::PSGI - if you're coming from PSGI
PAGI::Building - if you're building a framework on PAGI
Browse examples/ for complete working applications, including a small web framework built on PAGI
Read the specification: PAGI::Spec and the protocol documents PAGI::Spec::Www, PAGI::Spec::Lifespan, PAGI::Spec::Server.
PAGI::Tools::Tutorial - Guide to the optional convenience helpers (middleware, routers, request/response sugar, ready-made apps)

AUTHOR

PAGI Contributors

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install PAGI, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PAGI

CPAN shell

perl -MCPAN -e shell
install PAGI

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

PART 1: GETTING STARTED

1.1 Introduction

What is PAGI?

Why Async?

PAGI vs PSGI

Prerequisites

1.2 Installation

About pagi-server

1.3 Your First PAGI App

Environment Modes

Inspecting the Scope

1.4 Understanding the Event Loop: Blocking vs Non-Blocking

The Event Loop

Non-Blocking Operations (GOOD)

Blocking Operations (BAD)

Why Blocking is Bad

Solutions for Blocking Operations

1.5 Worker Mode

Single Process vs Worker Mode

When to Use Worker Mode

Running with Workers

Worker Isolation

Wrong: Shared State in Memory

Right: External State Storage

PART 2: UNDERSTANDING RAW PAGI

2.1 The Three Arguments

$scope - Connection Metadata

$receive - Receiving Client Events

$send - Sending Events to Client

2.2 Scope Types

http - Standard HTTP Requests

websocket - WebSocket Connections

sse - Server-Sent Events

lifespan - Application Lifecycle Events

2.3 HTTP Request/Response Cycle (Raw)

2.4 WebSocket (Raw)

2.5 SSE (Raw)

2.6 Streaming Responses

2.7 Lifespan Protocol (Application Lifecycle)

2.8 UTF-8 Handling

Request Paths

Query Strings

Request Bodies

Response Bodies

Complete UTF-8 Example

Using High-Level Helpers

2.9 Async Patterns and Pitfalls

The Completion Contract

The Most Common Mistake

The Correct Pattern

Detecting This Problem

The Future Tree Mental Model

A Scope Key Set in Middleware "Vanishes"

Summary

BEYOND THE PROTOCOL: OPTIONAL CONVENIENCES

PART 3: REFERENCE

3.1 Scope Reference

Async Operations Without Loop Access

Common Fields (All Types)

HTTP Scope

WebSocket Scope

SSE Scope

Lifespan Scope

3.2 Event Reference

HTTP Events

WebSocket Events

SSE Events

Lifespan Events

NEXT STEPS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

Keyboard Shortcuts