turntabler 0.0.1 → 0.1.0

data/lib/turntabler/boot.rb

@@ -1,7 +1,7 @@
 require 'turntabler/resource'
 
 module Turntabler
-  # Represents an instance where a user has been booted from a room
+  # Represents an event where a user has been booted from a room
   class Boot < Resource
     # The user that was booted from the room
     # @return [Turntabler::User]

data/lib/turntabler/client.rb

@@ -24,8 +24,8 @@ module Turntabler
     attr_reader :id
 
     # Sets the current room the user is in
-    # @param [Turntabler::Room] value The new room
     # @api private
+    # @param [Turntabler::Room] value The new room
     attr_writer :room
 
     # The directory for looking up / creating rooms
@@ -37,29 +37,31 @@ module Turntabler
     attr_reader :timeout
     
     # Creates a new client for communicating with Turntable.fm with the given
-    # user id / auth token.
+    # email / password.
     # 
-    # @param [String] user_id The user to authenticate with
-    # @param [String] auth The authentication token for the user
+    # @param [String] email The e-mail address of the user to authenticate with
+    # @param [String] password The Turntable password associated with the email address
     # @param [Hash] options The configuration options for the client
     # @option options [String] :id The unique identifier representing this client
     # @option options [String] :room The id of the room to initially enter
+    # @option options [String] :user_id The Turntable id for the authenticating user (required if the user does not have an associated password)
+    # @option options [String] :auth The authentication token for the user (required if the user does not have an associated password)
     # @option options [Fixnum] :timeout (10) The amount of seconds to allow to elapse for requests before timing out
     # @option options [Boolean] :reconnect (false) Whether to allow the client to automatically reconnect when disconnected either by Turntable or by the network
     # @option options [Fixnum] :reconnect_wait (5) The amount of seconds to wait before reconnecting
     # @raise [Turntabler::Error] if an invalid option is specified
     # @yield Runs the given block within the context if the client (for DSL-type usage)
-    def initialize(user_id, auth, options = {}, &block)
+    def initialize(email, password, options = {}, &block)
       options = {
         :id => "#{Time.now.to_i}-#{rand}",
         :timeout => 10,
         :reconnect => false,
         :reconnect_wait => 5
       }.merge(options)
-      assert_valid_keys(options, :id, :room, :url, :timeout, :reconnect, :reconnect_wait)
+      assert_valid_keys(options, :id, :room, :url, :user_id, :auth, :timeout, :reconnect, :reconnect_wait)
 
       @id = options[:id]
-      @user = AuthorizedUser.new(self, :_id => user_id, :auth => auth)
+      @user = AuthorizedUser.new(self, :email => email, :password => password, :_id => options[:user_id], :userauth => options[:auth])
       @rooms = RoomDirectory.new(self)
       @event_handlers = {}
       @timeout = options[:timeout]
@@ -101,8 +103,8 @@ module Turntabler
         @connection.start
 
         # Wait until the connection is authenticated
-        wait do |fiber|
-          on(:session_missing, :once => true) { fiber.resume }
+        wait do |&resume|
+          on(:session_missing, :once => true) { resume.call }
         end
       end
 
@@ -118,8 +120,8 @@ module Turntabler
         @update_timer = nil
         @connection.close
 
-        wait do |fiber|
-          on(:session_ended, :once => true) { fiber.resume }
+        wait do |&resume|
+          on(:session_ended, :once => true) { resume.call }
         end
 
         on_session_ended(allow_reconnect)
@@ -149,8 +151,8 @@ module Turntabler
       message_id = @connection.publish(params.merge(:api => command))
 
       # Wait until we get a response for the given message
-      data = wait do |fiber|
-        on(:response_received, :once => true, :if => {'msgid' => message_id}) {|data| fiber.resume(data)}
+      data = wait do |&resume|
+        on(:response_received, :once => true, :if => {'msgid' => message_id}) {|data| resume.call(data)}
       end
 
       if data['success']
