NAME

PSGI::Extensions - PSGI extensions

SPECIFICATION

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 "read" from "psgi.input" without worrying about non-blocking I/O and then can call "seek" to 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: "level" and "message" where "level" MUST be one of the following strings: "debug", "info", "warn", "error" and "fatal". "message" SHOULD 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.

• "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 $env as 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.