spotify_web 0.0.1

data/lib/spotify_web/connection.rb

@@ -0,0 +1,162 @@
+require 'faye/websocket'
+require 'em-http'
+require 'json'
+
+require 'spotify_web/assertions'
+require 'spotify_web/loggable'
+require 'spotify_web/schema/mercury.pb'
+
+module SpotifyWeb
+  # Represents the interface for sending and receiving data in Spotify
+  # @api private
+  class Connection
+    include Assertions
+    include Loggable
+
+    # Maps method actions to their Spotify identifier
+    METHODS = {'SUB' => 1, 'UNSUB' => 2}
+
+    # The host that this connection is bound to
+    # @return [String]
+    attr_reader :host
+
+    # The callback to run when a message is received from the underlying socket.
+    # The data passed to the callback will always be a hash.
+    # @return [Proc]
+    attr_accessor :handler
+
+    # Builds a new connection for sending / receiving data via the given host.
+    # 
+    # @note This will *not* open the connection -- #start must be explicitly called in order to do so.
+    # @param [String] host The host to open a conection to
+    # @param [Hash] options The connection options
+    # @option options [Fixnum] :timeout The amount of time to allow to elapse for requests before timing out
+    # @raise [ArgumentError] if an invalid option is specified
+    def initialize(host, options = {})
+      assert_valid_keys(options, :timeout)
+
+      @host = host
+      @message_id = 0
+      @timeout = options[:timeout]
+    end
+
+    # Initiates the connection with Spotify
+    # 
+    # @return [true]
+    def start
+      uri = URI.parse("ws://#{host}")
+      scheme = uri.port == 443 ? 'wss' : 'ws'
+      @socket = Faye::WebSocket::Client.new("#{scheme}://#{uri.host}")
+      @socket.onopen = lambda {|event| on_open(event)}
+      @socket.onclose = lambda {|event| on_close(event)}
+      @socket.onmessage = lambda {|event| on_message(event)}
+      true
+    end
+
+    # Closes the connection (if one was previously opened)
+    # 
+    # @return [true]
+    def close
+      if @socket
+        @socket.close
+
+        # Spotify doesn't send the disconnect frame quickly, so the callback
+        # gets run immediately
+        EventMachine.add_timer(0.1) { on_close(nil) }
+      end
+      true
+    end
+
+    # Whether this connection's socket is currently open
+    # 
+    # @return [Boolean] +true+ if the connection is open, otherwise +false+
+    def connected?
+      @connected
+    end
+
+    # Publishes the given params to the underlying web socket.  The defaults
+    # initially configured as part of the connection will also be included in
+    # the message.
+    # 
+    # @param [Hash] params The parameters to include in the message sent
+    # @return [Fixnum] The id of the message delivered
+    def publish(command, options)
+      if command == 'request'
+        options = {:uri => '', :method => 'GET', :source => ''}.merge(options)
+        options[:content_type] = 'vnd.spotify/mercury-mget-request' if options[:payload].is_a?(Schema::Mercury::MercuryMultiGetRequest)
+        payload = options.delete(:payload)
+
+        # Generate arguments for the request
+        args = [
+          METHODS[options[:method]] || 0,
+          Base64.encode64(Schema::Mercury::MercuryRequest.new(options).encode)
+        ]
+        args << Base64.encode64(payload.encode) if payload
+
+        # Update the command to what Spotify expects
+        command = 'sp/hm_b64'
+      else
+        args = options
+      end
+
+      message = {
+        :id => next_message_id,
+        :name => command,
+        :args => args || []
+      }
+
+      logger.debug "Message sent: #{message.inspect}"
+      @socket.send(message.to_json)
+
+      # Add timeout handler
+      EventMachine.add_timer(@timeout) do
+        dispatch('id' => message[:id], 'command' => 'response_received', 'error' => 'timed out')
+      end if @timeout
+
+      message[:id]
+    end
+
+    private
+    # Runs the configured handler with the given message
+    def dispatch(message)
+      SpotifyWeb.run { @handler.call(message) } if @handler
+    end
+
+    # Callback when the socket is opened.
+    def on_open(event)
+      logger.debug 'Socket opened'
+      @connected = true
+      dispatch('command' => 'session_started')
+    end
+
+    # Callback when the socket is closed.  This will mark the connection as no
+    # longer connected.
+    def on_close(event)
+      logger.debug 'Socket closed'
+      @connected = false
+      @socket = nil
+      dispatch('command' => 'session_ended')
+    end
+
+    # Callback when a message has been received from the remote server on the
+    # open socket.
+    def on_message(event)
+      message = JSON.parse(event.data)
+
+      if message['id']
+        message['command'] = 'response_received'
+      elsif message['message']
+        command, *args = *message['message']
+        message = {'command' => command, 'args' => args}
+      end
+
+      logger.debug "Message received: #{message.inspect}"
+      dispatch(message)
+    end
+
+    # Calculates what the next message id should be sent to Spotify
+    def next_message_id
+      @message_id += 1
+    end
+  end
+end

