ably-pubsub-core 0.0.1.pre

data/lib/ably/models/channel_state_change.rb

@@ -0,0 +1,84 @@
+module Ably::Models
+  # Contains state change information emitted by {Ably::Rest::Channel} and {Ably::Realtime::Channel} objects.
+  #
+  class ChannelStateChange
+    include Ably::Modules::ModelCommon
+
+    def initialize(hash_object)
+      unless (hash_object.keys - [:current, :previous, :event, :reason, :resumed, :protocol_message]).empty?
+        raise ArgumentError, 'Invalid attributes, expecting :current, :previous, :event, :reason, :resumed'
+      end
+
+      @hash_object = {
+        current: hash_object.fetch(:current),
+        previous: hash_object.fetch(:previous),
+        event: hash_object[:event],
+        reason: hash_object[:reason],
+        protocol_message: hash_object[:protocol_message],
+        resumed: hash_object[:resumed]
+      }
+    rescue KeyError => e
+      raise ArgumentError, e
+    end
+
+    # The new current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def current
+      @hash_object[:current]
+    end
+
+    # The previous state. For the {Ably::Realtime::Channel::EVENT}(:update) event, this is equal to the current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::EVENT]
+    #
+    def previous
+      @hash_object[:previous]
+    end
+
+    # The event that triggered this {Ably::Realtime::Channel::STATE} change.
+    #
+    # @spec TH5
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def event
+      @hash_object[:event]
+    end
+
+    # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
+    #
+    # @spec RTL2e, TH3
+    #
+    # @return [Ably::Models::ErrorInfo, nil]
+    #
+    def reason
+      @hash_object[:reason]
+    end
+
+    # Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.
+    #
+    # @spec RTL2f, TH4
+    #
+    # @return [Boolean]
+    #
+    def resumed
+      !!@hash_object[:resumed]
+    end
+    alias_method :resumed?, :resumed
+
+    # @api private
+    def protocol_message
+      @hash_object[:protocol_message]
+    end
+
+    def to_s
+      "<ChannelStateChange: current state #{current}, previous state #{previous}>"
+    end
+  end
+end

data/lib/ably/models/channel_status.rb

@@ -0,0 +1,63 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelStatus} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelStatus]
+  #
+  def self.ChannelStatus(attributes)
+    case attributes
+    when ChannelStatus
+      return attributes
+    else
+      ChannelStatus.new(attributes)
+    end
+  end
+
+  # Contains the status of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
+  # such as whether it is active and its {Ably::Models::ChannelOccupancy}.
+  #
+  # @spec CHS1
+  #
+  class ChannelStatus
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    # The attributes of ChannelStatus
+    #
+    # @spec CHS2
+    #
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    # Initialize a new ChannelStatus
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+    end
+
+    # If true, the channel is active, otherwise false.
+    #
+    # @spec CHS2a
+    #
+    # @return [Boolean]
+    #
+    def is_active
+      attributes[:isActive]
+    end
+    alias_method :active?, :is_active
+    alias_method :is_active?, :is_active
+
+    # A {Ably::Models::ChannelOccupancy} object.
+    #
+    # @spec CHS2b
+    #
+    # @return [Ably::Models::ChannelOccupancy, nil]
+    #
+    def occupancy
+      Ably::Models::ChannelOccupancy(attributes[:occupancy])
+    end
+  end
+end

data/lib/ably/models/cipher_params.rb

