From 673c23168492c3a2859ea6aa7184f0a80bdc1d8f Mon Sep 17 00:00:00 2001
From: ldayananda <ldayananda@users.noreply.github.com>
Date: Tue, 23 Jan 2018 15:36:49 -0500
Subject: [PATCH] docs: add middleware guide (#4877)

* adding guide content

* fix link

* CR comments

* fixing a typo

* fixing example
---
 docs/guides/middleware.md | 74 +++++++++++++++++++++++++++++++++++++++
 src/js/tech/middleware.js |  2 +-
 2 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/middleware.md

diff --git a/docs/guides/middleware.md b/docs/guides/middleware.md
new file mode 100644
index 0000000000..0e82d8aa50
--- /dev/null
+++ b/docs/guides/middleware.md
@@ -0,0 +1,74 @@
+# Middleware
+
+Middleware is a Video.js feature that allows interaction with and modification of how the `Player` and `Tech` talk to each other. For more in-depth information, check out our [feature spotlight](http://blog.videojs.com/feature-spotlight-middleware/).
+
+## Table of Contents
+
+* [Understanding Middleware](#understanding-middleware)
+* [Using Middleware](#using-middleware)
+* [setSource](#setsource)
+
+## Understanding Middleware
+
+Middleware are functions that return an object with methods matching those on the `Tech`. There are currently a limited set of allowed methods that will be understood by middleware. These are: `buffered`, `currentTime`, `setCurrentTime`, `duration`, `seekable` and `played`.
+
+These allowed methods are split into two categories: `getters` and `setters`. Setters will be called on the `Player` first and run through middleware(from left to right) before calling the method, with its arguments, on the `Tech`. Getters are called on the `Tech` first and are run though middleware(from right to left) before returning the result to the `Player`.
+
+```
++----------+                      +----------+
+|          |  setter middleware   |          |
+|          +---------------------->          |
+|  Player  |                      |   Tech   |
+|          <----------------------+          |
+|          |  getter middleware   |          |
++----------+                      +----------+
+```
+
+## Using Middleware
+
+Middleware are registered to a video MIME type, and will be run for any source with that type.
+
+```javascript
+videojs.use('video/mp4', myMiddleware);
+```
+
+You can also register a middleware on all sources by registering it on `*`.
+
+```javascript
+videojs.use('*', myMiddleware);
+```
+
+Your middleware should be a function that takes a player as an argument and returns an object with methods on it like below:
+
+```javascript
+var myMiddleware = function(player) {
+  return {
+    currentTime: function(ct) {
+      return ct / 2;
+    },
+    setCurrentTime: function(time) {
+      return time * 2;
+    },
+    ...
+  };
+};
+
+videojs.use('*', myMiddleware);
+```
+
+
+## setSource
+
+`setSource` is a required method for all middleware and must be included in the returned object. If your middlware is not manipulating or rejecting the source, you can pass along the source by doing the following:
+
+```javascript
+videojs.use('*', function(player) {
+  return {
+    setSource: function(srcObj, next) {
+      // pass null as the first argument to indicate that the source is not rejected
+      next(null, srcObj);
+    }
+  };
+});
+```
+
diff --git a/src/js/tech/middleware.js b/src/js/tech/middleware.js
index 8cf901b424..d6f0fa3c3f 100644
--- a/src/js/tech/middleware.js
+++ b/src/js/tech/middleware.js
@@ -76,7 +76,7 @@ function setSourceHelper(src = {}, middleware = [], next, player, acc = [], last
       // we've succeeded, now we need to go deeper
       acc.push(mw);
 
-      // if it's the same time, continue does the current chain
+      // if it's the same type, continue down the current chain
       // otherwise, we want to go down the new chain
       setSourceHelper(_src,
           src.type === _src.type ? mwrest : middlewares[_src.type],