data/lib/spotify_web/error.rb

@@ -0,0 +1,13 @@
+module SpotifyWeb
+  # Represents an error within the library
+  class Error < StandardError
+  end
+  
+  # Represents an error that occurred while connecting to the Spotify Web API
+  class ConnectionError < Error
+  end
+  
+  # Represents an error that occurred while interacting with the Spotify Web API
+  class APIError < Error
+  end
+end

data/lib/spotify_web/event.rb

@@ -0,0 +1,95 @@
+module SpotifyWeb
+  # Provides access to all of the events that get triggered by incoming messages
+  # from the Spotify Web API
+  # @api private
+  class Event
+    class << self
+      # Maps Spotify command => event name
+      # @return [Hash<String, String>]
+      attr_reader :commands
+
+      # Defines a new event that maps to the given Spotify command.  The
+      # block defines how to typecast the data that is received from Spotify.
+      # 
+      # @param [String] name The name of the event exposed to the rest of the library
+      # @param [String] command The Spotify command that this event name maps to
+      # @yield [data] Gives the data to typecast to the block
+      # @yieldparam [Hash] data The data received from Spotify
+      # @yieldreturn The typecasted data that should be passed into any handlers bound to the event
+      # @return [nil]
+      def handle(name, command = name, &block)
+        block ||= lambda { [args] }
+        commands[command] = name
+
+        define_method("typecast_#{command}_event", &block)
+        protected :"typecast_#{command}_event"
+      end
+
+      # 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+
+      def command?(command)
+        commands.include?(command)
+      end
+    end
+
+    @commands = {}
+
+    # The client's connection has opened
+    handle :session_started
+
+    # The client's connection has closed
+    handle :session_ended
+
+    # The user is successfully logged in
+    handle :session_authenticated, :login_complete
+
+    # The client re-connected after previously being disconnected
+    handle :reconnected
+
+    # A response was receivied from a prior command sent to Spotify
+    handle :response_received do
+      data
+    end
+
+    # A request was made to evaluate javascript on the client
+    handle :work_requested, :do_work do
+      data
+    end
+
+    # The name of the event that was triggered
+    # @return [String]
+    attr_reader :name
+
+    # The raw arguments list from the event
+    # @return [Array<Object>]
+    attr_reader :args
+
+    # The raw hash of data parsed from the event
+    # @return [Hash<String, Object>]
+    attr_reader :data
+
+    # The typecasted results args parsed from the event
+    # @return [Array<Array<Object>>]
+    attr_reader :results
+
+    # Creates a new event triggered with the given data
+    # 
+    # @param [SpotifyWeb::Client] client The client that this event is bound to
+    # @param [Symbol] command The name of the command that fired the event
+    # @param [Array] args The raw argument data from the event
+    def initialize(client, command, args)
+      @client = client
+      @args = args
+      @data = args[0]
+      @name = self.class.commands[command]
+      @results = __send__("typecast_#{command}_event")
+      @results = [[@results].compact] unless @results.is_a?(Array)
+    end
+
+    private
+    # The client that all APIs filter through
+    attr_reader :client
+  end
+end

data/lib/spotify_web/handler.rb