@@ -0,0 +1,137 @@
+require 'base64'
+require 'ably/util/crypto'
+
+module Ably::Models
+  # Convert cipher param attributes to a {CipherParams} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [CipherParams]
+  #
+  def self.CipherParams(attributes)
+    case attributes
+    when CipherParams
+      return attributes
+    else
+      CipherParams.new(attributes || {})
+    end
+  end
+
+  # Sets the properties to configure encryption for a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
+  #
+  class CipherParams
+    include Ably::Modules::ModelCommon
+
+    # @param params [Hash]
+    # @option params [String,Binary]  :key         Required private key must be either a binary (e.g. a ASCII_8BIT encoded string), or a base64-encoded string. If the key is a base64-encoded string, the it will be automatically converted into a binary
+    # @option params [String]         :algorithm   optional (default AES), specify the encryption algorithm supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
+    # @option params [String]         :mode        optional (default CBC), specify the cipher mode supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
+    # @option params [Integer]        :key_length  optional (default 128), specify the key length of the cipher supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
+    # @option params [String]         :combined    optional (default AES-128-CBC), specify in one option the algorithm, key length and cipher of the cipher supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
+    #
+    def initialize(params = {})
+      @attributes = IdiomaticRubyWrapper(params.clone)
+
+      raise Ably::Exceptions::CipherError, ':key param is required' unless attributes[:key]
+      raise Ably::Exceptions::CipherError, ':key param must be a base64-encoded string or byte array (ASCII_8BIT enocdede string)' unless key.kind_of?(String)
+      attributes[:key] = decode_key(key) if key.kind_of?(String) && key.encoding != Encoding::ASCII_8BIT
+
+      if attributes[:combined]
+        match = /(?<algorithm>\w+)-(?<key_length>\d+)-(?<mode>\w+)/.match(attributes[:combined])
+        raise Ably::Exceptions::CipherError, "Invalid :combined param, expecting format such as AES-256-CBC" unless match
+        attributes[:algorithm] = match[:algorithm]
+        attributes[:key_length] = match[:key_length].to_i
+        attributes[:mode] = match[:mode]
+      end
+
+      if attributes[:key_length] && (key_length != attributes[:key_length])
+        raise Ably::Exceptions::CipherError, "Incompatible :key length of #{key_length} and provided :key_length of #{attributes[:key_length]}"
+      end
+
+      if algorithm == 'aes' && mode == 'cbc'
+        unless [128, 256].include?(key_length)
+          raise Ably::Exceptions::CipherError, "Unsupported key length #{key_length} for aes-cbc encryption. Encryption key must be 128 or 256 bits (16 or 32 ASCII characters)"
+        end
+      end
+
+      attributes.freeze
+    end
+
+    # The Cipher algorithm string such as AES-128-CBC
+    #
+    # @param [Hash]  params  Hash containing :algorithm, :key_length and :mode key values
+    #
+    # @return [String]
+    #
+    def self.cipher_type(params)
+      "#{params[:algorithm]}-#{params[:key_length]}-#{params[:mode]}".to_s.upcase
+    end
+
+    # The algorithm to use for encryption. Only AES is supported and is the default value.
+    #
+    # @spec TZ2a
+    #
+    # @return [String]
+    #
+    def algorithm
+      attributes.fetch(:algorithm) do
+        Ably::Util::Crypto::DEFAULTS.fetch(:algorithm)
+      end.downcase
+    end
+
+    # The private key used to encrypt and decrypt payloads.
+    #
+    # @spec TZ2d
+    #
+    # @return [Binary]
+    #
+    def key
+      attributes[:key]
+    end
+
+    # The length of the key in bits; for example 128 or 256.
+    #
+    # @spec TZ2b
+    #
+    # @return [Integer]
+    #
+    def key_length
+      key.unpack('b*').first.length
+    end
+
+    # The cipher mode. Only CBC is supported and is the default value.
+    #
+    # @spec TZ2c
+    #
+    # @return [String]
+    #
+    def mode
+      attributes.fetch(:mode) do
+        Ably::Util::Crypto::DEFAULTS.fetch(:mode)
+      end.downcase
+    end
+
+    # The complete Cipher algorithm string such as AES-128-CBC
+    #
+    # @return [String]
+    #
+    def cipher_type
+      self.class.cipher_type(algorithm: algorithm, key_length: key_length, mode: mode)
+    end
+
+    # Access the token details Hash object ruby'fied to use symbolized keys
+    #
+    # @return [Hash]
+    #
+    def attributes
+      @attributes
+    end
+
+    private
+
+    def decode_key(encoded_key)
+      normalised_key = encoded_key.gsub('_', '/').gsub('-', '+')
+      Base64.decode64(normalised_key)
+    end
+  end
+end

