Merge pull request #265 from opentok/dev

Version 4.7.0

Author: superchilled

CHANGES.md

@@ -1,3 +1,9 @@
+# 4.7.0
+
+* Adds support for the End-to-end encryption (E2EE) feature [#259](https://github.com/opentok/OpenTok-Ruby-SDK/pull/259)
+* Implements Auto-archive improvements [#262](https://github.com/opentok/OpenTok-Ruby-SDK/pull/262)
+* Updates the README to explain appending a custom value to the `UserAgent` header [#263](https://github.com/opentok/OpenTok-Ruby-SDK/pull/263)
+
 # 4.6.0
 
 * Adds functionality for working with the Audio Connector feature [#247](https://github.com/opentok/OpenTok-Ruby-SDK/pull/247)

README.md

@@ -59,6 +59,8 @@ opentok = OpenTok::OpenTok.new api_key, api_secret
 
 #### Initialization Options
 
+**Custom Timeout**
+
 You can specify a custom timeout value for HTTP requests when initializing a new `OpenTok::OpenTok`
 object:
 
@@ -71,6 +73,23 @@ opentok = OpenTok::OpenTok.new api_key, api_secret, :timeout_length => 10
 The value for `:timeout_length` is an integer representing the number of seconds to wait for an HTTP
 request to complete. The default is set to 2 seconds.
 
+**UA Addendum**
+
+You can also append a custom string to the `User-Agent` header value for HTTP requests when initializing a new `OpenTok::OpenTok`
+object:
+
+```ruby
+require "opentok"
+
+opentok = OpenTok::OpenTok.new api_key, api_secret, :ua_addendum => 'FOO'
+```
+
+The above would generate a `User-Agent` header something like this:
+
+```
+User-Agent: OpenTok-Ruby-SDK/4.6.0-Ruby-Version-3.1.2-p20 FOO
+```
+
 ### Creating Sessions
 
 To create an OpenTok Session, use the `OpenTok#create_session(properties)` method.
@@ -101,6 +120,9 @@ session = opentok.create_session :location => '12.34.56.78'
 # A session with automatic archiving (must use the routed media mode):
 session = opentok.create_session :archive_mode => :always, :media_mode => :routed
 
+# A session with end-to-end encryption (must use the routed media mode):
+session = opentok.create_session :e2ee => true, :media_mode => :routed
+
 # Store this sessionId in the database for later use:
 session_id = session.session_id
 ```

lib/opentok/opentok.rb

@@ -144,11 +144,26 @@ def initialize(api_key, api_secret, opts={})
     #     automatically (<code>:always</code>) or not (<code>:manual</code>). When using automatic
     #     archiving, the session must use the <code>:routed</code> media mode.
     #
+    # @option opts [Symbol] :archive_name The name to use for archives in auto-archived sessions.
+    #     When setting this option, the :archive_mode option must be set to :always or an error will result.
+    #     The length of the archive name can be up to 80 chars.
+    #     Due to encoding limitations the following special characters are translated to a colon (:) character: ~, -, _.
+    #     If you do not set a name and the archiveMode option is set to always, the archive name will be empty.
+    #
+    # @option opts [Symbol] :archive_resolution The resolution of archives in an auto-archived session.
+    #     Valid values are "480x640", "640x480" (the default), "720x1280", "1280x720", "1080x1920", and "1920x1080".
+    #     When setting this option, the :archive_mode option must be set to :always or an error will result.
+    #
+    # @option opts [true, false] :e2ee
+    #     (Boolean, optional) — Whether the session uses end-to-end encryption from client to client (default: false).
+    #     This should not be set to `true` if `:media_mode` is `:relayed`.
+    #     See the {https://tokbox.com/developer/guides/end-to-end-encryption/ documentation} for more information.
+    #
     # @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, :archive_mode ]
+      valid_opts = [ :media_mode, :location, :archive_mode, :archive_name, :archive_resolution, :e2ee ]
       opts = opts.inject({}) do |m,(k,v)|
         if valid_opts.include? k.to_sym
           m[k.to_sym] = v
@@ -159,6 +174,13 @@ def create_session(opts={})
       # keep opts around for Session constructor, build REST params
       params = opts.clone
 
+      # validate input combinations
+      raise ArgumentError, "A session with always archive mode must also have the routed media mode." if (params[:archive_mode] == :always && params[:media_mode] == :relayed)
+
+      raise ArgumentError, "A session with relayed media mode should not have e2ee set to true." if (params[:media_mode] == :relayed && params[:e2ee] == true)
+
+      raise ArgumentError, "A session with always archive mode must not have e2ee set to true." if (params[:archive_mode] == :always && params[:e2ee] == true)
+
       # 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
@@ -175,10 +197,9 @@ def create_session(opts={})
       # archive mode is optional, but it has to be one of the valid values if present
       unless params[:archive_mode].nil?
         raise "archive mode must be either always or manual" unless ARCHIVE_MODES.include? params[:archive_mode].to_sym
+        raise ArgumentError, "archive name and/or archive resolution must not be set if archive mode is manual" if params[:archive_mode] == :manual && (params[:archive_name] || params[:archive_resolution])
       end
 
-      raise "A session with always archive mode must also have the routed media mode." if (params[:archive_mode] == :always && params[:media_mode] == :relayed)
-
       response = client.create_session(params)
       Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
     end

lib/opentok/session.rb

@@ -20,6 +20,10 @@ module OpenTok
   # @attr_reader [String] archive_mode Whether the session will be archived automatically
   #  (<code>:always</code>) or not (<code>:manual</code>).
   #
+  # @attr_reader [String] archive_name The name to use for archives in auto-archived sessions.
+  #
+  # @attr_reader [String] :archive_resolution The resolution of archives in an auto-archived session.
+  #
   # @!method generate_token(options)
   #   Generates a token.
   #
@@ -57,7 +61,7 @@ class Session
       :session_id => ->(instance) { instance.session_id }
     })
 
-    attr_reader :session_id, :media_mode, :location, :archive_mode, :api_key, :api_secret
+    attr_reader :session_id, :media_mode, :location, :archive_mode, :archive_name, :archive_resolution, :e2ee, :api_key, :api_secret
 
     # @private
     # this implementation doesn't completely understand the format of a Session ID
@@ -73,7 +77,12 @@ def self.belongs_to_api_key?(session_id, api_key)
     # @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, @archive_mode = opts.fetch(:media_mode, :relayed), opts[:location], opts.fetch(:archive_mode, :manual)
+      @media_mode = opts.fetch(:media_mode, :relayed)
+      @location = opts[:location]
+      @archive_mode = opts.fetch(:archive_mode, :manual)
+      @archive_name = opts.fetch(:archive_name, '') if archive_mode == :always
+      @archive_resolution = opts.fetch(:archive_resolution, "640x480") if archive_mode == :always
+      @e2ee = opts.fetch(:e2ee, :false)
     end
 
     # @private

lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '4.6.0'
+  VERSION = '4.7.0'
 end