@@ -0,0 +1,74 @@
+require 'spotify_web/assertions'
+require 'spotify_web/event'
+require 'spotify_web/loggable'
+
+module SpotifyWeb
+  # 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
+    # @param [Hash] options The configuration options
+    # @option options [Boolean] :once (false) Whether to only call the handler once
+    # @option options [Hash] :if (nil) Data that must be matched to run
+    # @raise [ArgumentError] if an invalid option is specified
+    def initialize(event, options = {}, &block)
+      assert_valid_values(event, *Event.commands.values)
+      assert_valid_keys(options, :once, :if)
+      options = {:once => false, :if => nil}.merge(options)
+
+      @event = event
+      @once = options[:once]
+      @conditions = options[:if]
+      @block = block
+    end
+
+    # Runs this handler for each result from the given event.
+    # 
+    # @param [SpotifyWeb::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 |args|
+          begin
+            @block.call(*args)
+          rescue StandardError => ex
+            logger.error(([ex.message] + ex.backtrace) * "\n")
+          end
+        end
+
+        true
+      else
+        false
+      end
+    end
+
+    private
+    # Determines whether the conditions configured for this handler match the
+    # event data
+    def conditions_match?(data)
+      if conditions
+        conditions.all? {|(key, value)| data[key] == value}
+      else
+        true
+      end
+    end
+  end
+end

data/lib/spotify_web/loggable.rb

@@ -0,0 +1,13 @@
+module SpotifyWeb
+  # Provides a set of helper methods for logging
+  # @api private
+  module Loggable
+    private
+    # Delegates access to the logger to SpotifyWeb.logger
+    # 
+    # @return [Logger] The logger configured for this library
+    def logger
+      SpotifyWeb.logger
+    end
+  end
+end

data/lib/spotify_web/playlist.rb

@@ -0,0 +1,48 @@
+require 'spotify_web/resource'
+require 'spotify_web/resource_collection'
+require 'spotify_web/song'
+require 'spotify_web/schema/mercury.pb'
+require 'spotify_web/schema/playlist4.pb'
+
+module SpotifyWeb
+  # Represents a collection of songs
+  class Playlist < Resource
+    # The user this playlist is managed by
+    # @return [SpotifyWeb::User]
+    attribute :user, :load => false
+
+    # The human-readable name for the playlist
+    # @return [String]
+    attribute :name
+
+    # The songs that have been added to this playlist
+    # @return [Array<SpotifyWeb::Song>]
+    attribute :songs do |songs|
+      ResourceCollection.new(client, songs.map {|song| Song.new(client, :uri => song.uri)})
+    end
+
+    def name #:nodoc:
+      uri_id == 'starred' ? 'Starred' : @name
+    end
+
+    def uri_id #:nodoc:
+      @uri_id ||= @uri ? @uri.split(':')[4] : super
+    end
+
+    # Loads the attributes for this playlist
+    def load
+      path = uri_id == 'starred' ? uri_id : "playlist/#{uri_id}"
+      response = api('request',
+        :uri => "hm://playlist/user/#{user.username}/#{path}?from=0&length=100",
+        :response_schema => Schema::Playlist4::SelectedListContent
+      )
+      result = response['result']
+
+      attributes = result.attributes.to_hash
+      attributes[:songs] = result.contents.items
+      self.attributes = attributes
+
+      super
+    end
+  end
+end

data/lib/spotify_web/resource.rb