data/lib/ably/models/connection_details.rb

@@ -0,0 +1,149 @@
+module Ably::Models
+  # Convert connection details attributes to a {ConnectionDetails} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ConnectionDetails]
+  #
+  def self.ConnectionDetails(attributes)
+    case attributes
+    when ConnectionDetails
+      return attributes
+    else
+      ConnectionDetails.new(attributes || {})
+    end
+  end
+
+  # Contains any constraints a client should adhere to and provides additional metadata about a {Ably::Realtime::Connection},
+  # such as if a request to {Ably::Realtime::Client#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably.
+  #
+  class ConnectionDetails
+    include Ably::Modules::ModelCommon
+
+    # Max message size
+    MAX_MESSAGE_SIZE = 65536 # See spec TO3l8
+
+    # Max frame size
+    MAX_FRAME_SIZE = 524288 # See spec TO3l9
+
+    # @param attributes [Hash]
+    # @option attributes [String]    :client_id             Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed for all operations from this client.
+    # @option attributes [String]    :connection_key        the connection secret key string that is used to resume a connection and its state
+    # @option attributes [Integer]   :max_message_size      maximum individual message size in bytes
+    # @option attributes [Integer]   :max_frame_size        maximum size for a single frame of data sent to Ably. This restriction applies to a {Ably::Models::ProtocolMessage} sent over a realtime connection, or the total body size for a REST request
+    # @option attributes [Integer]   :max_inbound_rate      maximum allowable number of requests per second from a client
+    # @option attributes [Integer]   :max_idle_interval     is the maximum length of time in seconds that the server will allow no activity to occur in the server->client direction. After such a period of inactivity, the server will send a @HEARTBEAT@ or transport-level ping to the client. If the value is 0, the server will allow arbitrarily-long levels of inactivity.
+    # @option attributes [Integer]   :connection_state_ttl  duration in seconds that Ably will persist the connection state when a Realtime client is abruptly disconnected
+    # @option attributes [String]    :server_id             unique identifier of the Ably server where the connection is established
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+      [:connection_state_ttl, :max_idle_interval].each do |duration_field|
+        if self.attributes[duration_field]
+          self.attributes[duration_field] = (self.attributes[duration_field].to_f / 1000).round
+        end
+      end
+      self.attributes[:max_message_size] ||= MAX_MESSAGE_SIZE
+      self.attributes[:max_frame_size] ||= MAX_FRAME_SIZE
+      self.attributes.freeze
+    end
+
+    # Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from
+    # assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted
+    # to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed
+    # for all operations from this client.
+    #
+    # @spec RSA12a, CD2a
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The connection secret key string that is used to resume a connection and its state.
+    #
+    # @spec RTN15e, CD2b
+    #
+    # @return [String]
+    #
+    def connection_key
+      attributes[:connection_key]
+    end
+
+    # The duration that Ably will persist the connection state for when a Realtime client is abruptly disconnected.
+    #
+    # @spec CD2f, RTN14e, DF1a
+    #
+    # @return [Integer]
+    #
+    def connection_state_ttl
+      attributes[:connection_state_ttl]
+    end
+
+    # Overrides the default maxFrameSize.
+    #
+    # @spec CD2d
+    #
+    # @return [Integer]
+    #
+    def max_frame_size
+      attributes[:max_frame_size]
+    end
+
+    # The maximum allowable number of requests per second from a client or Ably. In the case of a realtime connection,
+    # this restriction applies to the number of messages sent, whereas in the case of REST, it is the total number of REST requests per second.
+    #
+    # @spec CD2e
+    #
+    # @return [Integer]
+    #
+    def max_inbound_rate
+      attributes[:max_inbound_rate]
+    end
+
+    # The maximum message size is an attribute of an Ably account and enforced by Ably servers.
+    # maxMessageSize indicates the maximum message size allowed by the Ably account this connection is using.
+    # Overrides the default value of ClientOptions.maxMessageSize.
+    #
+    # @spec CD2c
+    #
+    # @return [Integer]
+    #
+    def max_message_size
+      attributes[:max_message_size]
+    end
+
+    # A unique identifier for the front-end server that the client has connected to. This server ID is only used for the purposes of debugging.
+    #
+    # @spec CD2g
+    #
+    # @return [String]
+    #
+    def server_id
+      attributes[:server_id]
+    end
+
+    # The maximum length of time in milliseconds that the server will allow no activity to occur in the server to client direction.
+    # After such a period of inactivity, the server will send a HEARTBEAT or transport-level ping to the client.
+    # If the value is 0, the server will allow arbitrarily-long levels of inactivity.
+    #
+    # @spec CD2h
+    #
+    # @return [Integer]
+    #
+    def max_idle_interval
+      attributes[:max_idle_interval]
+    end
+
+    def has_client_id?
+      attributes.has_key?(:client_id)
+    end
+
+    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    #
+    def attributes
+      @hash_object
+    end
+  end
+end

