kosmonaut 0.3.0 → 0.3.1

data/NEWS

@@ -1,6 +1,30 @@
 Releases
 ========
 
+v0.3.1
+------
+* Documentation.
+* Listener doesn't try to reconnect when unauthenticated.
+
+v0.3.0
+------
+* Kosmonaut::Client#request_single_access token gets 2 arguments now - uid and
+  permission - according to new spec and implementation of WebRocket. 
+
+v0.2.4
+------
+* Handled broken pipe error.
+* Timeouts switched to raw socket options.
+
+v0.2.3
+------
+* Worker's listener tweaks and optimization.
+
+v0.2.2
+------
+* Optimized timeouts.
+* Fixed bug in opening new channel.
+
 v0.2.1
 ------
 * Fixed behaviour of the worker's listener.
@@ -8,4 +32,4 @@ v0.2.1
 v0.2.0
 ------
 * Pure ruby implementation of the client and worker using majordomo pattern.
-* Tests for the API
+* Tests for the API

data/README

@@ -85,7 +85,7 @@ or email one of the maintainers.
 Sponsors
 --------
 All the work on the project is sponsored and supported by Cubox - an
-awesome dev shop from Uruguay <http://cuboxsa.com>.
+awesome dev shop from Uruguay <http://cuboxlabs.com>.
    
 Copyright
 ---------

data/Rakefile

@@ -1,14 +1,12 @@
 # -*- ruby -*-
 
-=begin
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "Kosmonaut - The WebRocket backend client"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-=end
+#require 'rdoc/task'
+#Rake::RDocTask.new do |rdoc|
+#  rdoc.rdoc_dir = 'rdoc'
+#  rdoc.title = "Kosmonaut - The WebRocket backend client"
+#  rdoc.rdoc_files.include('README*')
+#  rdoc.rdoc_files.include('lib/**/*.rb')
+#end
 
 require 'rake/testtask'
 Rake::TestTask.new do |t|

data/lib/kosmonaut.rb

@@ -1,3 +1,13 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 require 'kosmonaut/errors'
 require 'kosmonaut/socket'
 require 'kosmonaut/worker'

data/lib/kosmonaut/client.rb

@@ -1,25 +1,45 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 require 'json'
 require 'thread'
 
 module Kosmonaut
+  # Public: Client is an implementation REQ-REP type socket which handles
+  # communication between backend application and WebRocket backend endpoint.
+  #
+  # Client is used to synchronously request operations from the server.
+  # Synchronous operations are used to provide consistency for the backed
+  # generated events.
+  #
+  # Examples
+  #
+  #     c = Kosmonaut::Client.new("wr://token@127.0.0.1:8081/vhost")
+  #     c.open_channel("comments")
+  #     
+  #     @comment = User.new(params[:comment])
+  #     
+  #     if @comment.save
+  #       c.broadcast("comments", "comment_added", @comment.to_json)
+  #       # ...
+  #     end
+  #
   class Client < Socket
     # Maximum number of seconds to wait for the request to being processed.
     REQUEST_TIMEOUT = 5.0
 
     # Public: The Client constructor. Pre-configures the client instance. See
-    # also the Kosmonaut::Socket#initialize for the details.
+    # also the Kosmonaut::Socket#initialize to get more information.
     # 
     # url - The WebRocket backend endpoint URL to connect to.
     #
-    # The endpoint's URL must have the following format:
-    #
-    #     [scheme]://[secret]@[host]:[port]/[vhost]
-    #
-    # Examples
-    #
-    #     c = Kosmonaut::Client.new("wr://f343...fa4a@myhost.com:8080/hello")
-    #     c.broadcast("room", "status", {"message" => "is going to the beach!"})
-    # 
     def initialize(url)
       super(url)
       @mtx = Mutex.new
@@ -38,32 +58,81 @@ module Kosmonaut
     #     c.broadcast("room". "message", {"content" => "Hello World!"})
     #     c.broadcast("room". "status", {"message" => "is saying hello!"})
     #
+    # Returns 0 if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def broadcast(channel, event, data)
       payload = ["BC", channel, event, data.to_json]
       perform_request(payload)
     end
-
+    
+    # Public: Opens specified channel. If channel already exists, then ok 
+    # response will be received anyway. If channel name is starts with the
+    # `presence-` or `private-` prefix, then appropriate type of the channel
+    # will be created.
+    #
+    # name - A name of the channel to be created.
+    #
+    # Examples
+    #
+    #     c.open_channel("room")
+    #     c.open_channel("presence-room")
+    #     c.open_channel("private-room")
+    # 
+    # Returns 0 if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def open_channel(name)
       payload = ["OC", name]
       perform_request(payload)
     end
 