@@ -169,6 +171,16 @@ module Turntabler
     # @option options [Boolean] :once (false) Whether to only run the handler once
     # @return [true]
     # 
+    # == Client Events
+    # 
+    # * +:reconnected+ - The client reconnected (and re-entered any room that the user was previously in)
+    # 
+    # @example
+    #   client.on :reconnected do
+    #     client.room.dj
+    #     # ...
+    #   end
+    # 
     # == Room Events
     # 
     # * +:room_updated+ - Information about the room was updated
@@ -334,6 +346,21 @@ module Turntabler
       user_id ? User.new(self, :_id => user_id) : @user
     end
 
+    # Gets the user with the given DJ name.  This should only be used if the id
+    # of the user is unknown.
+    # 
+    # @param [String] name The user's DJ name
+    # @return [Turntabler::User]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   client.user_by_name('DJSpinster')   # => #<Turntabler::User id="a34bd..." ...>
+    def user_by_name(name)
+      data = api('user.get_id', :name => name)
+      user = self.user(data['userid'])
+      user.attributes = {'name' => name}
+      user
+    end
+
     # Get all avatars availble on Turntable.
     # 
     # @return [Array<Turntabler::Avatar>]
@@ -389,17 +416,20 @@ module Turntabler
       api('file.search', :query => query, :page => options[:page])
 
       # Wait for the async callback
-      songs = wait do |fiber|
-        on(:search_completed, :once => true, :if => {'query' => query}) {|songs| fiber.resume(songs)}
-        on(:search_failed, :once => true, :if => {'query' => query}) { fiber.resume }
+      songs = wait do |&resume|
+        on(:search_completed, :once => true, :if => {'query' => query}) {|songs| resume.call(songs)}
+        on(:search_failed, :once => true, :if => {'query' => query}) { resume.call }
       end
 
       songs || raise(Error, 'Search failed to complete')
     end
 
-    private
     # Callback when a message has been received from Turntable.  This will run
     # any handlers registered for the event associated with the message.
+    # 
+    # @api private
+    # @param [Hash<String, Object>] data The message data received
+    # @return nil
     def on_message(data)
       if Event.command?(data['command'])
         event = Event.new(self, data)
@@ -411,6 +441,7 @@ module Turntabler
       end
     end
     
+    private
     # Callback when a heartbeat message has been received from Turntable determining
     # whether this client is still alive.
     def on_heartbeat
@@ -442,16 +473,29 @@ module Turntabler
       if @reconnect && allow_reconnect
         EM::Synchrony.add_timer(@reconnect_wait) do
           room ? room.enter : connect(url)
+          on_message('command' => 'reconnected')
         end
       end
     end
 
     # Pauses the current fiber until it is resumed with response data.  This
     # can only get resumed explicitly by the provided block.
-    def wait
+    def wait(&block)
       fiber = Fiber.current
-      yield(fiber)
-      Fiber.yield
+
+      # Resume the fiber when a response is received
+      allow_resume = true
+      block.call do |*args|
+        fiber.resume(*args) if allow_resume
+      end
+
+      # Attempt to pause the fiber until a response is received
+      begin
+        Fiber.yield
+      rescue FiberError => ex
+        allow_resume = false
+        raise Error, 'Turntabler APIs cannot be called from root fiber; use Turntabler.run { ... } instead'
+      end
     end
   end
 end

data/lib/turntabler/connection.rb

@@ -78,7 +78,7 @@ module Turntabler
     def publish(params)
       params[:msgid] = message_id = next_message_id
       params = @default_params.merge(params)
-      
+
       logger.debug "Message sent: #{params.inspect}"
 
       if HTTP_APIS.include?(params[:api])
@@ -86,7 +86,7 @@ module Turntabler
       else
         publish_to_socket(params)
       end
-      
+
       # Add timeout handler
       EventMachine.add_timer(@timeout) do
         dispatch('msgid' => message_id, 'command' => 'response_received', 'error' => 'timed out')
