opentok 0.1.3 → 2.2.0

data/lib/opentok.rb

@@ -1,18 +1,7 @@
-=begin
- OpenTok Ruby Library
- http://www.tokbox.com/
-
- Copyright 2010 - 2012, TokBox, Inc.
-
- Last modified: 2012-08-28
-=end
-
-require 'rubygems'
+require "opentok/version"
+require "opentok/opentok"
 
+# Namespace for classes and modules in the OpenTok 2.2 Ruby SDK.
 module OpenTok
 
-  API_URL = 'http://api.opentok.com/hl'
-
-  autoload :OpenTokSDK, 'open_tok/open_tok_sdk'
-
 end

data/lib/opentok/archive.rb

@@ -0,0 +1,92 @@
+require "active_support/inflector"
+
+module OpenTok
+    # Represents an archive of an OpenTok session.
+    #
+    # @attr [int] created_at
+    #   The time at which the archive was created, in milliseconds since the UNIX epoch.
+    #
+    # @attr [string] duration
+    #   The duration of the archive, in milliseconds.
+    #
+    # @attr [string] id
+    #   The archive ID.
+    #
+    # @attr [string] name
+    #   The name of the archive. If no name was provided when the archive was created, this is set
+    #   to null.
+    #
+    # @attr [string] partner_id
+    #   The API key associated with the archive.
+    #
+    # @attr [string] reason
+    #   For archives with the status "stopped", this can be set to "90 mins exceeded", "failure",
+    #   "session ended", or "user initiated". For archives with the status "failed", this can be set
+    #   to "system failure".
+    #
+    # @attr [string] session_id
+    #   The session ID of the OpenTok session associated with this archive.
+    #
+    # @attr [float] size
+    #   The size of the MP4 file. For archives that have not been generated, this value is set to 0.
+    #
+    # @attr [string] status
+    #   The status of the archive, which can be one of the following:
+    #
+    #   * "available" -- The archive is available for download from the OpenTok cloud.
+    #   * "failed" -- The archive recording failed.
+    #   * "started" -- The archive started and is in the process of being recorded.
+    #   * "stopped" -- The archive stopped recording.
+    #   * "uploaded" -- The archive is available for download from the the upload target
+    #     S3 bucket.
+    #
+    # @attr [string] url
+    #   The download URL of the available MP4 file. This is only set for an archive with the status set to
+    #   "available"; for other archives, (including archives with the status "uploaded") this property is
+    #   set to null. The download URL is obfuscated, and the file is only available from the URL for
+    #   10 minutes. To generate a new URL, call the Archive.listArchives() or OpenTok.getArchive() method.
+    class Archive
+
+    # @private
+    def initialize(interface, json)
+      @interface = interface
+      # TODO: validate json fits schema
+      @json = json
+    end
+
+    # A JSON encoded string representation of the archive
+    def to_json
+      @json.to_json
+    end
+
+    # Stops an OpenTok archive that is being recorded.
+    #
+    # Archives automatically stop recording after 90 minutes or when all clients have disconnected
+    # from the session being archived.
+    def stop
+      # TODO: validate returned json fits schema
+      @json = @interface.stop_by_id @json['id']
+    end
+
+    # Deletes an OpenTok archive.
+    #
+    # You can only delete an archive which has a status of "available" or "uploaded". Deleting an
+    # archive removes its record from the list of archives. For an "available" archive, it also
+    # removes the archive file, making it unavailable for download.
+    def delete
+      # TODO: validate returned json fits schema
+      @json = @interface.delete_by_id @json['id']
+    end
+
+    # @private ignore
+    def method_missing(method, *args, &block)
+      camelized_method = method.to_s.camelize(:lower)
+      if @json.has_key? camelized_method and args.empty?
+        # TODO: convert create_time method call to a Time object
+        @json[camelized_method]
+      else
+        super method, *args, &block
+      end
+    end
+  end
+end

data/lib/opentok/archive_list.rb

@@ -0,0 +1,17 @@
+require "opentok/archive"
+
+module OpenTok
+  # A class for accessing an array of Archive objects.
+  class ArchiveList < Array
+
+    # The total number archives.
+    attr_reader :total
+
+    # @private
+    def initialize(interface, json)
+      @total = json['count']
+      super json['items'].map { |item| Archive.new interface, item }
+    end
+
+  end
+end

data/lib/opentok/archives.rb

