Merge pull request #1021 from github/response-middleware

Response middleware

Author: Ben Lavender

docs/scripting.md

@@ -645,22 +645,18 @@ These scoped identifiers allow you to externally specify new behaviors like:
 
 # Middleware
 
-There are two kinds of middleware: Receive middleware and Listener Middleware.
+There are three kinds of middleware: Receive, Listener and Response.
 
 Receive middleware runs once, before listeners are checked.
 Listener middleware runs for every listener that matches the message.
+Response middleware runs for every response sent to a message.
 
 ## Execution Process and API
 
-Similar to [Express middleware](http://expressjs.com/api.html#middleware), Hubot listener middleware executes middleware in definition order. Each middleware can either continue the chain (by calling `next`) or interrupt the chain (by calling `done`). If all middleware continues, the listener callback is executed and `done` is called. Middleware may wrap the `done` callback to allow executing code in the second half of the process (after the listener callback has been executed or a deeper piece of middleware has interrupted).
+Similar to [Express middleware](http://expressjs.com/api.html#middleware), Hubot executes middleware in definition order. Each middleware can either continue the chain (by calling `next`) or interrupt the chain (by calling `done`). If all middleware continues, the listener callback is executed and `done` is called. Middleware may wrap the `done` callback to allow executing code in the second half of the process (after the listener callback has been executed or a deeper piece of middleware has interrupted).
 
 Middleware is called with:
 
-- a context object containing:
-  - matching Listener object (with associated metadata)
-  - response object (contains the original message)
-- next/done callbacks.
-
 - `context`
   - See the each middleware type's API to see what the context will expose.
 - `next`
@@ -789,3 +785,36 @@ of `next` and `done`. Receive middleware context includes these fields:
     - this response object will not have a `match` property, as no listeners have been run yet to match it.
     - middleware may decorate the response object with additional information (e.g. add a property to `response.message.user` with a user's LDAP groups)
     - middleware may modify the `response.message` object
+
+# Response Middleware
+
+Response middleware runs against every message hubot sends to a chat room. It's
+helpful for message formatting, preventing password leaks, metrics, and more.
+
+## Response Middleware Example
+
+This simple example changes the format of links sent to a chat room from
+markdown links (like [example](https://example.com)) to the format supported
+by [Slack](https://slack.com), <https://example.com|example>.
+
+```coffeescript
+module.exports = (robot) ->
+  robot.responseMiddleware (context, next, done) ->
+    return unless context.plaintext?
+    context.strings = (string.replace(/\[([^\[\]]*?)\]\((https?:\/\/.*?)\)/, "<$2|$1>") for string in context.strings)
+    next()
+```
+
+## Response Middleware API
+
+Response middleware callbacks receive three arguments, `context`, `next`, and
+`done`. See the [middleware API](#execution-process-and-api) for a description
+of `next` and `done`. Receive middleware context includes these fields:
+  - `response`
+    - This response object can be used to send new messages from the middleware. Middleware will be called on these new responses. Be careful not to create infinite loops.
+  - `strings`
+    - An array of strings being sent to the chat room adapter. You can edit these, or use `context.strings = ["new strings"]` to replace them.
+  - `method`
+    - A string representing which type of response message the listener sent, such as `send`, `reply`, `emote` or `topic`.
+  - `plaintext`
+    - `true` or `undefined`. This will be set to `true` if the message is of a normal plaintext type, such as `send` or `reply`. This property should be treated as read-only.

src/response.coffee

@@ -19,7 +19,7 @@ class Response
   #
   # Returns nothing.
   send: (strings...) ->
-    @robot.adapter.send @envelope, strings...
+    @runWithMiddleware("send", { plaintext: true }, strings...)
 
   # Public: Posts an emote back to the chat source
   #
@@ -28,7 +28,7 @@ class Response
   #
   # Returns nothing.
   emote: (strings...) ->
-    @robot.adapter.emote @envelope, strings...
+    @runWithMiddleware("emote", { plaintext: true }, strings...)
 
   # Public: Posts a message mentioning the current user.
   #
@@ -37,7 +37,7 @@ class Response
   #
   # Returns nothing.
   reply: (strings...) ->
-    @robot.adapter.reply @envelope, strings...
+    @runWithMiddleware("reply", { plaintext: true }, strings...)
 
   # Public: Posts a topic changing message
   #
@@ -46,7 +46,7 @@ class Response
   #
   # Returns nothing.
   topic: (strings...) ->
-    @robot.adapter.topic @envelope, strings...
+    @runWithMiddleware("topic", { plaintext: true }, strings...)
 
   # Public: Play a sound in the chat source
   #
@@ -55,7 +55,7 @@ class Response
   #
   # Returns nothing
   play: (strings...) ->
-    @robot.adapter.play @envelope, strings...
+    @runWithMiddleware("play", strings...)
 
   # Public: Posts a message in an unlogged room
   #
@@ -64,7 +64,26 @@ class Response
   #
   # Returns nothing
   locked: (strings...) ->
-    @robot.adapter.locked @envelope, strings...
+    @runWithMiddleware("locked", { plaintext: true }, strings...)
+
+  # Private: Call with a method for the given strings using response
+  # middleware.
+  runWithMiddleware: (methodName, opts, strings...) ->
+    callback = undefined
+    copy = strings.slice(0)
+    if typeof(copy[copy.length - 1]) == 'function'
+      callback = copy.pop()
+    context = {response: @, strings: copy, method: methodName}
+    context.plaintext = true if opts.plaintext?
+    responseMiddlewareDone = ->
+    runAdapterSend = (_, done) =>
+      result = context.strings
+      result.push(callback) if callback?
+      @robot.adapter[methodName](@envelope, result...)
+      done()
+    @robot.middleware.response.execute context,
+                                       runAdapterSend,
+                                       responseMiddlewareDone
 
   # Public: Picks a random item from the given items.
   #

src/robot.coffee

@@ -51,6 +51,7 @@ class Robot
     @listeners  = []
     @middleware =
       listener: new Middleware(@)
+      response: new Middleware(@)
       receive:  new Middleware(@)
     @logger     = new Log process.env.HUBOT_LOG_LEVEL or 'info'
     @pingIntervalId = null
@@ -249,6 +250,21 @@ class Robot
     @middleware.listener.register middleware
     return undefined
 
+  # Public: Registers new middleware for execution as a response to any
+  # message is being sent.
+  #
+  # middleware - A function that examines an outgoing message and can modify
+  #              it or prevent its sending. The function is called with
+  #              (context, next, done). If execution should continue,
+  #              the middleware should call next(done). If execution should stop,
+  #              the middleware should call done(). To modify the outgoing message,
+  #              set context.string to a new message.
+  #
+  # Returns nothing.
+  responseMiddleware: (middleware) ->
+    @middleware.response.register middleware
+    return undefined
+
   # Public: Registers new middleware for execution before matching
   #
   # middleware - A function that determines whether or not listeners should be

test/robot_test.coffee

@@ -767,3 +767,85 @@ describe 'Robot', ->
         @robot.receive testMessage, ->
           expect(testCallback).to.have.been.called
           testDone()
+
+    describe 'Response Middleware', ->
+      it 'executes response middleware in order', (testDone) ->
+        @robot.adapter.send = sendSpy = sinon.spy()
+        listenerCallback = sinon.spy()
+        @robot.hear /^message123$/, (response) ->
+          response.send "foobar, sir, foobar."
+
+        @robot.responseMiddleware (context, next, done) ->
+          context.strings[0] = context.strings[0].replace(/foobar/g, "barfoo")
+          next()
+
+        @robot.responseMiddleware (context, next, done) ->
+          context.strings[0] = context.strings[0].replace(/barfoo/g, "replaced bar-foo")
+          next()
+
+        testMessage = new TextMessage @user, 'message123'
+        @robot.receive testMessage, () ->
+          expect(sendSpy.getCall(0).args[1]).to.equal('replaced bar-foo, sir, replaced bar-foo.')
+          testDone()
+
+      it 'allows replacing outgoing strings', (testDone) ->
+        @robot.adapter.send = sendSpy = sinon.spy()
+        listenerCallback = sinon.spy()
+        @robot.hear /^message123$/, (response) ->
+          response.send "foobar, sir, foobar."
+
+        @robot.responseMiddleware (context, next, done) ->
+          context.strings = ["whatever I want."]
+          next()
+
+        testMessage = new TextMessage @user, 'message123'
+        @robot.receive testMessage, () ->
+          expect(sendSpy.getCall(0).args[1]).to.deep.equal("whatever I want.")
+          testDone()
+
+      it 'marks plaintext as plaintext', (testDone) ->
+        @robot.adapter.send = sendSpy = sinon.spy()
+        listenerCallback = sinon.spy()
+        @robot.hear /^message123$/, (response) ->
+          response.send "foobar, sir, foobar."
+        @robot.hear /^message456$/, (response) ->
+          response.play "good luck with that"
+
+        method = undefined
+        plaintext = undefined
+        @robot.responseMiddleware (context, next, done) ->
+          method = context.method
+          plaintext = context.plaintext
+          next(done)
+
+        testMessage = new TextMessage @user, 'message123'
+
+        @robot.receive testMessage, () =>
+          expect(plaintext).to.equal true
+          expect(method).to.equal "send"
+          testMessage2 = new TextMessage @user, 'message456'
+          @robot.receive testMessage2, () ->
+            expect(plaintext).to.equal undefined
+            expect(method).to.equal "play"
+            testDone()
+
+      it 'does not send trailing functions to middleware', (testDone) ->
+        @robot.adapter.send = sendSpy = sinon.spy()
+        asserted = false
+        postSendCallback = ->
+        @robot.hear /^message123$/, (response) ->
+          response.send "foobar, sir, foobar.", postSendCallback
+
+        @robot.responseMiddleware (context, next, done) ->
+          # We don't send the callback function to middleware, so it's not here.
+          expect(context.strings).to.deep.equal ["foobar, sir, foobar."]
+          expect(context.method).to.equal "send"
+          asserted = true
+          next()
+
+        testMessage = new TextMessage @user, 'message123'
+        @robot.receive testMessage, ->
+          expect(asserted).to.equal(true)
+          expect(sendSpy.getCall(0).args[1]).to.equal('foobar, sir, foobar.')
+          expect(sendSpy.getCall(0).args[2]).to.equal(postSendCallback)
+          testDone()