@@ -102,7 +102,7 @@ module Turntabler
       data = "~m~#{message.length}~m~#{message}"
       @socket.send(data)
     end
-    
+
     # Publishes the given params to the HTTP API
     def publish_to_http(params)
       api = params.delete(:api)
@@ -124,7 +124,7 @@ module Turntabler
       event = Faye::WebSocket::API::Event.new('message', :data => "~m~#{Time.now.to_i}~m~#{JSON.generate(message)}")
       on_message(event)
     end
-    
+
     # Runs the configured handler with the given message
     def dispatch(message)
       Turntabler.run { @handler.call(message) } if @handler

data/lib/turntabler/digest_helpers.rb

@@ -1,8 +1,10 @@
+require 'digest/sha1'
+
 module Turntabler
   # Provides a set of helper functions for dealing with message digests
   # @api private
   module DigestHelpers
-    # Generates a SHA1 hash from the given data
+    # Generates a SHA1 hash from the given data.
     # 
     # @param [String] data The data to create a hash from
     # @return [String]

data/lib/turntabler/event.rb

@@ -29,8 +29,8 @@ module Turntabler
         define_method("typecast_#{command}_event", &block)
         protected :"typecast_#{command}_event"
       end
-      
-      # Determines whether the given command is handled
+
+      # Determines whether the given command is handled.
       # 
       # @param [String] command The command to check for the existence of
       # @return [Boolean] +true+ if the command exists, otherwise +false+
@@ -56,6 +56,9 @@ module Turntabler
     # The client's connection has closed
     handle :session_ended
 
+    # The client re-connected after previously being disconnected
+    handle :reconnected
+
     # A heartbeat was received from Turntable to ensure the client's connection
     # is still valid
     handle :heartbeat
@@ -119,7 +122,6 @@ module Turntabler
       new_djs = []
       data['user'].each_with_index do |attrs, index|
         new_djs << user = room.build_user(attrs.merge('placements' => data['placements'][index]))
-        room.listeners << user
         room.djs << user
       end
       new_djs
@@ -129,7 +131,6 @@ module Turntabler
     handle :dj_removed, :rem_dj do
       data['user'].map do |attrs|
         user = room.build_user(attrs)
-        room.listeners << user
         room.djs.delete(user)
         user
       end
@@ -138,7 +139,6 @@ module Turntabler
     # A new moderator was added to the room
     handle :moderator_added, :new_moderator do
       user = room.build_user(data)
-      room.listeners << user
       room.moderators << user
       user
     end
@@ -152,26 +152,34 @@ module Turntabler
 
     # There are no more songs to play in the room
     handle :song_unavailable, :nosong do
+      client.on_message('command' => 'song_ended') if room.current_song
       room.attributes = data['room'].merge('current_song' => nil)
       nil
     end
 
     # A new song has started playing
     handle :song_started, :newsong do
+      client.on_message('command' => 'song_ended') if room.current_song
       room.attributes = data['room']
       room.current_song
     end
 
     # The current song has ended
-    handle :song_ended, :endsong do
-      room.attributes = data['room']
+    handle :song_ended do
       room.current_song
     end
 
     # A vote was cast for the song
     handle :song_voted, :update_votes do
+      song = room.current_song
+      initial_up_votes_count = song.up_votes_count
       room.attributes = data['room']
-      room.current_song
+
+      # Update DJ point count
+      dj = room.current_dj
+      dj.attributes = {'points' => dj.points + song.up_votes_count - initial_up_votes_count}
+
+      song
     end
 
     # A user in the room has queued the current song onto their playlist
@@ -181,11 +189,13 @@ module Turntabler
 
     # A song was skipped due to a copyright claim
     handle :song_blocked do
+      client.on_message('command' => 'song_ended') if room.current_song
       Song.new(client, data)
     end
 
     # A song was skipped due to a limit on # of plays per hour
     handle :song_limited, :dmca_error do