@@ -0,0 +1,120 @@
+require "opentok/client"
+require "opentok/archive"
+require "opentok/archive_list"
+
+module OpenTok
+  # A class for working with OpenTok 2.0 archives.
+  class Archives
+
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Starts archiving an OpenTok 2.0 session.
+    #
+    # Clients must be actively connected to the OpenTok session for you to successfully start
+    # recording an archive.
+    #
+    # You can only record one archive at a time for a given session. You can only record archives
+    # of OpenTok server-enabled sessions; you cannot archive peer-to-peer sessions.
+    #
+    # @param [String] session_id The session ID of the OpenTok session to archive.
+    # @param [Hash] options  A hash with the key 'name' or :name.
+    # @option options [String] :name This is the name of the archive. You can use this name
+    #   to identify the archive. It is a property of the Archive object, and it is a property
+    #   of archive-related events in the OpenTok.js library.
+    #
+    # @return [Archive] The Archive object, which includes properties defining the archive,
+    #   including the archive ID.
+    #
+    # @raise [OpenTokArchiveError] The archive could not be started. The request was invalid or
+    #   the session has no connected clients.
+    # @raise [OpenTokAuthenticationError] Authentication failed while starting an archive.
+    #   Invalid API key.
+    # @raise [OpenTokArchiveError] The archive could not be started. The session ID does not exist.
+    # @raise [OpenTokArchiveError] The archive could not be started. The session could be
+    #   peer-to-peer or the session is already being recorded.
+    # @raise [OpenTokArchiveError] The archive could not be started.
+    def create(session_id, options = {})
+      raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
+      opts = Hash.new
+      opts[:name] = options[:name].to_s || options["name"].to_s
+      archive_json = @client.start_archive(session_id, opts)
+      Archive.new self, archive_json
+    end
+
+    # Gets an Archive object for the given archive ID.
+    #
+    # @param [String] archive_id The archive ID.
+    #
+    # @return [Archive] The Archive object.
+    # @raise [OpenTokArchiveError] The archive could not be retrieved. The archive ID is invalid.
+    # @raise [OpenTokAuthenticationError] Authentication failed while retrieving the archive.
+    #   Invalid API key.
+    # @raise [OpenTokArchiveError] The archive could not be retrieved.
+    def find(archive_id)
+      raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
+      archive_json = @client.get_archive(archive_id.to_s)
+      Archive.new self, archive_json
+    end
+
+    # Returns an ArchiveList, which is an array of archives that are completed and in-progress,
+    # for your API key.
+    #
+    # @param [Hash] options  A hash with keys defining which range of archives to retrieve.
+    # @option options [integer] :offset Optional. The index offset of the first archive. 0 is offset
+    #   of the most recently started archive. 1 is the offset of the archive that started prior to
+    #   the most recent archive. If you do not specify an offset, 0 is used.
+    # @option options [integer] :count Optional. The number of archives to be returned. The maximum
+    #   number of archives returned is 1000.
+    #
+    # @return [ArchiveList] An ArchiveList object, which is an array of Archive objects.
+    def all(options = {})
+      raise ArgumentError, "Limit is invalid" unless options[:count].nil? or (0..100).include? options[:count]
+      archive_list_json = @client.list_archives(options[:offset], options[:count])
+      ArchiveList.new self, archive_list_json
+    end
+
+    # Stops an OpenTok archive that is being recorded.
+    #
+    # Archives automatically stop recording after 90 minutes or when all clients have disconnected
+    # from the session being archived.
+    #
+    # @param [String] archive_id The archive ID of the archive you want to stop recording.
+    #
+    # @return [Archive] The Archive object corresponding to the archive being stopped.
+    #
+    # @raise [OpenTokArchiveError] The archive could not be stopped. The request was invalid.
+    # @raise [OpenTokAuthenticationError] Authentication failed while stopping an archive.
+    # @raise [OpenTokArchiveError] The archive could not be stopped. The archive ID does not exist.
+    # @raise [OpenTokArchiveError] The archive could not be stopped. The archive is not currently
+    #   recording.
+    # @raise [OpenTokArchiveError] The archive could not be started.
+    def stop_by_id(archive_id)
+      raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
+      archive_json = @client.stop_archive(archive_id)
+      Archive.new self, archive_json
+    end
+
+    # Deletes an OpenTok archive.
+    #
+    # You can only delete an archive which has a status of "available", "uploaded", or "deleted".
+    # Deleting an archive removes its record from the list of archives. For an "available" archive,
+    # it also removes the archive file, making it unavailable for download. For a "deleted"
+    # archive, the archive remains deleted.
+    #
+    # @param [String] archive_id The archive ID of the archive you want to delete.
+    #
+    # @raise [OpenTokAuthenticationError] Authentication failed or an invalid archive ID was given.
+    # @raise [OpenTokArchiveError] The archive could not be deleted. The status must be
+    #   'available', 'deleted', or 'uploaded'.
+    # @raise [OpenTokArchiveError] The archive could not be deleted.
+    def delete_by_id(archive_id)
+      raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
+      response = @client.delete_archive(archive_id)
+      (200..300).include? response.code
+    end
+
+  end
+end