+    # Public: Closes specified channel. If channel doesn't exist then an
+    # error will be thrown.
+    #
+    # name - A name of the channel to be deleted.
+    #
+    # Examples
+    #
+    #     c.close_channel("hello")
+    #     c.close_channel("presence-room")
+    #
+    # Returns 0 if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def close_channel(name)
       payload = ["CC", name]
       perform_request(payload)
     end
 
+    # Public: Sends a request to generate a single access token for given
+    # user with specified permissions.
+    #
+    # uid        - An user defined unique ID.
+    # permission - A permissions regexp to match against the channels.
+    #
+    # Examples
+    #
+    #     @current_user = User.find(params[:id])
+    #     c.request_single_access_token(@current_user.username, ".*")
+    #
+    # 
+    # Returns generated access token string if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def request_single_access_token(uid, permission)
       payload = ["AT", uid, permission]
       perform_request(payload)
     end
 
+    private
+
+    # Internal: Returns abbreviation of the socket type.
     def socket_type
       "req"
     end
 
-    private
-
+    # Internal: Performs request with specified payload and waits for the
+    # response with it's result.
+    #
+    # Returns response result if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def perform_request(payload)
       @mtx.synchronize {
         response = []
@@ -77,6 +146,18 @@ module Kosmonaut
       }
     end
 
+    # Internal: Parses given response and discovers it's result according
+    # to the WebRocket Backend Protocol specification.
+    #
+    # Response format
+    #
+    #     0x01 | command      \n |
+    #     0x02 | payload...   \n | *
+    #     0x.. | ...          \n | *
+    #          |        \r\n\r\n | 
+    #
+    # Returns response result if succeed.
+    # Raises one of the Kosmonaut::Error inherited exceptions.
     def parse_response(response)
       cmd = response[0].to_s
       Kosmonaut.log("Client/RES : #{response.join("\n").inspect}")

data/lib/kosmonaut/errors.rb

@@ -1,3 +1,13 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 module Kosmonaut
   class Error < StandardError
   end

data/lib/kosmonaut/socket.rb

@@ -1,33 +1,77 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 require 'uri'
 require 'socket'
 require 'securerandom'
 
 module Kosmonaut
+  # Internal: Socket is a base class defining tools and helpers used by 
+  # Client and Worker implementations.
   class Socket
+    # Public: A parsed URL of the WebRocket backend endpoint.
     attr_reader :uri
 
+    # Internal: The Socket constructor. 
+    #
+    # The endpoint's URL must have the following format:
+    #
+    #     [scheme]://[secret]@[host]:[port]/[vhost]
+    #
     def initialize(url)
       @uri = URI.parse(url)
       @addr = ::Socket.getaddrinfo(@uri.host, nil)
     end
 
+    protected
+
+    # Internal: Connect creates new connection with the backend endpoint.
+    #
+    # timeout - A value of the maximum execution time (float).
+    #
+    # Returns configured and connected socket instance.
     def connect(timeout)
-      secs   = timeout.to_i
-      usecs  = ((timeout - secs) * 1_000_000).to_i
+      secs = timeout.to_i
+      usecs = ((timeout - secs) * 1_000_000).to_i
       optval = [secs, usecs].pack("l_2")
       
+      # Raw timeouts are way way way faster than Timeout module or SystemTimer
+      # and doesn't need external dependencies. 
       s = ::Socket.new(::Socket.const_get(@addr[0][0]), ::Socket::SOCK_STREAM, 0)
       s.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY, 1)
       s.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_RCVTIMEO, optval)
       s.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_SNDTIMEO, optval)
       s.connect(::Socket.pack_sockaddr_in(@uri.port, @addr[0][3]))
       
-      generate_identity
+      generate_identity!
       return s
     end
 
-    protected
-
+    # Internal: Pack converts given payload into single packet in format
+    # defined by WebRocket Backend Protocol.
+    #
+    # Packet format
+    #
+    #     0x01 | identity     \n | *
+    #     0x02 |              \n | *
+    #     0x03 | command      \n |
+    #     0x04 | payload...   \n | *
+    #     0x.. | ...          \n | *
+    #          |        \r\n\r\n | 
+    #
+    # * - optional field
+    #
+    # payload       - The data to be packed.
+    # with_identity - Whether identity should be prepend to the packet.
+    #
+    # Returns packed data.
     def pack(payload=[], with_identity=true)
       if with_identity
         payload.unshift("")
