lita-debug-queue 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13062639eb8ef466d93d44bc1421d2d8a6643cd5
-  data.tar.gz: 3349600d80156d2c2df971fc0c61b8bd32ed18a1
+  metadata.gz: 81cb7c42ab50cfb2dcc68a79f3f12e506e96b3f4
+  data.tar.gz: f1601cff61d894a7c979bb1a23f9cf25f94ec80e
 SHA512:
-  metadata.gz: e6f8d5c8fe8c84d6d18e3e15e135358e23238bf350e6e3f78471e30b1046500c18d8a97dc80e3b32262c7f0c6d8f5702bd3721b6bfbb24abd67243199ad7030b
-  data.tar.gz: 2c15f5ced824dc95a2d0e246422ba3118ce7f848b3170a980d3ace919afd27d1b8ea098a62a1d60221d0ec9a25b5459fc68532f5c003e554d9e04ba8c79bfb3a
+  metadata.gz: eceb98b633cbec29a8f09224eb37cf8c7d343f6599a4356338b4459d15dad7c01be5132a5d02b024b0c20f7ea27f952e06366bb9ee2ccc2c794fbe3414b6ffc9
+  data.tar.gz: 09e2794ffbe2964b58d9ec370baab6af3857ad4fcea7bd5e6911ee37729c46874666c920f70a15afcb56571885b2aca8e14d074aaf7328b1a54b339c9c7b023a

data/NEWS.md

@@ -1,5 +1,12 @@
 ## News
 
+### 0.3.0 (2016-02-21)
+
+* The main addition is an API for administrators to interact with the queue.
+  The API is on by default and is *NOT* designed to be secure, only requiring an API key,
+  so it is recommended for most users to stick with version 0.2.0 for the time being.
+  The API methods available are documented in the README.
+
 ### 0.2.0 (2015-10-18)
 
 * Restrict users adding themselves to the queue

data/README.md

@@ -15,17 +15,20 @@ gem "lita-debug-queue"
 
 ## Configuration
 
-lita-debug-queue expects three things to be present for correct operation:
+lita-debug-queue expects four things to be present for correct operation:
 
 1. An `:instructors` authorization group containing admin users.
    If you want TAs to also be able to modify (but not clear) the
    queue you should add them to an `:assistants` group.
 
-2. A `classrooms` config option containing a Hash that maps instructor mention nam   es to classroom channels.
+2. A `debug_queue.classrooms` config option containing a Hash that maps instructor mention nam   es to classroom channels.
 