@@ -0,0 +1,309 @@
+require 'pp'
+require 'radix'
+require 'spotify_web/assertions'
+require 'spotify_web/error'
+
+module SpotifyWeb
+  # Represents an object that's been created using content from Spotify. This
+  # encapsulates responsibilities such as reading and writing attributes.
+  class Resource
+    include Assertions
+
+    class << self
+      include Assertions
+
+      # Defines a new Spotify attribute on this class.  By default, the name
+      # of the attribute is assumed to be the same name that Spotify specifies
+      # in its API.  If the names are different, this can be overridden on a
+      # per-attribute basis.
+      # 
+      # @api private
+      # @param [String] name The name for the attribute
+      # @param [Hash] options The configuration options
+      # @option options [Boolean] :load (true) Whether the resource should be loaded remotely from Spotify in order to access the attribute
+      # @raise [ArgumentError] if an invalid option is specified
+      # @example
+      #   # Define a "name" attribute that maps to a Spotify "name" attribute
+      #   attribute :name
+      #   
+      #   # Define an "id" attribute that maps to a Spotify "_id" attribute
+      #   attribute :id, :_id
+      #   
+      #   # Define an "user_id" attribute that maps to both a Spotify "user_id" and "userid" attribute
+      #   attribute :user_id, :user_id, :userid
+      #   
+      #   # Define a "time" attribute that maps to a Spotify "time" attribute
+      #   # and converts the value to a Time object
+      #   attribute :time do |value|
+      #     Time.at(value)
+      #   end
+      #   
+      #   # Define a "created_at" attribute that maps to a Spotify "time" attribute
+      #   # and converts the value to a Time object
+      #   attribute :created_at, :time do |value|
+      #     Time.at(value)
+      #   end
+      #   
+      #   # Define a "songs" attribute that does *not* get loaded from Spotify
+      #   # when accessed
+      #   attribute :songs, :load => false
+      # 
+      # @!macro [attach] attribute
+      #   @!attribute [r] $1
+      def attribute(name, *spotify_names, &block)
+        options = spotify_names.last.is_a?(Hash) ? spotify_names.pop : {}
+        assert_valid_keys(options, :load)
+        options = {:load => true}.merge(options)
+
+        # Reader
+        define_method(name) do
+          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 do |value|
+          value.force_encoding('UTF-8') if value.is_a?(String)
+          value
+        end
+        define_method("typecast_#{name}", &block)
+        protected :"typecast_#{name}"
+
+        # Attribute name conversion
+        spotify_names = [name] if spotify_names.empty?
+        spotify_names.each do |spotify_name|
+          define_method("#{spotify_name}=") do |value|
+            instance_variable_set("@#{name}", value.nil? ? nil : __send__("typecast_#{name}", value))
+          end
+          protected :"#{spotify_name}="
+        end
+      end
+
+      # The Spotify type name for this resouce
+      # @return [String]
+      attr_accessor :resource_name
+
+      # The metadata schema to use for loading data for this resource
+      # @return [Class]
+      attr_accessor :metadata_schema
+
+      # Provides a default resource name if one isn't specified
+      # @return [String]
+      def resource_name
+        @resource_name ||= begin
+          result = name.split('::').last.downcase
+          result.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          result.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+          result
+        end
+      end
+    end
+
+    # The characters to encoding / decoding in base62
+    BASE62_CHARS = ('0'..'9').to_a + ('a'..'z').to_a + ('A'..'Z').to_a
+
+    # The unique id for this resource on Spotify
+    # "e1987c10dbc34f4d8be1b11ddfd6bb31"
+    # @return [String]
+    attribute :id, :load => false
+
+    # The global unique id for this resource on Spotify
+    # "\xE1\x98|\x10\xDB\xC3OM\x8B\xE1\xB1\x1D\xDF\xD6\xBB1"
+    # @return [String]
+    attribute :gid, :load => false
+
+    # The URI for loading information about this resource
+    # "spotify:track:6RGXtkDeWNP2gyASlfjzTr"
+    # @return [String]
+    attribute :uri, :load => false
+
+    # The id used within the URI for this resource
+    # "6RGXtkDeWNP2gyASlfjzTr"
+    # @return [String]
+    attribute :uri_id, :load => false
+
+    # Initializes this resources with the given attributes.  This will continue
+    # to call the superclass's constructor with any additional arguments that
+    # get specified.
+    # 
+    # @api private
+    def initialize(client, attributes = {}, *args)
+      @loaded = false
+      @metadata_loaded = false
+      @client = client
+      self.attributes = attributes
+      super(*args)
+    end
+
+    # The unique identifier, represented in base16
+    # 
+    # @return [String] The Spotify ID for the resource
+    def id
+      @id ||= begin
+        if @gid
+          Radix::Base.new(Radix::BASE::HEX).encode(gid).rjust(32, '0')
+        elsif @uri
+          Radix::Base.new(Radix::BASE::HEX).convert(uri_id, BASE62_CHARS).rjust(32, '0')
+        end
+      end
+    end
+
+    # The unique group identifier, represented as bytes in base 16
+    # 
+    # @example "\xE1\x98|\x10\xDB\xC3OM\x8B\xE1\xB1\x1D\xDF\xD6\xBB1"
+    # @return [String] The group id
+    def gid
+      @gid ||= id && Radix::Base.new(Radix::BASE::HEX).decode(id)
+    end
+    
+    # The unique URI representing this resource in Spotify
+    # 
+    # @example "spotify:track:6RGXtkDeWNP2gyASlfjzTr"
+    # @return [String] The URI for the resource
+    def uri
+      @uri ||= uri_id && "spotify:#{self.class.resource_name}:#{uri_id}"
+    end
+
+    # The id used within the resource's URI, represented in base62.
+    # 
+    # @example "6RGXtkDeWNP2gyASlfjzTr"
+    # @return [String] The URI's id
+    def uri_id
+      @uri_id ||= begin
+        if @uri
+          @uri.split(':')[2]
+        elsif @gid || @id
+          Radix::Base.new(BASE62_CHARS).convert(id, Radix::BASE::HEX).rjust(22, '0')
+        end
+      end
+    end
+
+    # Loads the attributes for this resource from Spotify.  By default this is
+    # a no-op and just marks the resource as loaded.
+    # 
+    # @return [true]
+    def load
+      load_metadata
+      @loaded = true
+    end
+    alias :reload :load
+
+    # Determines whether the current resource has been loaded from Spotify.
+    # 
+    # @return [Boolean] +true+ if the resource has been loaded, otherwise +false+
+    def loaded?
+      @loaded
+    end
+
+    # Looks up the metadata associated with this resource.
+    # 
+    # @api private
+    # @return [Object, nil] +nil+ if there is no metadata schema associated, otherwise the result of the request
+    def load_metadata
+      if self.class.metadata_schema && !@metadata_loaded
+        if @metadata_loader
+          # Load the metadata externally
+          @metadata_loader.call
+          @metadata_loader = nil
+        else
+          # Load the metadata just for this single resource
+          response = api('request',
+            :uri => metadata_uri,
+            :response_schema => self.class.metadata_schema
+          )
+          self.metadata = response['result']
+        end
+      end
+    end
+
+    # Updates this resource based on the given metadata
+    # 
+    # @api private
+    # @param [Beefcake::Message, Proc] metadata The metadata to use or a proc for loading it
+    def metadata=(metadata)
+      if !metadata || metadata.is_a?(Proc)
+        @metadata_loader = metadata
+      else
+        @metadata_loaded = true
+        self.attributes = metadata.to_hash
+      end
+    end
+
+    # The URI for looking up the resource's metadata
+    # 
+    # @api private
+    # @return [String, nil] +nil+ if there is no metadata schema associated, otherwise the uri
+    def metadata_uri
+      if self.class.metadata_schema
+        "hm://metadata/#{self.class.resource_name}/#{id}"
+      end
+    end
+
+    # Attempts to set attributes on the object only if they've been explicitly
+    # defined by the class.
+    # 
+    # @api private
+    # @param [Hash] attributes The updated attributes for the resource
+    def attributes=(attributes)
+      if attributes
+        attributes.each do |attribute, value|
+          attribute = attribute.to_s
+          __send__("#{attribute}=", value) if respond_to?("#{attribute}=", true)
+        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+ variables.
+    # 
+    # @api private
+    # @return [Array<Symbol>]
+    def pretty_print_instance_variables
+      (instance_variables - [:'@client', :'@loaded', :'@metadata_loaded', :'@metadata_loader']).sort
+    end
+
+    # 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
+        other.id == id
+      else
+        false
+      end
+    end
+    alias :eql? :==
+
+    # Generates a hash for this resource based on the unique identifier
+    # 
+    # @return [Fixnum]
+    def hash
+      id.hash
+    end
+
+    private
+    # The client that all APIs filter through
+    attr_reader :client
+
+    # Runs the given API command on the client.
+    def api(command, options = {})
+      client.api(command, options)
+    end
+  end
+end