@@ -36,11 +80,16 @@ module Kosmonaut
       payload.join("\n") + "\n\r\n\r\n"
     end
 
-    def recv(s)
+    # Internal: Reads one packet from given socket instance.
+    #
+    # sock - The socket to receive from.
+    #
+    # Returns received data (frames) as an array of strings.
+    def recv(sock)
       data = []
       possible_eom = false # possible end of message
-      while !s.eof?
-        line = s.gets
+      while !sock.eof?
+        line = sock.gets
         if line == "\r\n"
           break if possible_eom
           possible_eom = true
@@ -54,13 +103,13 @@ module Kosmonaut
 
     private
 
-    def generate_identity
-      parts = []
-      parts << socket_type
-      parts << @uri.path
-      parts << @uri.user # secret
-      parts << SecureRandom.uuid
-      @identity = parts.join(":")
+    # Internal: Generates unique identity for the socket connection.
+    # Identity is composed from the following parts:
+    #
+    #     [socket-type]:[vhost]:[vhost-token]:[uuid]
+    #
+    def generate_identity!
+      @identity = [socket_type, @uri.path, @uri.user, SecureRandom.uuid].join(":")
     end
   end
 end

data/lib/kosmonaut/version.rb

@@ -1,8 +1,18 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 module Kosmonaut
   module Version
     MAJOR = 0
     MINOR = 3
-    PATCH = 0
+    PATCH = 1
 
     def self.to_s
       [MAJOR, MINOR, PATCH].join('.')

data/lib/kosmonaut/worker.rb

@@ -1,11 +1,62 @@
+# Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+ 
 require 'json'
 require 'thread'
 
 module Kosmonaut
+  # Public: Worker is an implementation of SUBSCRIBER socket which handles
+  # events incoming from the WebRocket backend endpoint.
+  #
+  # The communication here is asynchronous, and Worker can't send other
+  # messages than ready state, heartbeat, or quit notification.
+  #
+  # Worker shouldn't be called directly, it should be used as a base class
+  # for implementing your own workers.
+  #
+  # Examples
+  #
+  #     class MyWorker < Kosmonaut::Worker
+  #       def on_message(event, data)
+  #         if event == "append_chat_history"
+  #           @room = Room.find(data[:room_id])
+  #           @room.messages.build(data[:message])
+  #           @room.save!
+  #         end
+  #       end
+  #  
+  #       def on_error(err)
+  #         puts "WEBROCKET ERROR: #{err.to_s}"
+  #       end
+  #
+  #       def on_exception(err)
+  #         puts "INTERNAL ERROR: #{err.to_s}"
+  #       end
+  #     end
+  #
+  #     w = MyWorker.new("wr://token@127.0.0.1:8081/vhost")
+  #     w.listen
+  # 
   class Worker < Socket
-    RECONNECT_DELAY = 1000 # in milliseconds
-    HEARTBEAT_INTERVAL = 500 # in milliseconds
+    # Number of milliseconds after which client should retry to reconnect
+    # to the bakcend endpoint.
+    RECONNECT_DELAY = 1000
 
+    # Number of milliseconds between next heartbeat message.
+    HEARTBEAT_INTERVAL = 500
+
+    # Public: The Worker constructor. Pre-configures the worker instance. See
+    # also the Kosmonaut::Socket#initialize to get more information.
+    #
+    # url - The WebRocket backend endpoint URL to connect to.
+    #
     def initialize(url)
       super(url)
       @mtx = Mutex.new
@@ -16,6 +67,10 @@ module Kosmonaut
       @heartbeat_at = 0
     end
 
+    # Public: Listen starts a listener's loop for the worker. Listener implements
+    # the Majordomo pattern to manage connection with the backend. 
+    #
+    # Raises Kosmonaut::UnauthorizedError if worker's credentials are invalid.
     def listen
       @alive = true
       reconnect
@@ -31,7 +86,7 @@ module Kosmonaut
           end
 
           msg = recv(@sock)
-          raise Errno::ECONNRESET if @sock.eof? || msg.empty?
+          raise Errno::ECONNRESET if msg.empty?
           Kosmonaut.log("Worker/RECV : #{msg.join("\n").inspect}")
           cmd = msg.shift
 
@@ -46,6 +101,8 @@ module Kosmonaut
           when "ER"
             error_handler(msg.size < 1 ? 597 : msg[0])
           end