data/lib/ably/models/connection_state_change.rb

@@ -0,0 +1,83 @@
+module Ably::Models
+  # Contains {Ably::Models::ConnectionState} change information emitted by the {Ably::Realtime::Connection} object.
+  #
+  class ConnectionStateChange
+    include Ably::Modules::ModelCommon
+
+    def initialize(hash_object)
+      unless (hash_object.keys - [:current, :previous, :event, :retry_in, :reason, :protocol_message]).empty?
+        raise ArgumentError, 'Invalid attributes, expecting :current, :previous, :event, :retry_in, :reason'
+      end
+
+      @hash_object = {
+        current: hash_object.fetch(:current),
+        previous: hash_object.fetch(:previous),
+        event: hash_object[:event],
+        retry_in: hash_object[:retry_in],
+        reason: hash_object[:reason],
+        protocol_message: hash_object[:protocol_message]
+      }
+    rescue KeyError => e
+      raise ArgumentError, e
+    end
+
+    # The new {Ably::Realtime::Connection::STATE}.
+    #
+    # @spec TA2
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def current
+      @hash_object[:current]
+    end
+
+    # The event that triggered this {Ably::Realtime::Connection::EVENT} change.
+    #
+    # @spec TA5
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def event
+      @hash_object[:event]
+    end
+
+    # The previous {Ably::Models::Connection::STATE}. For the {Ably::Models::Connection::EVENT} UPDATE event,
+    # this is equal to the current {Ably::Models::Connection::STATE}.
+    #
+    # @spec TA2
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def previous
+      @hash_object[:previous]
+    end
+
+    # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
+    #
+    # @spec RTN4f, TA3
+    #
+    # @return [Ably::Models::ErrorInfo, nil]
+    #
+    def reason
+      @hash_object[:reason]
+    end
+
+    # Duration in milliseconds, after which the client retries a connection where applicable.
+    #
+    # @spec RTN14d, TA2
+    #
+    # @return [Integer]
+    #
+    def retry_in
+      @hash_object[:retry_in]
+    end
+
+    def protocol_message
+      @hash_object[:protocol_message]
+    end
+
+    def to_s
+      "<ConnectionStateChange: current state #{current}, previous state #{previous}>"
+    end
+  end
+end

data/lib/ably/models/delta_extras.rb