data/lib/opentok/client.rb

@@ -0,0 +1,125 @@
+require "opentok/exceptions"
+
+require "httparty"
+
+module OpenTok
+  # @private For internal use by the SDK.
+  class Client
+    include HTTParty
+    # TODO: expose a setting for http debugging for developers
+    # debug_output $stdout
+
+    def initialize(api_key, api_secret, api_url)
+      self.class.base_uri api_url
+      self.class.headers({
+        "X-TB-PARTNER-AUTH" => "#{api_key}:#{api_secret}",
+        "User-Agent" => "OpenTok-Ruby-SDK/#{VERSION}"
+      })
+      @api_key = api_key
+    end
+
+    def create_session(opts)
+      response = self.class.post("/session/create", :body => opts)
+      case response.code
+      when (200..300)
+        response
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while creating a session. API Key: #{@api_key}"
+      else
+        raise OpenTokError, "Failed to create session. Response code: #{response.code}"
+      end
+    end
+
+    def start_archive(session_id, opts)
+      body = { "sessionId" => session_id, "action" => "start" }
+      body["name"] = opts[:name] unless opts[:name].nil?
+      response = self.class.post("/v2/partner/#{@api_key}/archive", {
+        :body => body.to_json,
+        :headers => { "Content-Type" => "application/json" }
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokArchiveError, "The archive could not be started. The request was invalid or the session has no connected clients."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while starting an archive. API Key: #{@api_key}"
+      when 404
+        raise OpenTokArchiveError, "The archive could not be started. The Session ID does not exist: #{session_id}"
+      when 409
+        raise OpenTokArchiveError, "The archive could not be started. The session could be peer-to-peer or the session is already being recorded."
+      else
+        raise OpenTokArchiveError, "The archive could not be started"
+      end
+    end
+
+    def get_archive(archive_id)
+      response = self.class.get("/v2/partner/#{@api_key}/archive/#{archive_id}")
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokArchiveError, "The archive could not be retrieved. The Archive ID was invalid: #{archive_id}"
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while retrieving an archive. API Key: #{@api_key}"
+      else
+        raise OpenTokArchiveError, "The archive could not be retrieved."
+      end
+    end
+
+    def list_archives(offset, count)
+      query = Hash.new
+      query[:offset] = offset unless offset.nil?
+      query[:count] = count unless count.nil?
+      response = self.class.get("/v2/partner/#{@api_key}/archive", {
+        :query => query.empty? ? nil : query
+      })
+      case response.code
+      when 200
+        response
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while retrieving archives. API Key: #{@api_key}"
+      else
+        raise OpenTokArchiveError, "The archives could not be retrieved."
+      end
+    end
+
+    def stop_archive(archive_id)
+      response = self.class.post("/v2/partner/#{@api_key}/archive/#{archive_id}", {
+        :body => { "action" => "stop" }.to_json,
+        :headers => { "Content-Type" => "application/json" }
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokArchiveError, "The archive could not be stopped. The request was invalid."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while stopping an archive. API Key: #{@api_key}"
+      when 404
+        raise OpenTokArchiveError, "The archive could not be stopped. The Archive ID does not exist: #{archive_id}"
+      when 409
+        raise OpenTokArchiveError, "The archive could not be stopped. The archive is not currently recording."
+      else
+        raise OpenTokArchiveError, "The archive could not be started."
+      end
+    end
+
+    def delete_archive(archive_id)
+      response = self.class.delete("/v2/partner/#{@api_key}/archive/#{archive_id}", {
+        :headers => { "Content-Type" => "application/json" }
+      })
+      case response.code
+      when 204
+        response
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed or an invalid Archive ID was given while deleting an archive. API Key: #{@api_key}, Archive ID: #{archive_id}"
+      when 409
+        raise OpenTokArchiveError, "The archive could not be deleted. The status must be 'available', 'deleted', or 'uploaded'. Archive ID: #{archive_id}"
+      else
+        raise OpenTokArchiveError, "The archive could not be deleted."
+      end
+    end
+
+  end
+end

data/lib/opentok/constants.rb

@@ -0,0 +1,5 @@
+module OpenTok
+  API_URL = "https://api.opentok.com"
+  TOKEN_SENTINEL = "T1=="
+  ROLES = { subscriber: "subscriber", publisher: "publisher", moderator: "moderator" }
+end

data/lib/opentok/exceptions.rb

@@ -0,0 +1,10 @@
+module OpenTok
+
+  # Defines errors raised by methods of the OpenTok Ruby SDK.
+  class OpenTokError < StandardError; end
+  # Defines errors raised by archive-related methods of the OpenTok Ruby SDK.
+  class OpenTokArchiveError < OpenTokError; end
+  # Defines errors raised when you attempt an operation using an invalid OpenTok API key or secret.
+  class OpenTokAuthenticationError < OpenTokError; end
+
+end

data/lib/opentok/opentok.rb

@@ -0,0 +1,174 @@
+require "opentok/constants"
+require "opentok/session"
+require "opentok/client"
+require "opentok/token_generator"
+require "opentok/archives"
+
+require "resolv"
+
+module OpenTok
+  # Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
+  #
+  # To create a new OpenTok object, call the OpenTok constructor with your OpenTok API key
+  # and the API secret from the OpenTok dashboard (https://dashboard.tokbox.com). Do not
+  # publicly share your API secret. You will use it with the OpenTok constructor (only on your web
+  # server) to create OpenTok sessions.
+  #
+  # @attr_reader [String] api_secret @private The OpenTok API secret.
+  # @attr_reader [String] api_key @private The OpenTok API key.
+  #
+  #
+  # @!method generate_token(options)
+  #   Generates a token for a given session.
+  #
+  #   @param [String] sessioin_id The session ID of the session to be accessed by the client using
+  #     the token.
+  #
+  #   @param [Hash] options A hash defining options for the token.
+  #   @option options [String] :role The role for the token. Set this to one of the following
+  #     values:
+  #     * <code>:subscriber</code> -- A subscriber can only subscribe to streams.
+  #
+  #     * <code>:publisher</code> -- A publisher can publish streams, subscribe to
+  #       streams, and signal. (This is the default value if you do not specify a role.)
+  #
+  #     * <code>:moderator</code> -- In addition to the privileges granted to a
+  #       publisher, in clients using the OpenTok.js 2.2 library, a moderator can call the
+  #       <code>forceUnpublish()</code> and <code>forceDisconnect()</code> method of the
+  #       Session object.
+  #   @option options [integer] :expire_time The expiration time, in seconds since the UNIX epoch.
+  #     Pass in 0 to use the default expiration time of 24 hours after the token creation time.
+  #     The maximum expiration time is 30 days after the creation time.
+  #   @option options [String] :data A string containing connection metadata describing the
+  #     end-user. For example, you can pass the user ID, name, or other data describing the
+  #     end-user. The length of the string is limited to 1000 characters. This data cannot be
+  #     updated once it is set.
+  #   @return [String] The token string.
+  class OpenTok
+
+    include TokenGenerator
+    generates_tokens({
+      :api_key => ->(instance) { instance.api_key },
+      :api_secret => ->(instance) { instance.api_secret }
+    })
+
+    # @private
+    # don't want these to be mutable, may cause bugs related to inconsistency since these values are
+    # cached in objects that this can create
+    attr_reader :api_key, :api_secret, :api_url
+
+    ##
+    # Create a new OpenTok object.
+    #
+    # @param [String] api_key Your OpenTok API key. See the OpenTok dashboard
+    #   (https://dashboard.tokbox.com).
+    # @param [String] api_secret Your OpenTok API key.
+    # @param [String] api_url Do not set this parameter. It is for internal use by TokBox.
+    def initialize(api_key, api_secret , api_url = ::OpenTok::API_URL)
+      @api_key = api_key.to_s()
+      @api_secret = api_secret
+      # TODO: do we really need a copy of this in the instance or should we overwrite the module
+      # constant so that other objects can access the same copy?
+      @api_url = api_url
+    end
+
+    # Creates a new OpenTok session and returns the session ID, which uniquely identifies
+    # the session.
+    #
+    # For example, when using the OpenTok JavaScript library, use the session ID when calling the
+    # OT.initSession()</a> method (to initialize an OpenTok session).
+    #
+    # OpenTok sessions do not expire. However, authentication tokens do expire (see the
+    # generateToken() method). Also note that sessions cannot explicitly be destroyed.
+    #
+    # A session ID string can be up to 255 characters long.
+    #
+    # Calling this method results in an OpenTokException in the event of an error.
+    # Check the error message for details.
+    #
+    # You can also create a session using the OpenTok REST API (see
+    # http://www.tokbox.com/opentok/api/#session_id_production) or the OpenTok dashboard
+    # (see https://dashboard.tokbox.com/projects).
+    #
+    # @param [Hash] opts (Optional) This hash defines options for the session.
+    #
+    # @option opts [String] :media_mode Determines whether the session will transmit streams the
+    #   using OpenTok Media Router (<code>:routed</code>) or not (<code>:relayed</code>).
+    #   By default, sessions use the OpenTok Media Router.
+    #
+    #   With the <code>mediaMode</code> property set to <code>:routed</code>, the session
+    #   will use the {http://tokbox.com/#multiparty OpenTok Media Router}.
+    #   The OpenTok Media Router provides the following benefits:
+    #
+    #   * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
+    #     (When the <code>mediaMode</code> property is set to <code>:relayed</code>,
+    #     each client must send a separate audio-video stream to each client subscribing to
+    #     it.)
+    #   * The OpenTok Media Router can improve the quality of the user experience through
+    #     {http://tokbox.com/#iqc Intelligent Quality Control}. With
+    #     Intelligent Quality Control, if a client's connectivity degrades to a degree that
+    #     it does not support video for a stream it's subscribing to, the video is dropped on
+    #     that client (without affecting other clients), and the client receives audio only.
+    #     If the client's connectivity improves, the video returns.
+    #   * The OpenTok Media Router supports the {http://tokbox.com/platform/archiving archiving}
+    #     feature, which lets you record, save, and retrieve OpenTok sessions.
+    #
+    #   With the <code>mediaMode</code> property set to <code>:relayed</code>, the session
+    #   will attempt to transmit streams directly between clients. If clients cannot connect due to
+    #   firewall restrictions, the session uses the OpenTok TURN server to relay audio-video
+    #   streams.
+    #
+    #   You will be billed for streamed minutes if you use the OpenTok Media Router or if the
+    #   session uses the OpenTok TURN server to relay streams. For information on pricing, see the
+    #   {http://www.tokbox.com/pricing OpenTok pricing page}.
+    #
+    # @option opts [String] :location  An IP address that the OpenTok servers will use to
+    #     situate the session in its global network. If you do not set a location hint,
+    #     the OpenTok servers will be based on the first client connecting to the session.
+    #
+    # @return [Session] The Session object. The session_id property of the object is the session ID.
+    def create_session(opts={})
+
+      # normalize opts so all keys are symbols and only include valid_opts
+      valid_opts = [ :media_mode, :location ]
+      opts = opts.inject({}) do |m,(k,v)|
+        if valid_opts.include? k.to_sym
+          m[k.to_sym] = v
+        end
+        m
+      end
+
+      # keep opts around for Session constructor, build REST params
+      params = opts.clone
+
+      # anything other than :relayed sets the REST param to "disabled", in which case we force
+      # opts to be :routed. if we were more strict we could raise an error when the value isn't
+      # either :relayed or :routed
+      if params.delete(:media_mode) == :relayed
+        params["p2p.preference"] = "enabled"
+      else
+        params["p2p.preference"] = "disabled"
+        opts[:media_mode] = :routed
+      end
+      # location is optional, but it has to be an IP address if specified at all
+      unless params[:location].nil?
+        raise "location must be an IPv4 address" unless params[:location] =~ Resolv::IPv4::Regex
+      end
+
+      response = client.create_session(params)
+      Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
+    end
+
+    # An Archives object, which lets you work with OpenTok 2.0 archives.
+    def archives
+      @archives ||= Archives.new client
+    end
+
+    protected
+
+    def client
+      @client ||= Client.new api_key, api_secret, api_url
+    end
+
+  end
+end