opentok 0.1.3 → 2.2.0

data/lib/opentok/session.rb

@@ -0,0 +1,76 @@
+require "base64"
+require "opentok/token_generator"
+
+module OpenTok
+
+  # Represents an OpenTok session.
+  #
+  # Use the OpenTok.createSession() method to create an OpenTok session. Use the
+  # session_id property of the Session object to get the session ID.
+  #
+  # @attr_reader [String] session_id The session ID.
+  # @attr_reader [String] api_secret @private The OpenTok API secret.
+  # @attr_reader [String] api_key @private The OpenTok API key.
+  # @attr_reader [String] media_mode Set to :routed if the session uses the OpenTok Media Router
+  #   or to :relayed if the session attempts to transmit streams directly between clients.
+  #
+  # @attr_reader [String] location The location hint IP address. See the OpenTok.createSession()
+  #   method.
+  #
+  # @!method generate_token(options)
+  #   Generates a token.
+  #
+  #   @param [Hash] options
+  #   @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 Session
+
+    include TokenGenerator
+    generates_tokens({
+      :api_key => ->(instance) { instance.api_key },
+      :api_secret => ->(instance) { instance.api_secret },
+      :session_id => ->(instance) { instance.session_id }
+    })
+
+    attr_reader :session_id, :media_mode, :location, :api_key, :api_secret
+
+    # @private
+    # this implementation doesn't completely understand the format of a Session ID
+    # that is intentional, that is too much responsibility.
+    def self.belongs_to_api_key?(session_id, api_key)
+      encoded = session_id[2..session_id.length]
+                          .gsub('-', '+')
+                          .gsub('_', '/')
+      decoded = Base64.decode64(encoded)
+      decoded.include? api_key
+    end
+
+    # @private
+    def initialize(api_key, api_secret, session_id, opts={})
+      @api_key, @api_secret, @session_id = api_key, api_secret, session_id
+      @media_mode, @location = opts.fetch(:media_mode, :routed), opts[:location]
+    end
+
+    # @private
+    def to_s
+      @session_id
+    end
+  end
+end

data/lib/opentok/token_generator.rb

@@ -0,0 +1,101 @@
+require "opentok/constants"
+require "opentok/session"
+
+require "base64"
+require "addressable/uri"
+require "digest/hmac"
+require "active_support/time"
+
+module OpenTok
+  # @private
+  module TokenGenerator
+    # this works when using include TokenGenerator
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    module ClassMethods
+
+      # @private arguments the method we should generate will need (in order):
+      # *  api_key (required - if no lambda assigned, part of method sig)
+      # *  api_secret (required - if no lambda assigned, part of method sig)
+      # *  session_id (required - if no lambda assigned, part of method sig)
+      # *  token_opts (optional - part of method sig)
+      #
+      # arg_lambdas is a hash of keys which are the above args and values are lambdas that all have the 
+      # signature ->(instance)
+      def generates_tokens(arg_lambdas={})
+        @arg_lambdas = arg_lambdas
+        define_method(:generate_token) do |*args|
+          # puts "generate_something is being called on #{self}. set up with #{method_opts.inspect}"
+          dynamic_args = [ :api_key, :api_secret, :session_id, :token_opts ].map do |arg|
+            self.class.arg_lambdas[arg].call(self) if self.class.arg_lambdas[arg]
+          end
+          dynamic_args.compact!
+          args = args.first(4-dynamic_args.length)
+          self.class.generate_token.call(*dynamic_args, *args)
+        end
+      end
+
+      # @private For internal use by the SDK.
+      def arg_lambdas
+        @arg_lambdas
+      end
+
+      # Generates a token
+      def generate_token
+        TokenGenerator::GENERATE_TOKEN_LAMBDA
+      end
+
+    end
+
+    # @private TODO: this probably doesn't need to be a constant anyone can read
+    GENERATE_TOKEN_LAMBDA = ->(api_key, api_secret, session_id, opts = {}) do
+      # normalize required data params
+      role = opts.fetch(:role, :publisher)
+      unless ROLES.has_key? role
+        raise "'#{role}' is not a recognized role"
+      end
+      unless Session.belongs_to_api_key? session_id.to_s, api_key
+        raise "Cannot generate token for a session_id that doesn't belong to api_key: #{api_key}"
+      end
+
+      # minimum data params
+      data_params = {
+        :role => role,
+        :session_id => session_id,
+        :create_time => Time.now.to_i,
+        :nonce => Random.rand
+      }
+
+      # normalize and add additional data params
+      unless (expire_time = opts[:expire_time]).nil?
+        unless expire_time.between?(Time.now, Time.now + 30.days)
+          raise "Expire time must be within the next 30 days" 
+        end
+        data_params[:expire_time] = expire_time.to_i
+      end
+
+      unless opts[:data].nil?
+        unless (data = opts[:data].to_s).length < 1000
+          raise "Connection data must be less than 1000 characters"
+        end
+        data_params[:connection_data] = data
+      end
+
+      data_string = Addressable::URI.form_encode data_params
+      meta_string = Addressable::URI.form_encode({
+        :partner_id => api_key,
+        :sig => Digest::HMAC.hexdigest(data_string, api_secret, Digest::SHA1)
+      })
+
+      TOKEN_SENTINEL + Base64.strict_encode64(meta_string + ":" + data_string)
+    end
+
+
+    # this works when using extend TokenGenerator
+    # def generates_tokens(method_opts)
+    #   puts "I'm being called on #{self} with argument #{method_opts.inspect}"
+    #   
+    # end
+  end
+end

