PSGI::Extensions - PSGI extensions
The PSGI environment MAY include the following additional extensions. They are OPTIONAL and applications and middleware components SHOULD check if they exist in the environment before using the functionality provided.
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 jailbreak out of PSGI abstraction, to implement protocols over HTTP such as BOSH or WebSocket.
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
psgi.input. When this is set, applications or middleware components can safely
psgi.inputwithout worrying about non-blocking I/O and then can call
seekto rewind the input for the transparent access.
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 MUST include at least two keys:
levelMUST be one of the following strings:
messageSHOULD be a plain string or a scalar variable that stringifies.
psgix.session: A hash reference for storing and retrieving session data. Updates made on this hash reference SHOULD be persisted by middleware components and 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.
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.
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.
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.
Some servers such as Apache support an execution phase that happens after all content has been sent to the client and the connection has been closed. These should only be set if the server supports such a mode of execution that the client doesn't have to wait on, e.g. you could
sleep 10in a cleanup handler but return a response to the client in 10ms.
This can be used e.g. to close database connections, set keys in a cache whose values were generated during the request, send a logging event describing the request etc. It can even be used as a poor man's job queue (for e.g. resizing and converting uploaded images).
For most servers the implementation is straightforward, calling the callbacks once a request is complete but before
A CGI handler could run the callbacks after closing
STDOUT, mod_perl handlers can use
psgix.cleanup- A boolean flag indicating whether a PSGI server supports cleanup handlers. Absence of the key assumes false (i.e. unsupported). Middleware and applications MUST check this key before utilizing the cleanup handlers.
psgix.cleanup.handlers- Array reference to stack callback handlers. This reference MUST be initialized as an empty array reference by the servers. Applications can register the callbacks by simply push()ing a code reference to this array reference. Callbacks will be called once a request is complete, and will receive
$envas its first argument, and return value of the callbacks will be simply ignored. An exception thrown inside callbacks MAY also be ignored.
If the server also supports
psgix.harakiri, it SHOULD implement in a way that cleanup handlers run before harakiri checker, so that the cleanup handlers can commit the harakiri flag.
COPYRIGHT AND LICENSE
Copyright Tatsuhiko Miyagawa, 2009-2011.
This document is licensed under the Creative Commons license by-sa.