@@ -0,0 +1,28 @@
+module Ably::Models
+  # Contains any arbitrary key-value pairs, which may also contain other primitive JSON types, JSON-encodable objects,
+  # or JSON-encodable arrays from delta compression.
+  #
+  class DeltaExtras
+    include Ably::Modules::ModelCommon
+
+    # The ID of the message the delta was generated from.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :from
+
+    # The delta compression format. Only vcdiff is supported.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :format
+
+    def initialize(attributes = {})
+      @from, @format = IdiomaticRubyWrapper((attributes || {}), stop_at: [:from, :format]).attributes.values_at(:from, :format)
+    end
+
+    def to_json(*args)
+      as_json(args).to_json
+    end
+  end
+end

data/lib/ably/models/device_details.rb

@@ -0,0 +1,126 @@
+module Ably::Modules
+  module Conversions
+    private
+    # Convert device_details argument to a {Ably::Models::DeviceDetails} object
+    #
+    # @param device_details [Ably::Models::DeviceDetails,Hash,nil] A device details object
+    #
+    # @return [Ably::Models::DeviceDetails]
+    #
+    def DeviceDetails(device_details)
+      case device_details
+      when Ably::Models::DeviceDetails
+        device_details
+      else
+        Ably::Models::DeviceDetails.new(device_details)
+      end
+    end
+  end
+end
+
+module Ably::Models
+  # Contains the properties of a device registered for push notifications.
+  #
+  class DeviceDetails < Ably::Exceptions::BaseAblyException
+    include Ably::Modules::ModelCommon
+
+    # @param hash_object   [Hash,nil]  Device detail attributes
+    #
+    def initialize(hash_object = {})
+      @raw_hash_object = hash_object || {}
+      @hash_object     = IdiomaticRubyWrapper(hash_object)
+    end
+
+    # A unique ID generated by the device.
+    #
+    # @spec PCD2
+    #
+    def id
+      attributes[:id]
+    end
+
+    # The DevicePlatform associated with the device.
+    # Describes the platform the device uses, such as android or ios.
+    #
+    # @spec PCD6
+    #
+    # @return [String]
+    #
+    def platform
+      attributes[:platform]
+    end
+
+    # The client ID the device is connected to Ably with.
+    #
+    # @spec PCD3
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The DeviceFormFactor object associated with the device.
+    # Describes the type of the device, such as phone or tablet.
+    #
+    # @spec PCD4
+    #
+    # @return [String]
+    #
+    def form_factor
+      attributes[:form_factor]
+    end
+
+    def device_secret
+      attributes[:device_secret]
+    end
+
+    %w(id platform form_factor client_id device_secret).each do |attribute|
+      define_method "#{attribute}=" do |val|
+        unless val.nil? || val.kind_of?(String)
+          raise ArgumentError, "#{attribute} must be nil or a string value"
+        end
+        attributes[attribute.to_sym] = val
+      end
+    end
+
+    # A JSON object of key-value pairs that contains metadata for the device.
+    #
+    # @spec PCD5
+    #
+    # @return [Hash, nil]
+    #
+    def metadata
+      attributes[:metadata] || {}
+    end
+
+    def metadata=(val)
+      unless val.nil? || val.kind_of?(Hash)
+        raise ArgumentError, "metadata must be nil or a Hash value"
+      end
+      attributes[:metadata] = val
+    end
+
+    # The {Ably::Models::DevicePushDetails} object associated with the device.
+    # Describes the details of the push registration of the device.
+    #
+    # @spec PCD7
+    #
+    # @return [Ably::Models::DevicePushDetails]
+    #
+    def push
+      DevicePushDetails(attributes[:push] || {})
+    end
+
+    def push=(val)
+      unless val.nil? || val.kind_of?(Hash) || val.kind_of?(Ably::Models::DevicePushDetails)
+        raise ArgumentError, "push must be nil, a Hash value or a DevicePushDetails object"
+      end
+      attributes[:push] = DevicePushDetails(val)
+    end
+
+    def attributes
+      @hash_object
+    end
+  end
+end