=head1 NAME

PSGI::Extensions - PSGI extentions

=head1 SPECIFICATION

The PSGI environment B<MAY> include the following additional
extensions. They are B<OPTIONAL> and applications and middleware
components B<SHOULD> check if they exist in the environment before
using the functionality provided.

=over 4

=item *

C<psgix.io>: The raw IO socket to access the client connection to do
low-level socket operations. This is only available in PSGI servers
that run as an HTTP server, and should be used when (and only when)
you want to I<jailbreak> out of PSGI abstraction, to implement
protocols over HTTP such as BOSH or WebSocket.

=item *

C<psgix.input.buffered>: A boolean which is true if the HTTP request
body (for POST or PUT requests) is buffered using a temporary
filehandle or PerlIO in C<psgi.input>. When this is set, applications
or middleware components can safely C<read> from C<psgi.input> without
worrying about non-blocking I/O and then can call C<seek> to rewind
the input for the transparent access.

=item *

C<psgix.logger>: A code reference to log messages. The code reference
is passed one argument as a hash reference that represents a message
to be logged. The hash reference B<MUST> include at least two keys:
C<level> and C<message> where C<level> B<MUST> be one of the following
strings: C<debug>, C<warn>, C<info>, C<error> and C<fatal>. C<message>
B<SHOULD> be a plain string or a scalar variable that stringifies.

=item *

C<psgix.session>: A hash reference for storing and retrieving session
data. Updates made on this hash reference B<SHOULD> be persisted by
middleware components and B<SHOULD> be restored in the succeeding
requests. How to persist and restore session data, as well as how to
identify the requesting clients are implementation specific.

C<psgix.session.options>: A hash reference to tell Middleware
components how to manipulate session data after the request.
Acceptable keys and values are implementation specific.

=item *

C<psgix.harakiri>: A boolean which is true if the PSGI server supports
harakiri mode, that kills a worker (typically a forked child process)
after the current request is complete.

C<psgix.harakiri.commit>: A boolean which is set to true by the PSGI
application or middleware when it wants the server to kill the worker
after the current request.

=back

=head1 COPYRIGHT AND LICENSE

Copyright Tatsuhiko Miyagawa, 2009-2011.

This document is licensed under the Creative Commons license by-sa.

=cut
