/ 
PAGI-0.002002
/ PAGI::Spec::Server

NAME

PAGI::Spec::Server - PAGI server and application-runner integration guidance

PAGI Server and Application-Runner Integration

Version: 0.2 (Draft)

The main specification, PAGI::Spec, defines the runtime boundary between a PAGI server and application. This document clarifies how deployment tooling reaches that boundary without prescribing a Perl object model for servers.

Runtime Boundary

A PAGI server invokes a normalized PAGI application code reference and speaks the scopes and events defined by the PAGI protocol specifications. Conformance is determined by that runtime behaviour, not by how the server is constructed or started.

A server may be exposed as a class, a function, an embedded service, an external process, or another implementation-specific interface. PAGI does not require a new constructor, a app constructor option, a run method, or any particular event-loop ownership model.

Application Loading and Normalization

The canonical runtime application is always a code reference accepting ($scope, $receive, $send) and returning a Future. As described in "Application Providers and Loading" in PAGI::Spec, a general-purpose application runner SHOULD also accept an already-instantiated application-provider object implementing to_app.

When given a provider object, the runner MUST call to_app exactly once per loaded provider instance, verify that it returned a code reference, and pass only that normalized code reference across the server/application boundary. Provider construction failures and invalid to_app return values are loading errors; they MUST be reported before the runner starts serving traffic. A native code reference takes precedence over provider-method detection, even if that code reference is blessed.

A package-name string is not an application-provider object, and this convention does not permit invoking to_app as a class method. A runner MAY accept module or class names through its implementation-specific discovery interface, but that discovery step must produce an instantiated provider object or a native PAGI code reference before normalization begins.

Server Construction

The mechanism by which a runner configures and starts a server is an API of that runner and server implementation, not part of PAGI conformance. A runner may offer server-class selection, constructor options, command-line switches, or plugin contracts, but other conforming runners and servers need not use the same conventions.

For example, PAGI::Server::Runner currently constructs the reference PAGI::Server and offers a -s CLASS extension point. Those interfaces are documented by the PAGI-Server distribution; they are not required of every PAGI server.

Runner Guidance

A general-purpose runner should keep loading and runtime responsibilities separate:

-

discover and construct the configured application or provider;

-

normalize a provider through to_app before using it for connection dispatch;

-

configure and start the selected server through its implementation-specific API; and

-

use only the normalized application code reference for per-connection dispatch.

Loading errors should identify whether discovery, provider construction, to_app, or return-value validation failed.

Portability

A native PAGI application code reference is portable across conforming PAGI servers and runners. An application-provider object is portable across runners that adopt the to_app loading convention. Whether one server implementation can be selected as a drop-in replacement for another depends on the runner's plugin API and is not guaranteed by the PAGI runtime specification.

Version History

-

0.2 (Draft): Removed the prescribed new(app => ...) and run server-class contract. Clarified the separation between the runtime PAGI application, one-time application-provider normalization, and implementation-specific server construction.

-

0.1 (Draft): Initial server runner contract specification

This document has been placed in the public domain.