ably 1.2.1 → 1.2.3

data/lib/ably/realtime/push.rb

@@ -11,27 +11,39 @@ module Ably
         @client = client
       end
 
-      # Admin features for push notifications like managing devices and channel subscriptions
+      # A {Ably::Realtime::Push::Admin} object.
+      #
+      # @spec RSH1
+      #
       # @return [Ably::Realtime::Push::Admin]
+      #
       def admin
         @admin ||= Admin.new(self)
       end
 
-      # Activate this device for push notifications by registering with the push transport such as GCM/APNS
+      # Activates the device for push notifications with FCM or APNS, obtaining a unique identifier from them.
+      # Subsequently registers the device with Ably and stores the deviceIdentityToken in local storage.
+      #
+      # @spec RSH2a
       #
       # @note This is unsupported in the Ruby library
+      #
       def activate(*arg)
         raise_unsupported
       end
 
-      # Deactivate this device for push notifications by removing the registration with the push transport such as GCM/APNS
+      # Deactivates the device from receiving push notifications with Ably and FCM or APNS.
+      #
+      # @spec RSH2b
       #
       # @note This is unsupported in the Ruby library
+      #
       def deactivate(*arg)
         raise_unsupported
       end
 
       private
+
       def raise_unsupported
         raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable'
       end

data/lib/ably/rest/channel/push_channel.rb

@@ -3,9 +3,6 @@ module Ably::Rest
     # A push channel used for push notifications
     # Each PushChannel maps to exactly one Rest Channel
     #
-    # @!attribute [r] channel
-    #   @return [Ably::Rest::Channel] Underlying channel object
-    #
     class PushChannel
       attr_reader :channel
 

data/lib/ably/rest/channel.rb

@@ -1,12 +1,7 @@
 module Ably
   module Rest
-    # The Ably Realtime service organises the traffic within any application into named channels.
-    # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.
+    # Enables messages to be published and historic messages to be retrieved for a channel.
     #
-    # @!attribute [r] name
-    #   @return {String} channel name
-    # @!attribute [r] options
-    #   @return {Hash} channel options configured for this channel, see {#initialize} for channel_options
     class Channel
       include Ably::Modules::Conversions
 
@@ -15,9 +10,14 @@ module Ably
       # @api private
       attr_reader :client
 
-      attr_reader :name, :options
+      # The channel name.
+      # @return [String]
+      attr_reader :name
 
-      # Push channel used for push notification (client-side)
+      attr_reader :options
+
+      # A {Ably::Rest::Channel::PushChannel} object
+      # @spec RSH4
       # @return [Ably::Rest::Channel::PushChannel]
       # @api private
       attr_reader :push
@@ -39,7 +39,10 @@ module Ably
         @push    = PushChannel.new(self)
       end
 
-      # Publish one or more messages to the channel. Five overloaded forms
+      # Publishes a message to the channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.
+      #
+      # @spec RSL1
+      #
       # @param name [String, Array<Ably::Models::Message|Hash>, Ably::Models::Message, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs, or a single Ably::Model::Message object
       # @param data [String, Array, Hash, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters
       # @param attributes [Hash, nil]   Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object)
@@ -112,15 +115,19 @@ module Ably
         [201, 204].include?(response.status)
       end
 
-      # Return the message   of the channel
+      # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical {Ably::Models::Message}
+      # objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from
+      # history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.
+      #
+      # @spec RSL2a
       #
       # @param [Hash] options   the options for the message history request
-      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
-      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
-      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
-      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
+      # @option options [Integer,Time] :start      The time from which messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1
+      # @option options [Integer,Time] :end        The time until messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1
+      # @option options [Symbol]       :direction  The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. RSL2b2
+      # @option options [Integer]      :limit      An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. RSL2b3
       #
-      # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
+      # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::Message} objects.
       #
       def history(options = {})
         url = "#{base_path}/messages"
@@ -146,14 +153,15 @@ module Ably
         end
       end
 
-      # Return the {Ably::Rest::Presence} object
-      #
+      # A {Ably::Rest::Presence} object.
+      # @spec RSL3
       # @return [Ably::Rest::Presence]
       def presence
         @presence ||= Presence.new(client, self)
       end
 
