view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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

### Running programmatically

You can also drive `PAGI::Server` directly from your own event loop:

```perl
use IO::Async::Loop;
use PAGI::Server;
use MyApp::Root;

# If you use Future::IO-based libraries, load this BEFORE them:
use Future::IO::Impl::IOAsync;

my $loop   = IO::Async::Loop->new;
my $server = PAGI::Server->new(
    # A native coderef or an instantiated object with to_app.
    app  => MyApp::Root->new,
    host => '127.0.0.1',
    port => 5000,
);

$loop->add($server);
$server->listen->get;  # start accepting connections
```

When passed a provider object directly, `PAGI::Server` calls `to_app` exactly
once during construction and stores only the resulting coderef.
Package-name strings are not providers; instantiate the class first.

## Command-line usage

```
pagi-server [options] [app] [key=value ...]

# Serve a PAGI app file
pagi-server ./app.pl

# Multi-worker, custom port
pagi-server --workers 4 --port 8080 ./app.pl

# Development mode (auto-enables Lint middleware when PAGI-Tools is installed)
pagi-server -E development ./app.pl

# HTTPS
pagi-server --ssl-cert cert.pem --ssl-key key.pem ./app.pl

# HTTP/2 over TLS (experimental)
pagi-server --http2 --ssl-cert cert.pem --ssl-key key.pem ./app.pl
```

Run `perldoc pagi-server` for the full list of options (workers, timeouts,
limits, watermarks, TLS, listeners, and more).

## Examples

The [`examples/`](examples/) directory contains progressively more advanced,
runnable applications — minimal HTTP, streaming with disconnect handling,
request-body draining, a WebSocket echo server, an SSE broadcaster,
lifespan/shared-state, extension-aware streaming, TLS introspection, a job
runner, UTF-8 handling, and a backpressure test harness. Each has its own
`README.md`. Start with [`examples/01-hello-http`](examples/01-hello-http/).

## Documentation

- [`PAGI::Server`](lib/PAGI/Server.pm) — the server class, constructor options,
  and operational notes (`perldoc PAGI::Server`).
- [`pagi-server`](bin/pagi-server) — the command-line launcher
  (`perldoc pagi-server`).
- [`PAGI::Server::Runner`](lib/PAGI/Server/Runner.pm) — application loading and
  server orchestration.
- [`PAGI::Server::Compliance`](lib/PAGI/Server/Compliance.pod) — HTTP/WebSocket
  compliance and the built-in security defenses.
- [`Changes`](Changes) — release history.
- [`SECURITY.md`](SECURITY.md) — how to report security issues.

## Relationship to PAGI and PAGI-Tools

PAGI-Server has **no runtime dependency** on other PAGI distributions — the
application runner (`PAGI::Server::Runner`) ships here. The framework-level
toolkit (routers, endpoints, middleware such as `PAGI::Middleware::Lint`, and
the `PAGI::App::*` apps) lives in the separate **PAGI-Tools** distribution and
is used only when present. The specification itself lives in the
[**PAGI**](https://github.com/jjn1056/pagi) distribution.

This distribution was split out of the PAGI distribution; its git history is
preserved from the [original repository](https://github.com/jjn1056/pagi).

## License

Copyright (C) John Napiorkowski.

This library is free software; you can redistribute it and/or modify it under
the terms of the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).