JSGI Extension Proposal - Evented Streaming JSGI
Reference Implementation: http://github.com/isaacs/ejsgi
Simplify the input, error, and response body objects to a single non-blocking data stream class.
Support reading the input request and writing the response body without ever having to hold the entire body in memory.
Changes from JSGI 0.3
urlmember to the request object, which is the requested URL exactly as it appears on the first line of the HTTP request.
request.inputMUST be a Stream object.
response.bodyMUST be a Stream object.
request.jsgi.errorMUST be a Stream object.
request.jsgi.streamMUST be a reference to the Stream implementation.
Stream Objects are representations of a stream of data in an asynchronous evented paradigm.
Stream Objects have the following methods:
- write - Send data down the stream. If the stream is closed, then throw an Error. This must not actually perform the write until after the current scope of execution is completed. The order of written data MUST be consistent with the order in which
- close - Close the stream. Once closed, no more data may be written to the Stream.
- pause - Temporarily prevent the firing of
dataevents. This is useful when a reader needs to throttle a stream of incoming data.
- resume - Resume a paused thread, so that
dataevents will begin firing again.
- addListener - Attach an event handler to an event. The first argument is the event name, and the second is the callback.
Stream Objects emit the following events
- data - All the data that is passed through
writeeventually triggers a
dataevent. The argument is the data that was written.
- eof - Emitted when all data has been written, and the stream is closed.
- drain - Emitted when the internal buffer empties.
- pause - Emitted when the stream is paused with the
- resume - Emitted when the stream is resumed with the
Stream objects MUST implement some sort of “event queue” in order to defer callbacks until after the current execution context has exited. Specifically, the
drain events MUST NOT be fired immediately after the corresponding calls to
All streams SHOULD be both readable and writeable. This allows for middleware to step into the flow and filter the input or output to/from an app.
For the purposes of this spec, “compliant” applications are applications that return a stream as the response body.
However, non-streaming JSGI applications can easily be supported using a middleware adapter. See the
string-to-stream.js examples included in the reference implementation.