Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: ee99fc900f
Fetching contributors…

Cannot retrieve contributors at this time

112 lines (81 sloc) 4.17 KB


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.

  • 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.

  • Cleanup handlers

    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 10 in 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 $env is destroyed.

    A CGI handler could run the callbacks after closing STDOUT, mod_perl handlers can use PerlCleanupHandlers mechanism.

    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 Tatsuhiko Miyagawa, 2009-2011.

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

Jump to Line
Something went wrong with that request. Please try again.