# Extensions

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

## 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 in this file 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 `$send`/`$receive`.
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.