-      # Sets or updates the stored channel options. (#RSL7)
+      # Sets the {Ably::Models::ChannelOptions} for the channel.
+      # @spec RSL7
       # @param channel_options [Hash, Ably::Models::ChannelOptions]  A hash of options or a {Ably::Models::ChannelOptions}
       # @return [Ably::Models::ChannelOptions]
       def set_options(channel_options)
@@ -161,6 +169,13 @@ module Ably
       end
       alias options= set_options
 
+      # Retrieves a {Ably::Models::ChannelDetails} object for the channel, which includes status and occupancy metrics.
+      # @spec RSL8
+      # @return [Ably::Models::ChannelDetails] 	A {Ably::Models::ChannelDetails} object.
+      def status
+        Ably::Models::ChannelDetails.new(client.get(base_path).body)
+      end
+
       private
 
       def base_path

data/lib/ably/rest/channels.rb

@@ -8,24 +8,26 @@ module Ably
         super client, Ably::Rest::Channel
       end
 
-      # @!method get(name, channel_options = {})
       # Return a {Ably::Rest::Channel} for the given name
       #
       # @param name [String] The name of the channel
       # @param channel_options [Hash] Channel options, currently reserved for Encryption options
-      # @return [Ably::Rest::Channel}
+      #
+      # @return [Ably::Rest::Channel]
+      #
       def get(*args)
         super
       end
 
-      # @!method fetch(name, &missing_block)
       # Return a {Ably::Rest::Channel} for the given name if it exists, else the block will be called.
       # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
       #
       # @param name [String] The name of the channel
       # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
       # @yieldparam [String] name of the missing channel
+      #
       # @return [Ably::Rest::Channel]
+      #
       def fetch(*args)
         super
       end
@@ -36,6 +38,7 @@ module Ably
       # {Ably::Rest::Channel} object. Explicitly release channels to free up resources if required
       #
       # @return [void]
+      #
       def release(*args)
         super
       end

data/lib/ably/rest/client.rb

@@ -10,12 +10,7 @@ require 'ably/rest/middleware/exceptions'
 
 module Ably
   module Rest
-    # Client for the Ably REST API
-    #
-    # @!attribute [r] client_id
-    #   @return [String] A client ID, used for identifying this client for presence purposes
-    # @!attribute [r] auth_options
-    #   @return [Hash] {Ably::Auth} options configured for this client
+    # A client that offers a simple stateless API to interact directly with Ably's REST API.
     #
     class Client
       include Ably::Modules::Conversions
@@ -59,11 +54,13 @@ module Ably
       # @return [String]
       attr_reader :agent
 
-      # {Ably::Auth} authentication object configured for this connection
+      # An {Ably::Auth} object.
+      # @spec RSC5
       # @return [Ably::Auth]
       attr_reader :auth
 
-      # The collection of {Ably::Rest::Channel}s that have been created
+      # A {Ably::Rest::Channels} object.
+      # @spec RSN1
       # @return [Aby::Rest::Channels]
       attr_reader :channels
 
@@ -127,9 +124,11 @@ module Ably
       # @return [Integer]
       attr_reader :max_frame_size
 
-      # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection.
+      # Constructs a {Ably::Rest::Client} object using an Ably API key or token string.
+      #
+      # @spec RSC1
       #
-      # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID
+      # @param [Hash,String] options an options Hash or String used to configure the client and the authentication, or String with an API key or Token ID
       # @option options [Boolean]                 :tls                 (true) When false, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections.
       # @option options [String]                  :key                 API key comprising the key name and key secret in a single string
       # @option options [String]                  :token               Token string or {Models::TokenDetails} used to authenticate requests
@@ -167,10 +166,10 @@ module Ably
       # @return [Ably::Rest::Client]
       #
       # @example
-      #    # create a new client authenticating with basic auth
+      #    # Create a new client authenticating with basic auth using a String object
       #    client = Ably::Rest::Client.new('key.id:secret')
       #
-      #    # create a new client and configure a client ID used for presence
+      #    # Construct a RestClient object using a Hash object.
       #    client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options)
@@ -275,16 +274,18 @@ module Ably
         channels.get(name, channel_options)
       end
 