data/lib/opentok/version.rb

@@ -0,0 +1,4 @@
+module OpenTok
+  # @private
+  VERSION = '2.2.0'
+end

data/opentok.gemspec

@@ -1,27 +1,34 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "open_tok/version"
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "opentok/version"
 
-Gem::Specification.new do |s|
-  s.name        = "opentok"
-  s.version     = OpenTok::VERSION
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Stijn Mathysen", "Karmen Blake", "Song Zheng"]
-  s.email       = ["stijn@skylight.be", "karmenblake@gmail.com", "song@tokbox.com"]
-  s.homepage    = "https://github.com/opentok/Opentok-Ruby-SDK"
-  s.summary     = %q{OpenTok gem}
-  s.description = %q{OpenTok is an API from TokBox that enables websites to weave live group video communication into their online experience. With OpenTok you have the freedom and flexibility to create the most engaging web experience for your users. OpenTok is currently available as a JavaScript and ActionScript 3.0 library. This gem allows you to connect to the API from within Ruby (and Rails)}
+Gem::Specification.new do |spec|
+  spec.name        = "opentok"
+  spec.version     = OpenTok::VERSION
+  spec.authors     = ["Stijn Mathysen", "Karmen Blake", "Song Zheng", "Patrick Quinn-Graham", "Ankur Oberoi"]
+  spec.email       = ["stijn@skylight.be", "karmenblake@gmail.com", "song@tokbox.com", "pqg@tokbox.com", "ankur@tokbox.com"]
+  spec.summary     = %q{Ruby gem for the OpenTok API}
+  spec.description = %q{OpenTok is an API from TokBox that enables websites to weave live group video communication into their online experience. With OpenTok you have the freedom and flexibility to create the most engaging web experience for your users. This gem lets you generate sessions and tokens for OpenTok applications. It also includes support for working with OpenTok 2.0 archives. See <http://tokbox.com/opentok/platform> for more details.}
+  # TODO: this homepage isn't set up just yet
+  spec.homepage    = "https://opentok.github.io/opentok-ruby-sdk"
+  spec.license     = "MIT"
 
-  s.rubyforge_project = "opentok"
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.1.1"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "webmock", "~> 1.17.4"
+  spec.add_development_dependency "vcr", "~> 2.8.0"
+  spec.add_development_dependency "yard", "~> 0.8.7"
+  # TODO: exclude this for compatibility with rbx
+  # spec.add_development_dependency "debugger", "~> 1.6.6"
 
-  s.add_dependency "addressable"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "rspec"
-  s.add_development_dependency "webmock"
-  s.add_development_dependency "vcr"
+  spec.add_dependency "addressable", "~> 2.3.5"
+  spec.add_dependency "httparty", "0.13.0"
+  spec.add_dependency "activesupport", ">= 3.2"
 end

data/sample/Archiving/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+gem "sinatra", "~> 1.4.4"
+gem "opentok", :path => "../../"

data/sample/Archiving/README.md

@@ -0,0 +1,212 @@
+# OpenTok Archiving Sample for Ruby
+
+This is a simple demo app that shows how you can use the OpenTok Java SDK to archive (or record)
+Sessions, list archives that have been created, download the recordings, and delete the recordings.
+
+## Running the App
+
+First, download the dependencies using [Bundler](http://bundler.io)
+
+```
+$ bundle install
+```
+
+Next, add your own API Key and API Secret to the environment variables. There are a few ways to do
+this but the simplest would be to do it right in your shell.
+
+```
+$ export API_KEY=0000000
+$ export API_SECRET=abcdef1234567890abcdef01234567890abcdef
+```
+
+Finally, start the server using Bundler to handle dependencies
+
+```
+$ bundle exec ruby hello_world.rb
+```
+
+Visit <http://localhost:9393> in your browser. You can now create new archives (either as a host or
+as a participant) and also play archives that have already been created.
+
+## Walkthrough
+
+This demo application uses the same frameworks and libraries as the HelloWorld sample. If you have
+not already gotten familiar with the code in that project, consider doing so before continuing.
+
+The explanations below are separated by page. Each section will focus on a route handler within the
+main application (archiving_sample.rb).
+
+### Creating Archives – Host View
+
+Start by visiting the host page at <http://localhost:9393/host> and using the application to record
+an archive. Your browser will first ask you to approve permission to use the camera and microphone.
+Once you've accepted, your image will appear inside the section titled 'Host'. To start recording
+the video stream, press the 'Start Archiving' button. Once archiving has begun the button will turn
+green and change to 'Stop Archiving'. You should also see a red blinking indicator that you are
+being recorded. Wave and say hello! Stop archiving when you are done.
+
+Next we will see how the host view is implemented on the server. The route handler for this page is
+shown below:
+
+```ruby
+get '/host' do
+  api_key = settings.api_key
+  session_id = settings.session.session_id
+  token = settings.opentok.generate_token(session_id, :role => :moderator)
+
+  erb :host, :locals => {
+    :api_key => api_key,
+    :session_id => session_id,
+    :token => token
+  }
+end
+```
+
+If you've completed the HelloWorld walkthrough, this should look familiar. This handler simply
+generates the three strings that the client (JavaScript) needs to connect to the session: `api_key`,
+`session_id` and `token`. After the user has connected to the session, they press the
+'Start Archiving' button, which sends an XHR (or Ajax) request to the <http://localhost:9393/start>
+URL. The route handler for this URL is shown below:
+
+```ruby
+get '/start' do
+  archive = settings.opentok.archives.create settings.session.session_id, {
+    :name => "Ruby Archiving Sample App"
+  }
+  body archive.to_json
+end
+```
+
+In this handler, `opentok.archives.create` is called with the `session_id` for the session that
+needs to be archived. The optional second argument is a hash which contains a `:name` key. The value
+is a string that will be stored with the archive and can be read later. In this case, as in the
+HelloWorld sample app, there is only one session created and it is used here and for the participant
+view. This will trigger the recording to begin. The response sent back to the client's XHR request
+will be the JSON representation of the archive, which is returned from the `to_json()` method. The
+client is also listening for the `archiveStarted` event, and uses that event to change the
+'Start Archiving' button to show 'Stop Archiving' instead. When the user presses the button this
+time, another XHR request is sent to the <http://localhost:9393/stop/:archiveId> URL where
+`:archiveId` represents the ID the client receives in the 'archiveStarted' event. The route handler
+for this request is shown below:
+
+```ruby
+get '/stop/:archive_id' do
+  archive = settings.opentok.archives.stop_by_id(params[:archive_id])
+  body archive.to_json
+end
+```
+
+This handler is very similar to the previous one. Instead of calling the `archives.create()` method,
+the `archives.stop_by_id()` method is called. This method takes an `archive_id` as its parameter,
+which is different for each time a session starts recording. But the client has sent this to the
+server as part of the URL, so the `params[:archive_id]` expression is used to retrieve it.
+
+Now you have understood the three main routes that are used to create the Host experience of
+creating an archive. Much of the functionality is done in the client with JavaScript. That code can
+be found in the `public/js/host.js` file. Read about the
+[OpenTok.js JavaScript](http://tokbox.com/opentok/libraries/client/js/) library to learn more.
+
+### Creating Archives - Participant View
+
+With the host view still open and publishing, open an additional window or tab and navigate to
+<http://localhost:9393/participant> and allow the browser to use your camera and microphone. Once
+again, start archiving in the host view. Back in the participant view, notice that the red blinking
+indicator has been shown so that the participant knows his video is being recorded. Now stop the
+archiving in the host view. Notice that the indicator has gone away in the participant view too.
+
+Creating this view on the server is as simple as the HelloWorld sample application. See the code
+for the route handler below:
+
+```ruby
+get '/participant' do
+  api_key = settings.api_key
+  session_id = settings.session.session_id
+  token = settings.opentok.generate_token(session_id, :role => :moderator)
+
+  erb :participant, :locals => {
+    :api_key => api_key,
+    :session_id => session_id,
+    :token => token
+  }
+end
+```
+
+Since this view has no further interactivity with buttons, this is all that is needed for a client
+that is participating in an archived session. Once again, much of the functionality is implemented
+in the client, in code that can be found in the `public/js/participant.js` file.
+
+### Past Archives
+
+Start by visiting the history page at <http://localhost:9393/history>. You will see a table that
+displays all the archives created with your API Key. If there are more than five, the older ones
+can be seen by clicking the "Older →" link. If you click on the name of an archive, your browser
+will start downloading the archive file. If you click the "Delete" link in the end of the row
+for any archive, that archive will be deleted and no longer available. Some basic information like
+when the archive was created, how long it is, and its status is also shown. You should see the
+archives you created in the previous sections here.
+
+We begin to see how this page is created by looking at the route handler for this URL:
+
+```ruby
+get '/history' do
+  page = (params[:page] || "1").to_i
+  offset = (page - 1) * 5
+  archives = settings.opentok.archives.all(:offset => offset, :count => 5)
+
+  show_previous = page > 1 ? '/history?page=' + (page-1).to_s : nil
+  show_next = archives.total > (offset + 5) ? '/history?page=' + (page+1).to_s : nil
+
+  erb :history, :locals => {
+    :archives => archives,
+    :show_previous => show_previous,
+    :show_next => show_next
+  }
+end
+```
+
+This view is paginated so that we don't potentially show hundreds of rows on the table, which would
+be difficult for the user to navigate. So this code starts by figuring out which page needs to be
+shown, where each page is a set of 5 archives. The `page` number is read from the request's query
+string parameters as a string and then converted into an Integer. The `offset`, which represents how
+many archives are being skipped is always calculated as five times as many pages that are less than
+the current page, which is `(page - 1) * 5`. Now there is enough information to ask for a list of
+archives from OpenTok, which we do by calling the `archives.all()` method of the `opentok` instance.
+The parameter is an optional Hash that contains the offset, the count (which is always 5 in this
+view). If we are not at the first page, we can pass the view a string that contains the relative URL
+for the previous page. Similarly, we can also include one for the next page. Now the application
+renders the view using that information and the partial list of archives.
+
+At this point the template file `views/history.erb` handles looping over the array of archives and
+outputting the proper information for each column in the table. It also places a link to the
+download and delete routes around the archive's name and its delete button, respectively.
+
+The code for the download route handler is shown below:
+
+```ruby
+get '/download/:archive_id' do
+  archive = settings.opentok.archives.find(params[:archive_id])
+  redirect archive.url
+end
+```
+
+The download URL for an archive is available as a property of an `Archive` instance. In order to get
+an instance to this archive, the `archives.find()` method of the `opentok` instance is used. The only
+parameter it needs is the `archive_id`. We use the same technique as above to read that `archive_id`
+from the URL. Lastly, we send a redirect response to the download URL back to the browser so the
+download begins.
+
+The code for the delete route handler is shown below:
+
+```ruby
+get '/delete/:archive_id' do
+  settings.opentok.archives.delete_by_id(params[:archive_id])
+  redirect '/history'
+end
+```
+
+Once again the `archive_id` is retrieved from the URL of the request. This value is then passed to
+the `archives.delete_by_id()` method of the `opentok` instance. Now that the archive has been
+deleted, a redirect response back to the first page of the history is sent back to the browser.
+
+That completes the walkthrough for this Archiving sample application. Feel free to continue to use
+this application to browse the archives created for your API Key.