Adding more code documentation.

[arvados.git] / services / api / app / middlewares / rack_socket.rb

diff --git a/services/api/app/middlewares/rack_socket.rb b/services/api/app/middlewares/rack_socket.rb
index e2ca570af629fed09151cc8794cb443033fb8cfa..892dbf527898b532754846722cc9de164bc612e0 100644 (file)
--- a/services/api/app/middlewares/rack_socket.rb
+++ b/services/api/app/middlewares/rack_socket.rb
@@ -2,15 +2,34 @@ require 'rack'
 require 'faye/websocket'
 require 'eventmachine'
 
+# A Rack middleware to handle inbound websocket connection requests and hand
+# them over to the faye websocket library.
 class RackSocket
 
   DEFAULT_ENDPOINT  = '/websocket'
 
+  # Stop EventMachine on signal, this should give it a chance to to unwind any
+  # open connections.
   def die_gracefully_on_signal
     Signal.trap("INT") { EM.stop }
     Signal.trap("TERM") { EM.stop }
   end
 
+  # Create a new RackSocket handler
+  # +app+  The next layer of the Rack stack.
+  #
+  # Accepts options:
+  # +:handler+ (Required) A class to handle new connections.  Initialize will
+  # call handler.new to create the actual handler instance object.  When a new
+  # websocket connection is established, #on_connect on the handler instance
+  # object to notify it about the connection.
+  #
+  # +:mount+  The path for websocket connect requests, defaults to '/websocket'.
+  #
+  # +:websocket_only+  If true, the server will only handle websocket requests,
+  # and all other requests will result in an error.  If false, unhandled
+  # non-websocket requests will be passed along on to 'app' in the usual Rack
+  # way.
   def initialize(app = nil, options = nil)
     @app = app if app.respond_to?(:call)
     @options = [app, options].grep(Hash).first || {}
@@ -38,14 +57,20 @@ class RackSocket
       }
     end
 
+    # Create actual handler instance object from handler class.
     @handler = @options[:handler].new
   end
 
+  # Handle websocket connection request, or pass on to the next middleware
+  # supplied in +app+ initialize (unless +:websocket_only+ option is true, in
+  # which case return an error response.)
+  # +env+ the Rack environment with information about the request.
   def call env
     request = Rack::Request.new(env)
     if request.path_info == @endpoint and Faye::WebSocket.websocket?(env)
       ws = Faye::WebSocket.new(env)
 
+      # Notify handler about new connection
       @handler.on_connect ws
 
       # Return async Rack response