+      client.on_message('command' => 'song_ended') if room.current_song
       Song.new(client, data)
     end
 
@@ -201,19 +211,19 @@ module Turntabler
 
     # A song search failed to complete
     handle :search_failed
-    
+
     # The name of the event that was triggered
     # @return [String]
     attr_reader :name
-    
+
     # The raw hash of data parsed from the event
-    # @return [Hash]
+    # @return [Hash<String, Object>]
     attr_reader :data
-    
+
     # The typecasted results parsed from the data
     # @return [Array]
     attr_reader :results
-    
+
     # Creates a new event triggered with the given data
     # 
     # @param [Turntabler::Client] client The client that this event is bound to
@@ -226,11 +236,11 @@ module Turntabler
       @results = __send__("typecast_#{command}_event")
       @results = [@results] unless @results.is_a?(Array)
     end
-    
+
     private
     # The client that all APIs filter through
     attr_reader :client
-    
+
     # Gets the current room the user is in
     def room
       client.room

data/lib/turntabler/handler.rb

@@ -1,23 +1,26 @@
+require 'turntabler/assertions'
 require 'turntabler/event'
+require 'turntabler/loggable'
 
 module Turntabler
   # Represents a callback that's been bound to a particular event
   # @api private
   class Handler
     include Assertions
+    include Loggable
 
     # The event this handler is bound to
     # @return [String]
     attr_reader :event
-    
+
     # Whether to only call the handler once and then never again
     # @return [Boolean] +true+ if only called once, otherwise +false+
     attr_reader :once
-    
+
     # The data that must be matched in order for the handler to run
     # @return [Hash<String, Object>]
     attr_reader :conditions
-    
+
     # Builds a new handler bound to the given event.
     # 
     # @param [String] event The name of the event to bind to
@@ -35,18 +38,22 @@ module Turntabler
       @conditions = options[:if]
       @block = block
     end
-    
-    # Runs this handler with results from the given event.
+
+    # Runs this handler for each result from the given event.
     # 
-    # @param [Array] event The event being triggered
-    # @return [Boolean] +true+ if conditions were matcher to run the handler, otherwise +false+
+    # @param [Turntabler::Event] event The event being triggered
+    # @return [Boolean] +true+ if conditions were matched to run the handler, otherwise +false+
     def run(event)
       if conditions_match?(event.data)
         # Run the block for each individual result
         event.results.each do |result|
-          @block.call(*[result].compact)
+          begin
+            @block.call(*[result].compact)
+          rescue StandardError => ex
+            logger.error(([ex.message] + ex.backtrace) * "\n")
+          end
         end
-        
+
         true
       else
         false

data/lib/turntabler/loggable.rb

@@ -4,6 +4,8 @@ module Turntabler
   module Loggable
     private
     # Delegates access to the logger to Turntabler.logger
+    # 
+    # @return [Logger] The logger configured for this library
     def logger
       Turntabler.logger
     end

data/lib/turntabler/playlist.rb

@@ -29,7 +29,7 @@ module Turntabler
       self.attributes = data
       super()
     end
-    
+
     # Gets the song with the given id.
     # 
     # @param [String] song_id The id for the song

data/lib/turntabler/preferences.rb

@@ -6,47 +6,48 @@ module Turntabler
     # Send e-mails if a fan starts DJing
     # @return [Boolean]
     attribute :notify_dj
-    
+
     # Send e-mails when someone becomes a fan
     # @return [Boolean]
     attribute :notify_fan
-    
+
     # Sends infrequent e-mails about news
     # @return [Boolean]
     attribute :notify_news
-    
+
     # Sends e-mails at random times with a different subsection of the digits of pi
     # @return [Boolean]
     attribute :notify_random
-    
-    # Publishes to facebook songs awesomed in public rooms
+
+    # Publishes to facebook songs voted up in public rooms
     # @return [Boolean]
     attribute :facebook_awesome
-    
+
     # Publishes to facebook when a public room is joined
     # @return [Boolean]
     attribute :facebook_join
