View source for JSGI/ForEachStreaming

<h1>JSGI Streaming Body Using forEach</h1>

<h2 id="status_proposed">Status: Proposed</h2>

<p>
Reference Implementation: http://github.com/kriszyp/jsgi-node</p>

<h2 id="rationale">Rationale</h2>

<p>KISS - Make it as simple as possible to return a response.</p>

<p>Read request input and write to the response body without buffering data without requiring extra effort on the part of the programmer.</p>

<p>Consistency between synchronous and asynchronous streaming of the body with backwards compatibility with JSGI 0.3.</p>

<p>Consistency with the API on how asynchronous actions are modeled, keeping in mind that in JSGI, response status and headers are asynchronously provided using promises.</p>

<h2 id="changes_from_jsgi_03">Addition JSGI 0.3</h2>

<ul>
<li>add <code>url</code> member to the request object, which is the requested URL exactly as it appears on the first line of the HTTP request.</li>
<li><code>request.body</code> MUST be a forEach-able Stream object.</li>
<li><code>response.body</code> MUST be a forEach-able Stream object.</li>
<li><code>request.jsgi.error</code> MUST be a forEach-able Stream object.</li>
</ul>

<h3 id="stream_objects">Stream Objects</h3>

<p>forEach-able Stream Objects are representations of a stream of data.</p>

<h4 id="methods">Methods</h4>

<p>forEach-able Stream Objects have the following method:</p>

<ul>
<li><strong>forEach(write)</strong> - When the stream can be written to, this will be called. The first parameter, write, MUST be a function. The forEach function can call the write function to write strings to the stream. The stream will be closed when forEach returns with any value that does not have a then() function, or if it returns a then() function (a promise), then() should be called with a callback that can be called when the stream is finished.

Each time the write callback is called, it may optionally also return a promise with a then() function if wishes to indicate that it has not yet completed handling processing the data. Once the data consumer is ready to continue receiving data, it call the callbacks to indicate that the forEach should continue. This allows for throttling of data.
</li>
</ul>
<h4 id="methods">Properties</h4>
<ul>
<li><strong>charset</strong> - This property can be set to the desired charset to use for encoding or decoding strings.</li>
</ul>

<h4 id="examples">Examples</h4>
Simple sync app:
<pre>
app = function(request){
  return {
    status: 200,
    headers: {},
    body: ["hello", "world"]
  }
};
</pre>
Streaming app, this could be sync or async, as along as "data" is a forEach-able source data structure:
<pre>
app = function(request){
  return {
    status: 200,
    headers: {},
    body: {
      forEach: function(write){
        return data.forEach(function(item){
          return serialize(item);
        })
      }
    }
  }
};
</pre>

Reading input:
<pre>
app = function(request){
  var file = new File("fileToSave");
  var fileUpload = request.body.forEach(function(data){
    file.write(data);
  }).then(file.close);

  return fileUpload.then(function(){
    return {
      status: 200,
      headers: {},
      body: ["file successfully uploaded"]
    };
  };
};
</pre>
Streaming app, where the source is an event emitter:
<pre>
app = function(request){
  return {
    status: 200,
    headers: {},
    body: {
      forEach: function(write){
        var promise = new Promise();
        someEventSource.addListener("data", function(data){ write(data); });
        someEventSource.addListener("finished", function(data){ promise.resolve() });
        return promise;
      }
    }
  }
};
</pre>

Middleware:
<pre>
MiddleWare = function(nextApp){
  return function(request){
    var response = nextApp(request);
    var inBody = response.body;
    response.body = {
      forEach: function(write){
        return inBody.forEach(function(block){
          return modify(block);
        })
      }
    }
    return response;
  }
};
</pre>