-3. A `schedule` config option containing a Hash that maps from days of the week
+3. A `debug_queue.schedule` config option containing a Hash that maps from days of the week
    (as from `DateTime.now.strftime("%a")`), to ranges of hours in the
    [server's time zone][heroku-tz].
+   
+4. A `debug_api.passphrase` config option which is just a static string. A way to disable the API
+   will be available in a future release.
 
 [heroku-tz]: http://blog.pardner.com/2012/08/setting-the-default-time-zone-for-a-heroku-app/
 
@@ -43,3 +46,33 @@ lita-debug-queue expects three things to be present for correct operation:
 * `debug next` - Notify the next student to be helped.
 * `debug drop NAME` - Remove the student with NAME from the queue.
 * `debug clear` - Empty the queue.
+
+### API
+
+Better docs coming soon. ... Ish.
+
+### General Conventions
+
+*AUTH*: Every request to the API must include a Query Param `?passphrase=FOO`. Check with your local debug queue admin.``
+
+In the event that an invalid room is supplied or incorrect authorization is provided,
+a JSON object containing an `error` key will be returned.
+All correct API requests will result in a response with `queue` and `message` keys.
+
+#### Retrieve the Queue for a Class
+
+`GET /api/:classroom/queue`
+
+#### Pop the Next Debugee
+
+`PUT /api/:classroom/queue`
+
+#### Drop a specific Debugee
+
+`DELETE /api/:classroom/drop`
+
+*PARAMS:* Drop requires a `student` query param with the mention name of the student to be removed from the queue.
+
+#### Clear the Queue
+
+`DELETE /api/:classroom/clear`

data/lib/lita-debug-queue.rb

@@ -7,6 +7,7 @@ Lita.load_locales Dir[File.expand_path(
 require "lita/handlers/room_finder"
 require "lita/handlers/room_queue"
 require "lita/handlers/debug_queue"
+require "lita/handlers/debug_api"
 
 Lita::Handlers::DebugQueue.template_root File.expand_path(
   File.join("..", "..", "templates"),

data/lib/lita/handlers/debug_api.rb

@@ -0,0 +1,102 @@
+module Lita
+  module Handlers
+    class DebugApi
+      extend Lita::Handler::HTTPRouter
+
+      config :passphrase # The worst auth strategy.
+
+      http.get    "api/:classroom/queue", :show
+      http.put    "api/:classroom/next",  :next
+      http.delete "api/:classroom/drop",  :drop
+      http.delete "api/:classroom/clear", :clear
+
+      def show(request, response)
+        return unless validate!(request, response)
+        result = { queue: @room.queue }
+        response.write(MultiJson.dump(result))
+      end
+
+      def next(request, response)
+        return unless validate!(request, response)
+        if @room.count.zero?
+          result = {
+            queue: @room.queue,
+            message: "The queue is empty. :beer:?"
+          }
+        else
+          student = @room.next
+          send_message(student, "@#{student}: You're up. Let's debug :allthethings:!")
+          result = {
+            queue: @room.queue,
+            message: "#{student} is up next and has been notified."
+          }
+        end
+        response.write(MultiJson.dump(result))
+      end
+
+      def clear(request, response)
+        return unless validate!(request, response)
+        @room.clear!
+        result = { queue: @room.queue, message: "So much for that. :control_knobs:" }
+        response.write(MultiJson.dump(result))
+      end
+
+      def drop(request, response)
+        return unless validate!(request, response)
+        params = request.env["router.params"]
+        student = request.params["student"]
+
+        if @room.include?(student)
+          @room.remove(student)
+          result = { queue: @room.queue, message: "#{student} has been removed." }
+        else
+          result = { queue: @room.queue, message: "#{student} isn't in the queue!" }
+        end
+        response.write(MultiJson.dump(result))
+      end
+
+      private
+
+      ## NOTES: These private methods are a tangle of stateful filth.
+      ## This is out of an attempt at DRYness since we need to return
+      ## JSON everywhere and I lack a nice error handling mechanism
+      ## like rescue_from. (See: response.headers, response.write)
+
+      def validate!(request, response)
+        response.headers["Content-Type"] = "application/json"
+        passphrase_check!(request.params, response)
+        room_check!(request.env, response)
+        @room
+      end
+
+      def passphrase_check!(params, response)
+        authenticated = params["passphrase"] == config.passphrase
+        result = { error: "Passphrase must be supplied correctly to use API." }
+        response.write(MultiJson.dump(result)) unless authenticated
+      end
+
+      def room_check!(env, response)
+        name = env["router.params"][:classroom]
+        if valid_room?(name)
+          redis.namespace = "handlers:debug_queue"
+          @room = RoomQueue.new(name, redis)
+        else
+          result = { error: "Couldn't find Slack channel '#{name}'" }
+          response.write(MultiJson.dump(result))
+        end
+      end
+
+      def valid_room?(name)
+        rooms = robot.config.handlers.debug_queue.classrooms
+        rooms.has_value?(name)
+      end
+
+      def send_message(username, message)
+        user = Lita::User.find_by_mention_name(username)
+        robot.send_message(user, message)
+      end
+    end
+
+    Lita.register_handler(DebugApi)
+  end
+end

data/lita-debug-queue.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "lita-debug-queue"
-  spec.version       = "0.2.0"
+  spec.version       = "0.3.0"
   spec.authors       = ["Brit Butler"]
   spec.email         = ["brit@kingcons.io"]
   spec.description   = "Queue tracking of users who need debugging help with per-channel management"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lita-debug-queue
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brit Butler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-19 00:00:00.000000000 Z
+date: 2016-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lita
@@ -109,6 +109,7 @@ files:
 - README.md
 - Rakefile
 - lib/lita-debug-queue.rb
+- lib/lita/handlers/debug_api.rb
 - lib/lita/handlers/debug_queue.rb
 - lib/lita/handlers/room_finder.rb
 - lib/lita/handlers/room_queue.rb