+
+          raise Errno::ECONNRESET if @sock.eof?
         rescue Errno::EAGAIN, Errno::ECONNRESET, Errno::ECONNREFUSED, IOError => err
           Kosmonaut.log("Worker/RECONNECT: " + err.to_s)
           sleep(@reconnect_delay.to_f / 1000.0)
@@ -59,33 +116,49 @@ module Kosmonaut
       end
     end
     
+    # Public: Breaks the listener's loop and stops execution of
+    # the worker. 
     def stop
       @mtx.synchronize { @alive = false }
     end
 
+    # Public: Returns whether this worker's event loop is running.
     def alive?
       @mtx.synchronize { @alive }
     end
 
+    private
+
+    # Internal: Returns abbreviation of the socket type.
     def socket_type
       "dlr"
     end
-
-    private
-
-    def send(s, payload, with_identity=false)
-      return unless s
+    
+    # Internal: Packs given payload and writes it to the specified socket.
+    #
+    # sock          - The socket to write to.
+    # payload       - The payload to be packed and sent.
+    # with_identity - Whether identity should be prepend to the packet.
+    #
+    def send(sock, payload, with_identity=false)
+      return unless sock
       packet = pack(payload, with_identity)
-      s.write(packet)
+      sock.write(packet)
       Kosmonaut.log("Worker/SENT : #{packet.inspect}")
+      nil
     rescue Errno::EPIPE
     end
-
+    
+    # Internal: Disconnects and cleans up the socket if connected.
     def disconnect
-      @sock.close if @sock 
+      @sock.close if @sock
+      @sock = nil
     rescue IOError
     end
-      
+
+    # Internal: Sets up new connection with the backend endpoint and sends
+    # information that it's ready to work. Also initializes heartbeat 
+    # scheduling.
     def reconnect
       @sock = connect(((@heartbeat_ivl * 2).to_f / 1000.0).to_i + 1)
       send(@sock, ["RD"], true)
@@ -93,6 +166,11 @@ module Kosmonaut
     rescue Errno::ECONNREFUSED
     end
 
+    # Intenral: Message handler routes received data to user defined
+    # 'on_message' method (if exists) and handles it's exceptions.
+    #
+    # data - The data to be handled.
+    #
     def message_handler(data)
       if respond_to?(:on_message)
         payload = JSON.parse(data.to_s)
@@ -102,15 +180,30 @@ module Kosmonaut
       exception_handler(err)
     end
 
+    # Internal: Handles given WebRocket error.
+    #
+    # errcode - A code of the received error.
+    # 
+    # Raises Kosmonaut::UnauthorizerError if error 402 has been received.
     def error_handler(errcode)
       if respond_to?(:on_error)
         err = ERRORS[errcode.to_i]
-        on_error(err ? err : UnknownServerError)
+        if err == UnauthorizedError
+          raise err.new
+        end
+        begin
+          on_error((err ? err : UnknownServerError).new)
+        rescue => err
+          exception_handler(err)
+        end
       end
-    rescue => err
-      exception_handler(err)
     end
 
+    # Internal: Exception handler passes given error to user defined
+    # exception handler or raises error if such not exists.
+    #
+    # err - The exception to be handled.
+    #
     def exception_handler(err)
       if respond_to?(:on_exception)
         on_exception(err)

data/test/test_kosmonaut_worker.rb

@@ -2,15 +2,15 @@ require File.expand_path("../helper", __FILE__)
 
 class MyWorker < Kosmonaut::Worker
   def on_message(event, data)
-    puts "MSG", event, data
+    puts "MSG : #{event} : #{data.inspect}"
   end
   
   def on_error(err)
-    puts "ERR", err.to_s
+    puts "ERR : #{err.to_s}"
   end
 
   def on_exception(err)
-    puts "EXC", err.to_s
+    puts "EXC : #{err.to_s}"
   end
 end
 

metadata

@@ -2,7 +2,7 @@
 name: kosmonaut
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Krzysztof Kowalik
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-24 00:00:00 Z
+date: 2012-01-28 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
@@ -44,12 +44,12 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/kosmonaut.rb
+- lib/kosmonaut/client.rb
+- lib/kosmonaut/errors.rb
 - lib/kosmonaut/socket.rb
-- lib/kosmonaut/worker.rb
 - lib/kosmonaut/version.rb
-- lib/kosmonaut/errors.rb
-- lib/kosmonaut/client.rb
+- lib/kosmonaut/worker.rb
+- lib/kosmonaut.rb
 - test/helper.rb
 - test/test_kosmonaut_client.rb
 - test/test_kosmonaut_worker.rb
@@ -82,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Ruby client for the WebRocket backend