-    
+
     # Publishes to facebook when DJing in a public room
     # @return [Boolean]
     attribute :facebook_dj
-    
+
     # Loads the user's current Turntable preferences.
     # 
     # @return [true]
     # @raise [Turntabler::Error] if the command fails
     # @example
-    #   preferences.load    # => true
+    #   preferences.load        # => true
+    #   preferences.notify_dj   # => false
     def load
       data = api('user.get_prefs')
-      self.attributes = data['result'].inject({}) do |result, (preference, value, id, description)|
+      self.attributes = data['result'].inject({}) do |result, (preference, value, *)|
         result[preference] = value
         result
       end
       super
     end
 
-    # Updates the preferences.
+    # Updates the user's preferences.
     # 
     # @param [Hash] attributes The attributes to update
     # @option attributes [Boolean] :notify_dj

data/lib/turntabler/resource.rb

@@ -1,5 +1,4 @@
 require 'pp'
-require 'digest/sha1'
 require 'turntabler/assertions'
 require 'turntabler/digest_helpers'
 
@@ -14,18 +13,18 @@ module Turntabler
 
     class << self
       include Assertions
-      
+
       # Defines a new Turntable attribute on this class.  By default, the name
       # of the attribute is assumed to be the same name that Turntable specifies
       # in its API.  If the names are different, this can be overridden on a
       # per-attribute basis.
       # 
-      # Configuration options:
-      # * +:load+ - Whether the resource should be loaded remotely from
-      #   Turntable in order to access the attribute.  Default is true.
-      # 
-      # == Examples
-      # 
+      # @api private
+      # @param [String] name The public name for the attribute
+      # @param [Hash] options The configuration options
+      # @option options [Boolean] :load (true) Whether the resource should be loaded remotely from Turntable in order to access the attribute
+      # @raise [ArgumentError] if an invalid option is specified
+      # @example
       #   # Define a "name" attribute that maps to a Turntable "name" attribute
       #   attribute :name
       #   
@@ -51,7 +50,6 @@ module Turntabler
       #   # when accessed
       #   attribute :friends, :load => false
       # 
-      # @api private
       # @!macro [attach] attribute
       #   @!attribute [r] $1
       def attribute(name, *turntable_names, &block)
@@ -64,12 +62,12 @@ module Turntabler
           load if instance_variable_get("@#{name}").nil? && !loaded? && options[:load]
           instance_variable_get("@#{name}")
         end
-        
+
         # Query
         define_method("#{name}?") do
           !!__send__(name)
         end
-        
+
         # Typecasting
         block ||= lambda {|value| value}
         define_method("typecast_#{name}", &block)
@@ -123,6 +121,7 @@ module Turntabler
     # "metadata" properties as additional attributes.
     # 
     # @api private
+    # @param [Hash] attributes The updated attributes for the resource
     def attributes=(attributes)
       if attributes
         attributes.each do |attribute, value|
@@ -135,19 +134,21 @@ module Turntabler
         end
       end
     end
-    
+
     # Forces this object to use PP's implementation of inspection.
     # 
     # @api private
+    # @return [String]
     def pretty_print(q)
       q.pp_object(self)
     end
     alias inspect pretty_print_inspect
 
     # Defines the instance variables that should be printed when inspecting this
-    # object.  This ignores the +client+ and +loaded+ attributes.
+    # object.  This ignores the +@client+ and +@loaded+ variables.
     # 
     # @api private
+    # @return [Array<Symbol>]
     def pretty_print_instance_variables
       (instance_variables - [:'@client', :'@loaded']).sort
     end
@@ -155,6 +156,7 @@ module Turntabler
     # Determines whether this resource is equal to another based on their
     # unique identifiers.
     # 
+    # @param [Object] other The object this resource is being compared against
     # @return [Boolean] +true+ if the resource ids are equal, otherwise +false+
     def ==(other)
       if other && other.respond_to?(:id) && other.id