/ 
PAGI-0.002000
/ PAGI::Spec::Extensions

NAME

PAGI::Spec::Extensions - The PAGI server extension mechanism

Extensions

Version: 0.3 (Draft)

The PAGI specification provides for server-specific extensions to be used outside of the core PAGI specification. This document records the extension mechanism and shared extensions so servers and applications can interoperate without private agreements.

Each extension is advertised by the server and may add keys to the connection scope and define new event types. The TLS extension is a fully specified example with its own document.

Declaring Extensions

-

Servers advertise extensions in scope->{extensions}. Each key must be a lower-case identifier (e.g., fullflush, tls).

-

Extension values are hashrefs whose contents are defined by the extension author. Use permitted data types from the core spec.

-

Applications must check for the presence of an extension before sending any extension-specific events.

When contributing a new extension, document it with:

  1. Name & Purpose -- what problem it solves.

  2. Scope Additions -- keys added to scope->{extensions}{$name} or other metadata.

  3. Events -- new type values that may flow through $receive/$send.

  4. Compatibility -- how clients should behave if the server omits the extension.

Example: fullflush

Some HTTP servers expose a fullflush capability that immediately flushes buffered bytes to the client (useful for server-sent events or debugging).

-

Scope: servers set scope->{extensions}{fullflush} = {} to indicate support.

-

Event: applications may send { type => 'http.fullflush' } to force a flush. Servers that do not advertise the extension must reject the event with an error.

Additional extensions (tracing hooks, background task controls, etc.) should follow the same pattern.

Defined extensions

The PAGI specification defines these extensions. A server advertises the ones it supports in scope->{extensions}; an application checks for a key's presence before relying on it.

-

fullflush -- force-flush buffered output to the client (described above).

-

tls -- metadata about a TLS connection (PEM certificates, negotiated version, cipher suite). See PAGI::Spec::Tls.

-

websocket.http.response -- reject a WebSocket handshake with a custom HTTP response (status, headers, body) instead of a bare 403 Forbidden. See "WebSocket Denial Response (extension)" in PAGI::Spec::Www.

(The pagi.connection and pagi.transport introspection handles are pagi.* scope keys rather than extensions entries; see PAGI::Spec::Www.)

Defining your own events

The mechanism above is how a server advertises a capability. A framework or application can also introduce its own events, at two different cost levels:

-

New event types within a scope (like http.fullflush), or new scope types entirely (a protocol beyond http/websocket/sse), require a cooperating server -- the server has to produce or accept those events. Use a namespaced type (for example myproto.message) and document it as an extension so other servers and applications can interoperate.

-

Your own asynchronous events -- a timer firing, a background job finishing, a message arriving on an external queue -- require no server cooperation and no protocol changes. You model them as Futures and compose them with the protocol's events using ordinary Future combinators. This is what makes PAGI's model loop-agnostic: a handler can wait on its own event sources alongside $receive, and the same code runs under any conforming server.

use Future;

# Whichever resolves first wins (the loser is cancelled): the next client
# message, or our own event -- a job-completion Future from elsewhere in
# the program.
my $next = await Future->wait_any( $receive->(), $job_done );

See PAGI::Building for using this to build event-driven layers on PAGI.

Version History

-

0.3 (Draft): Added the "Defined extensions" registry (tls, websocket.http.response) and the pagi.connection/pagi.transport clarification note.

-

0.2 (Draft): Initial extensions-mechanism documentation.

SEE ALSO

-

PAGI::Spec -- the base specification

-

PAGI::Spec::Tls -- the TLS extension, a fully specified example