From 5e8618ec3b694575b61030d02f29a3b3054493dc Mon Sep 17 00:00:00 2001
From: Thiago de Arruda <tpadilha84@gmail.com>
Date: Fri, 10 Nov 2017 13:21:09 -0300
Subject: [PATCH] Add documentation for {intercept,register}StreamProtocol.

---
 docs/api/protocol.md                          | 79 +++++++++++++++++++
 .../structures/stream-protocol-response.md    |  5 ++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/api/structures/stream-protocol-response.md

diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index 485f14bd20..bf4f8f6455 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -194,6 +194,67 @@ request to have a different session you should set `session` to `null`.
 
 For POST requests the `uploadData` object must be provided.
 
+### `protocol.registerStreamProtocol(scheme, handler[, completion])`
+
+* `scheme` String
+* `handler` Function
+  * `request` Object
+    * `url` String
+    * `headers` Object
+    * `referrer` String
+    * `method` String
+    * `uploadData` [UploadData[]](structures/upload-data.md)
+  * `callback` Function
+    * `stream` (ReadableStream | [StreamProtocolResponse](structures/stream-protocol-response.md)) (optional)
+* `completion` Function (optional)
+  * `error` Error
+
+Registers a protocol of `scheme` that will send a `Readable` as a response.
+
+The usage is similar to the other `register{Any}Protocol`, except that the
+`callback` should be called with either a `Readable` object or an object that
+has the `data`, `statusCode`, and `headers` properties.
+
+Example:
+
+```javascript
+const {protocol} = require('electron')
+const {PassThrough} = require('stream')
+
+function createStream (text) {
+  const rv = new PassThrough()  // PassThrough is also a Readable stream
+  rv.push(text)
+  rv.push(null)
+  return rv
+}
+
+protocol.registerStreamProtocol('atom', (request, callback) => {
+  callback({
+    statusCode: 200,
+    headers: {
+      'content-type': 'text/html'
+    },
+    data: createStream('<h5>Response</h5>')
+  })
+}, (error) => {
+  if (error) console.error('Failed to register protocol')
+})
+```
+
+It is possible to pass any object that implements the readable stream API (emits
+`data`/`end`/`error` events). For example, here's how a file could be returned:
+
+```javascript
+const {protocol} = require('electron')
+const fs = require('fs')
+
+protocol.registerStreamProtocol('atom', (request, callback) => {
+  callback(fs.createReadStream('index.html'))
+}, (error) => {
+  if (error) console.error('Failed to register protocol')
+})
+```
+
 ### `protocol.unregisterProtocol(scheme[, completion])`
 
 * `scheme` String
@@ -285,6 +346,24 @@ which sends a `Buffer` as a response.
 Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
 which sends a new HTTP request as a response.
 
+### `protocol.interceptStreamProtocol(scheme, handler[, completion])`
+
+* `scheme` String
+* `handler` Function
+  * `request` Object
+    * `url` String
+    * `headers` Object
+    * `referrer` String
+    * `method` String
+    * `uploadData` [UploadData[]](structures/upload-data.md)
+  * `callback` Function
+    * `stream` (ReadableStream | [StreamProtocolResponse](structures/stream-protocol-response.md)) (optional)
+* `completion` Function (optional)
+  * `error` Error
+
+Same as `protocol.registerStreamProtocol`, except that it replaces an existing
+protocol handler.
+
 ### `protocol.uninterceptProtocol(scheme[, completion])`
 
 * `scheme` String
diff --git a/docs/api/structures/stream-protocol-response.md b/docs/api/structures/stream-protocol-response.md
new file mode 100644
index 0000000000..64847075a0
--- /dev/null
+++ b/docs/api/structures/stream-protocol-response.md
@@ -0,0 +1,5 @@
+# StreamProtocolResponse Object
+
+* `statusCode` Number - The HTTP response code
+* `headers` Object - An object containing the response headers
+* `data` ReadableStream - A Node.js readable stream representing the response body