=encoding UTF-8

=head1 NAME

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

=head1 PAGI Server and Application-Runner Integration

B<Version>: 0.2 (Draft)

The main specification, L<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.

=head2 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 C<new> constructor, a C<app> constructor option, a C<run> method, or
any particular event-loop ownership model.

=head2 Application Loading and Normalization

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

When given a provider object, the runner MUST call C<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 C<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 C<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.

=head2 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, L<PAGI::Server::Runner> currently constructs the reference
L<PAGI::Server> and offers a C<-s CLASS> extension point. Those interfaces are
documented by the C<PAGI-Server> distribution; they are not required of every
PAGI server.

=head2 Runner Guidance

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

=over

=item -

discover and construct the configured application or provider;

=item -

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

=item -

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

=item -

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

=back

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

=head2 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 C<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.

=head2 Version History

=over

=item -

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

=item -

0.1 (Draft): Initial server runner contract specification

=back

=head2 Copyright

This document has been placed in the public domain.