-      # Retrieve the Stats for the application
+      # Queries the REST /stats API and retrieves your application's usage statistics. Returns a {Ably::Models::PaginatedResult} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs.
+      #
+      # @spec RSC6a, RSC6b1, RSC6b2, RSC6b3, RSC6b4
       #
       # @param [Hash] options the options for the stats request
-      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any stats retrieved is +:start+
-      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any stats retrieved is +:end+
-      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
-      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
-      # @option options [Symbol]       :unit       `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute`
+      # @option options [Integer,Time] :start      The time from which stats are retrieved, specified as milliseconds since the Unix epoch. RSC6b1
+      # @option options [Integer,Time] :end        The time until stats are retrieved, specified as milliseconds since the Unix epoch. RSC6b1
+      # @option options [Symbol]       :direction  The order for which stats are returned in. Valid values are backwards which orders stats from most recent to oldest, or forwards which orders stats from oldest to most recent. The default is backwards. RSC6b2
+      # @option options [Integer]      :limit      An upper limit on the number of stats returned. The default is 100, and the maximum is 1000. RSC6b3
+      # @option options [Symbol]       :unit       minute, hour, day or month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query. RSC6b4
       #
-      # @return [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats
+      # @return [Ably::Models::PaginatedResult<Ably::Models::Stats>] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::Stats} objects.
       #
       def stats(options = {})
         options = {
@@ -306,9 +307,13 @@ module Ably
         Ably::Models::PaginatedResult.new(response, url, self, paginated_options)
       end
 
-      # Retrieve the Ably service time
+      # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access
+      # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequest} with
+      # a more accurate timestamp should use the {Ably::Rest::Client#queryTime} property instead of this method.
       #
-      # @return [Time] The time as reported by the Ably service
+      # @spec RSC16
+      #
+      # @return [Time] The time as milliseconds since the Unix epoch.
       def time
         response = get('/time', {}, send_auth_header: false)
 
@@ -357,20 +362,19 @@ module Ably
         raw_request(:delete, path, params, options)
       end
 
-      # Perform an HTTP request to the Ably API
-      # This is a convenience for customers who wish to use bleeding edge REST API functionality
-      # that is either not documented or is not included in the API for our client libraries.
-      # The REST client library provides a function to issue HTTP requests to the Ably endpoints
-      # with all the built in functionality of the library such as authentication, paging,
-      # fallback hosts, MsgPack and JSON support etc.
+      # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API
+      # functionality that is either not documented or is not yet included in the public API, without having to directly
+      # handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
+      #
+      # @spec RSC19
       #
-      # @param method  [Symbol]    The HTTP method symbol such as +:get+, +:post+, +:put+
-      # @param path    [String]    The path of the URL such +/channel/foo/publish+
-      # @param params  [Hash, nil] Optional querystring params
-      # @param body    [Hash, nil] Optional body for the POST or PUT request, must be nil or a JSON-like object
-      # @param headers [Hash, nil] Optional additional headers
+      # @param method  [Symbol]    The request method to use, such as :get, :post.
+      # @param path    [String]    The request path.
+      # @param params  [Hash, nil] The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the REST API reference for the available parameters of each endpoint.
+      # @param body    [Hash, nil] The JSON body of the request.
+      # @param headers [Hash, nil] Additional HTTP headers to include in the request.
       #
-      # @return [Ably::Models::HttpPaginatedResponse<>]
+      # @return [Ably::Models::HttpPaginatedResponse<>] An {Ably::Models::HttpPaginatedResponse} object returned by the HTTP request, containing an empty or JSON-encodable object.
       def request(method, path, params = {}, body = nil, headers = {}, options = {})
         raise "Method #{method.to_s.upcase} not supported" unless %i(get put patch post delete).include?(method.to_sym)
 
@@ -408,7 +412,8 @@ module Ably
         Models::HttpPaginatedResponse.new(response, path, self)
       end
 
-      # The local device detilas
+      # Retrieves an object that represents the current state of the device as a target for push notifications.
+      # @spec RSH8
       # @return [Ably::Models::LocalDevice]
       #
       # @note This is unsupported in the Ruby library
@@ -416,7 +421,8 @@ module Ably
         raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. The local device object is not unavailable'
       end
 
-      # Push notification object for publishing and managing push notifications
+      # A {Ably::Rest::Push} object.
+      # @spec RSH7
       # @return [Ably::Rest::Push]
       def push
         @push ||= Push.new(self)

data/lib/ably/rest/presence.rb

@@ -1,34 +1,45 @@
 module Ably
   module Rest
+    # Enables the retrieval of the current and historic presence set for a channel.
+    #
     class Presence
       include Ably::Modules::Conversions
 
       # {Ably::Rest::Client} for this Presence object
+      #
       # @return {Ably::Rest::Client}
+      #
       # @private
       attr_reader :client
 
       # {Ably::Rest::Channel} this Presence object is associated with
-      # @return {Ably::Rest::Channel}
+      #
+      # @return [Ably::Rest::Channel]
+      #
       attr_reader :channel
 
       # Initialize a new Presence object
       #
       # @param client [Ably::Rest::Client]
       # @param channel [Channel] The channel object
+      #
       def initialize(client, channel)
         @client  = client
         @channel = channel
       end
 
-      # Obtain the set of members currently present for a channel
+      # Retrieves the current members present on the channel and the metadata for each member, such as their
+      # {Ably::Models::PresenceMessage::ACTION} and ID. Returns a {Ably::Models::PaginatedResult} object,
+      # containing an array of {Ably::Models::PresenceMessage} objects.
+      #
+      # @spec RSPa, RSP3a, RSP3a2, RSP3a3
       #
       # @param [Hash] options the options for the set of members present
-      # @option options [Integer]   :limit           Maximum number of members to retrieve up to 1,000, defaults to 100
-      # @option options [String]    :client_id       optional client_id filter for the member
-      # @option options [String]    :connection_id   optional connection_id filter for the member
+      # @option options [Integer]   :limit           An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. (RSP3a)
+      # @option options [String]    :client_id       Filters the list of returned presence members by a specific client using its ID. (RSP3a2)
+      # @option options [String]    :connection_id   Filters the list of returned presence members by a specific connection using its ID. (RSP3a3)
       #
-      # @return [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}.
+      # @return [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PresenceMessage} objects.
       #
       def get(options = {})
         options = options = {
@@ -49,15 +60,19 @@ module Ably
         end
       end
 
-      # Return the presence messages history for the channel
+      # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical {Ably::Models::PresenceMessage}
+      # objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved
+      # from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past.
+      #
+      # @spec RSP4a
       #
       # @param [Hash] options the options for the message history request
-      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any presence messages retrieved is +:start+
-      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any presence messages retrieved is +:end+
-      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
-      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
+      # @option options [Integer,Time] :start      The time from which messages are retrieved, specified as milliseconds since the Unix epoch. (RSP4b1)
+      # @option options [Integer,Time] :end        The time until messages are retrieved, specified as milliseconds since the Unix epoch. (RSP4b1)
+      # @option options [Symbol]       :direction  The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. (RSP4b2)
+      # @option options [Integer]      :limit      An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. (RSP4b3)
       #
-      # @return [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}.
+      # @return [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PresenceMessage} objects.
       #
       def history(options = {})
         url = "#{base_path}/history"

data/lib/ably/rest/push/admin.rb

@@ -39,13 +39,17 @@ module Ably::Rest
       end
 
       # Manage device registrations
+      #
       # @return [Ably::Rest::Push::DeviceRegistrations]
+      #
       def device_registrations
         @device_registrations ||= DeviceRegistrations.new(self)
       end
 
       # Manage channel subscriptions for devices or clients
+      #
       # @return [Ably::Rest::Push::ChannelSubscriptions]
+      #
       def channel_subscriptions
         @channel_subscriptions ||= ChannelSubscriptions.new(self)
       end

data/lib/ably/rest/push/device_registrations.rb

@@ -17,6 +17,8 @@ module Ably::Rest
 
       # Get registered device by device ID
       #
+      # @spec RSH1b1
+      #
       # @param [String, Ably::Models::DeviceDetails] device_id   the device to retrieve
       #
       # @return [Ably::Models::DeviceDetails]  Returns {Ably::Models::DeviceDetails} if a match is found else a {Ably::Exceptions::ResourceMissing} is raised
@@ -30,6 +32,8 @@ module Ably::Rest
 
       # List registered devices filtered by optional params
       #
+      # @spec RSH1b2
+      #
       # @param [Hash] params   the filter options for the list registered device request
       # @option params [String]   :client_id  filter by devices registered to a client identifier. Cannot be used with +device_id+ param
       # @option params [String]   :device_id  filter by unique device ID. Cannot be used with +client_id+ param
@@ -54,7 +58,10 @@ module Ably::Rest
         Ably::Models::PaginatedResult.new(response, '', client, paginated_options)
       end
 
-      # Save and register device
+      # Registers or updates a {Ably::Models::DeviceDetails} object with Ably.
+      # Returns the new, or updated {Ably::Models::DeviceDetails} object.
+      #
+      # @spec RSH1b3
       #
       # @param [Ably::Models::DeviceDetails, Hash]  device   the device details to save
       #
@@ -69,6 +76,8 @@ module Ably::Rest
 
       # Remove device
       #
+      # @spec RSH1b4
+      #
       # @param [String, Ably::Models::DeviceDetails]  device_id  the device to remove
       #
       # @return [void]
@@ -80,7 +89,9 @@ module Ably::Rest
         client.delete("/push/deviceRegistrations/#{device_id}", {})
       end
 
-      # Remove device matching where params
+      # Removes all devices registered to receive push notifications from Ably matching the filter params provided.
+      #
+      # @spec RSH1b5
       #
       # @param [Hash] params   the filter params for the remove request
       # @option params [String]   :client_id  remove devices registered to a client identifier. Cannot be used with +device_id+ param

data/lib/ably/rest/push.rb

@@ -14,7 +14,9 @@ module Ably
       end
 
       # Admin features for push notifications like managing devices and channel subscriptions
+      #
       # @return [Ably::Rest::Push::Admin]
+      #
       def admin
         @admin ||= Admin.new(self)
       end

data/lib/ably/util/crypto.rb

@@ -2,6 +2,8 @@ require 'msgpack'
 require 'openssl'
 
 module Ably::Util
+  # Contains the properties required to configure the encryption of {Ably::Models::Message} payloads.
+  #
   class Crypto
     DEFAULTS = {
       algorithm: 'aes',
@@ -14,6 +16,7 @@ module Ably::Util
     # Configured {Ably::Models::CipherParams} for this Crypto object, see {#initialize} for a list of configureable options
     #
     # @return [Ably::Models::CipherParams]
+    #
     attr_reader :cipher_params
 
     # Creates a {Ably::Util::Crypto} object
@@ -34,13 +37,12 @@ module Ably::Util
       @cipher_params = Ably::Models::CipherParams(params)
     end
 
-    # Obtain a default {Ably::Models::CipherParams}. This uses default algorithm, mode and
-    # padding and key length. An IV is generated using the default
-    # system SecureRandom; the key may be obtained from the returned {Ably::Models::CipherParams}
-    # for out-of-band distribution to other clients.
-
+    # Returns a {Ably::Models::CipherParams} object, using the default values for any fields not supplied by the `Hash` object.
+    #
+    # @spec RSE1, RSE1b, RSE1b
+    #
     # @param [Hash]  params  a Hash used to configure the Crypto library's {Ably::Models::CipherParams}
-    # @option params  (see Ably::Models::CipherParams#initialize)
+    # @option params  (see {Ably::Models::CipherParams#initialize})
     #
     # @return [Ably::Models::CipherParams]   Configured cipher params with :key, :algorithm, :mode, :key_length attributes
     #
@@ -48,11 +50,13 @@ module Ably::Util
       Ably::Models::CipherParams(params)
     end
 
-    # Generate a random encryption key from the supplied keylength (or the
-    # default key_length of 256 if none supplied)
+    # Generates a random key to be used in the encryption of the channel. If the language cryptographic randomness
+    # primitives are blocking or async, a callback is used. The callback returns a generated binary key.
+    #
+    # @spec RSE2, RSE2a, RSE2b
     #
-    # @param  [Integer]  key_length  Optional (default 256) key length for the generated random key. 128 and 256 bit key lengths are supported
-    # @return   Binary   String (byte array) with ASCII_8BIT encoding
+    # @param  [Integer]  key_length  The length of the key, in bits, to be generated. If not specified, this is equal to the default keyLength of the default algorithm: for AES this is 256 bits.
+    # @return   Binary   The key as a binary, for example, a byte array.
     #
     def self.generate_random_key(key_length = DEFAULTS.fetch(:key_length))
       params = DEFAULTS.merge(key_length: key_length)

data/lib/ably/version.rb

@@ -1,5 +1,5 @@
 module Ably
-  VERSION = '1.2.1'
+  VERSION = '1.2.3'
   PROTOCOL_VERSION = '1.2'
 
   # @api private

data/spec/acceptance/realtime/connection_spec.rb

@@ -1620,21 +1620,6 @@ describe Ably::Realtime::Connection, :event_machine do
           end
         end
 
-        context 'with invalid formatted value sent to server' do
-          let(:client_options) { default_options.merge(recover: 'not-a-valid-connection-key:1:0', log_level: :none) }
-
-          it 'sets the #error_reason and moves the connection to FAILED' do
-            connection.once(:failed) do |state_change|
-              expect(connection.state).to eq(:failed)
-              expect(state_change.reason.message).to match(/Invalid connectionKey/i)
-              expect(connection.error_reason.message).to match(/Invalid connectionKey/i)
-              expect(connection.error_reason.code).to eql(80018)
-              expect(connection.error_reason).to eql(state_change.reason)
-              stop_reactor
-            end
-          end
-        end
-
         context 'with expired (missing) value sent to server' do
           let(:client_options) { default_options.merge(recover: 'wVIsgTHAB1UvXh7z-1991d8586:0:0', log_level: :fatal) }
 

data/spec/acceptance/realtime/message_spec.rb

@@ -523,7 +523,7 @@ describe 'Ably::Realtime::Channel Message', :event_machine do
 
       resources_root = File.expand_path('../../../../lib/submodules/ably-common/test-resources', __FILE__)
 
-      def self.add_tests_for_data(data)
+      shared_examples 'add_tests_for_data' do |data|
         data['items'].each_with_index do |item, index|
           context "item #{index} with encrypted encoding #{item['encrypted']['encoding']}" do
             it_behaves_like 'an Ably encrypter and decrypter', item, data
@@ -533,12 +533,12 @@ describe 'Ably::Realtime::Channel Message', :event_machine do
 
       context 'with AES-128-CBC using crypto-data-128.json fixtures (#RTL7d)' do
         data = JSON.parse(File.read(File.join(resources_root, 'crypto-data-128.json')))
-        add_tests_for_data data
+        include_examples 'add_tests_for_data', data
       end
 
       context 'with AES-256-CBC using crypto-data-256.json fixtures (#RTL7d)' do
         data = JSON.parse(File.read(File.join(resources_root, 'crypto-data-256.json')))
-        add_tests_for_data data
+        include_examples 'add_tests_for_data', data
       end
 
       context 'with multiple sends from one client to another' do

data/spec/acceptance/rest/channel_spec.rb

@@ -595,5 +595,23 @@ describe Ably::Rest::Channel do
         expect(channel.presence).to be_a(Ably::Rest::Presence)
       end
     end
+
+    context '#status' do
+      let(:channel_name) { "persisted:#{random_str(4)}" }
+      let(:channel) { client.channel(channel_name) }
+      let(:channel_details) { channel.status }
+
+      it 'should return channel details status (#RSL8, #RSL8a)' do
+        expect(channel_details.channel_id).to eq(channel_name)
+        expect(channel_details.name).to eq(channel_name)
+        expect(channel_details.status).to be_a(Ably::Models::ChannelStatus)
+        expect(channel_details.status.is_active).to eq(true)
+        expect(channel_details.status.occupancy.metrics.publishers).to eq(0)
+        expect(channel_details.status.occupancy.metrics.subscribers).to eq(0)
+        expect(channel_details.status.occupancy.metrics.presence_connections).to eq(0)
+        expect(channel_details.status.occupancy.metrics.presence_members).to eq(0)
+        expect(channel_details.status.occupancy.metrics.presence_subscribers).to eq(0)
+      end
+    end
   end
 end