ably-pubsub-core 0.0.1.pre

data/lib/ably/models/stats_types.rb

@@ -0,0 +1,107 @@
+module Ably::Models
+  class Stats
+    # StatsStruct is a basic Struct like class that allows methods to be defined
+    # on the class that will be retuned co-erced objects from the underlying hash used to
+    # initialize the object.
+    #
+    # This class provides a concise way to create classes that have fixed attributes and types
+    #
+    # @example
+    #   class MessageCount < StatsStruct
+    #     coerce_attributes :count, :data, into: Integer
+    #   end
+    #
+    # @api private
+    #
+    class StatsStruct
+      class << self
+        def coerce_attributes(*attributes)
+          options = attributes.pop
+          raise ArgumentError, 'Expected attribute into: within options hash' unless options.kind_of?(Hash) && options[:into]
+
+          @type_klass = options[:into]
+          setup_attribute_methods attributes
+        end
+
+        def type_klass
+          @type_klass
+        end
+
+        private
+        def setup_attribute_methods(attributes)
+          attributes.each do |attr|
+            define_method(attr) do
+              # Lazy load the co-erced value only when accessed
+              unless instance_variable_defined?("@#{attr}")
+                instance_variable_set "@#{attr}", self.class.type_klass.new(hash[attr.to_sym])
+              end
+              instance_variable_get("@#{attr}")
+            end
+          end
+        end
+      end
+
+      attr_reader :hash
+
+      def initialize(hash)
+        @hash = hash || {}
+      end
+    end
+
+    # IntegerDefaultZero will always return an Integer object and will default to value 0 unless truthy
+    #
+    # @api private
+    #
+    class IntegerDefaultZero
+      def self.new(value)
+        (value && value.to_i) || 0
+      end
+    end
+
+    # MessageCount contains aggregate counts for messages and data transferred
+    #
+    # @spec TS5a, TS5b
+    #
+    class MessageCount < StatsStruct
+      coerce_attributes :count, :data, into: IntegerDefaultZero
+    end
+
+    # RequestCount contains aggregate counts for requests made
+    #
+    # @spec TS8a, TS8b, TS8c
+    #
+    class RequestCount < StatsStruct
+      coerce_attributes :succeeded, :failed, :refused, into: IntegerDefaultZero
+    end
+
+    # ResourceCount contains aggregate data for usage of a resource in a specific scope
+    #
+    class ResourceCount < StatsStruct
+      coerce_attributes :opened, :peak, :mean, :min, :refused, into: IntegerDefaultZero
+    end
+
+    # ConnectionTypes contains a breakdown of summary stats data for different (TLS vs non-TLS) connection types
+    #
+    # @spec TS4a, TS4b, TS4c
+    #
+    class ConnectionTypes < StatsStruct
+      coerce_attributes :tls, :plain, :all, into: ResourceCount
+    end
+
+    # MessageTypes contains a breakdown of summary stats data for different (message vs presence) message types
+    #
+    # @spec TS6a, TS6b, TS6c
+    #
+    class MessageTypes < StatsStruct
+      coerce_attributes :messages, :presence, :all, into: MessageCount
+    end
+
+    # MessageTraffic contains a breakdown of summary stats data for traffic over various transport types
+    #
+    # @spec TS7a, TS7b, TS7c, TS7d
+    #
+    class MessageTraffic < StatsStruct
+      coerce_attributes :realtime, :rest, :webhook, :all, into: MessageTypes
+    end
+  end
+end

data/lib/ably/models/token_details.rb

@@ -0,0 +1,148 @@
+module Ably::Models
+  # Convert token details argument to a {TokenDetails} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [TokenDetails]
+  #
+  def self.TokenDetails(attributes)
+    case attributes
+    when TokenDetails
+      return attributes
+    else
+      TokenDetails.new(attributes)
+    end
+  end
+
+  # Contains an Ably Token and its associated metadata.
+  #
+  class TokenDetails
+    include Ably::Modules::ModelCommon
+
+    # Buffer in seconds before a token is considered unusable
+    # For example, if buffer is 10s, the token can no longer be used for new requests 9s before it expires
+    TOKEN_EXPIRY_BUFFER = 15
+
+    # @param attributes
+    # @option attributes [String]       :token      token used to authenticate requests
+    # @option attributes [String]       :key_name   API key name used to create this token
+    # @option attributes [Time,Integer] :issued     Time the token was issued as Time or Integer in milliseconds
+    # @option attributes [Time,Integer] :expires    Time the token expires as Time or Integer in milliseconds
+    # @option attributes [String]       :capability JSON stringified capabilities assigned to this token
+    # @option attributes [String]       :client_id  client ID assigned to this token
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+
+      %w(issued expires).map(&:to_sym).each do |time_attribute|
+        if self.attributes[time_attribute].kind_of?(Time)
+          self.attributes[time_attribute] = (self.attributes[time_attribute].to_f * 1000).round
+        end
+      end
+
+      self.attributes.freeze
+    end
+
+    # The Ably Token itself. A typical Ably Token string appears with the form xVLyHw.A-pwh7wicf3afTfgiw4k2Ku33kcnSA7z6y8FjuYpe3QaNRTEo4.
+    #
+    # @spec TD2
+    #
+    # @return [String] Token used to authenticate requests
+    #
+    def token
+      attributes[:token]
+    end
+
+    # @return [String] API key name used to create this token.  An API key is made up of an API key name and secret delimited by a +:+
+    #
+    def key_name
+      attributes[:key_name]
+    end
+
+    # The timestamp at which this token was issued as milliseconds since the Unix epoch.
+    # @spec TD4
+    # @return [Time] Time the token was issued
+    def issued
+      as_time_from_epoch(attributes[:issued], granularity: :ms, allow_nil: :true)
+    end
+
+    # The timestamp at which this token expires as milliseconds since the Unix epoch.
+    # @spec TD3
+    # @return [Time] Time the token expires
+    def expires
+      as_time_from_epoch(attributes[:expires], granularity: :ms, allow_nil: :true)
+    end
+
+    # The capabilities associated with this Ably Token. The capabilities value is a JSON-encoded representation of the
+    # resource paths and associated operations. Read more about capabilities in the capabilities docs.
+    # @spec TD5
+    # @return [Hash] Capabilities assigned to this token
+    def capability
+      if attributes.has_key?(:capability)
+        capability_val = attributes.fetch(:capability)
+        case capability_val
+        when Hash
+          capability_val
+        when Ably::Models::IdiomaticRubyWrapper
+          capability_val.as_json
+        else
+          JSON.parse(attributes.fetch(:capability))
+        end
+      end
+    end
+
+    # The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its
+    # bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID.
+    # The client is then considered to be an identified client.
+    # @spec TD6
+    # @return [String] Optional client ID assigned to this token
+    def client_id
+      attributes[:client_id]
+    end
+
+    # Returns true if token is expired or about to expire
+    # For tokens that have not got an explicit expires attribute expired? will always return true
+    #
+    # @param attributes [Hash]
+    # @option attributes [Time] :from   Sets a current time from which token expires
+    #
+    # @return [Boolean]
+    def expired?(attributes = {})
+      return false if !expires
+
+      from = attributes[:from] || Time.now
+      expires < from + TOKEN_EXPIRY_BUFFER
+    end
+
+    # True if the TokenDetails was created from an opaque string i.e. no metadata exists for this token
+    # @return [Boolean]
+    # @api private
+    def from_token_string?
+      attributes.keys == [:token]
+    end
+
+    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    #
+    def attributes
+      @hash_object
+    end
+
+    def to_s
+      "<TokenDetails token=#{token} client_id=#{client_id} key_name=#{key_name} issued=#{issued} expires=#{expires} capability=#{capability} expired?=#{expired?}>"
+    end
+
+    # A static factory method to create a {Ably::Models::TokenDetails} object from a deserialized {Ably::Models::TokenDetails}-like
+    # object or a JSON stringified TokenDetails object. This method is provided to minimize bugs as a result of differing
+    # types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the {Ably::Models::TokenDetails}
+    # object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it
+    # is automatically converted to the Ably standard which is milliseconds. By using the fromJson() method when constructing
+    # a {Ably::Models::TokenDetails} object, Ably ensures that all fields are consistently serialized and deserialized across platforms.
+    #
+    # @overload from_json(json_like_object)
+    # @spec TD7
+    # @param json_like_object [Hash, String] A deserialized TokenDetails-like object or a JSON stringified TokenDetails object.
+    #
+    # @return [Ably::Models::TokenDetails]  An Ably authentication token.
+    #
+  end
+end

data/lib/ably/models/token_request.rb

@@ -0,0 +1,180 @@
+module Ably::Models
+  # Convert token request argument to a {TokenRequest} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [TokenRequest]
+  #
+  def self.TokenRequest(attributes)
+    case attributes
+    when TokenRequest
+      return attributes
+    else
+      TokenRequest.new(attributes)
+    end
+  end
+
+
+  # Contains the properties of a request for a token to Ably.
+  # Tokens are generated using {Ably::Auth#requestToken}.
+  #
+  # Ruby {http://ruby-doc.org/core/Time.html Time} objects are supported in place of Ably ms since epoch time fields.  However, if a numeric is provided
+  # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields.
+  #
+  class TokenRequest
+    include Ably::Modules::ModelCommon
+
+    # @param attributes
+    # @option attributes [Integer]      :ttl        requested time to live for the token in milliseconds
+    # @option attributes [Time,Integer] :timestamp  the timestamp of this request in milliseconds or as a {http://ruby-doc.org/core/Time.html Time}
+    # @option attributes [String]       :key_name   API key name of the key against which this request is made
+    # @option attributes [String]       :capability JSON stringified capability of the token
+    # @option attributes [String]       :client_id  client ID to associate with this token
+    # @option attributes [String]       :nonce      an opaque nonce string of at least 16 characters
+    # @option attributes [String]       :mac        the Message Authentication Code for this request
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+      if self.attributes[:timestamp].kind_of?(Time)
+        self.attributes[:timestamp] = (self.attributes[:timestamp].to_f * 1000).round
+      end
+      self.attributes.freeze
+    end
+
+    # The name of the key against which this request is made. The key name is public, whereas the key secret is private.
+    #
+    # @!attribute [r] key_name
+    #
+    # @spec TE2
+    #
+    # @return [String] API key name of the key against which this request is made.  An API key is made up of an API key name and secret delimited by a +:+
+    #
+    def key_name
+      attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' }
+    end
+
+    # Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the
+    # returned Ably Token is less than or equal to this value, depending on application settings and the attributes of
+    # the issuing key. The default is 60 minutes.
+    #
+    # @!attribute [r] ttl
+    #
+    # @spec TE4
+    #
+    # @return [Integer] requested time to live for the token in seconds. If the token request is successful,
+    #                   the TTL of the returned token will be less than or equal to this value depending on application
+    #                   settings and the attributes of the issuing key.
+    #                   TTL when sent to Ably is in milliseconds.
+    def ttl
+      attributes.fetch(:ttl) / 1000
+    end
+
+    # Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned
+    # Ably Token will be the intersection of this capability with the capability of the issuing key. The capabilities
+    # value is a JSON-encoded representation of the resource paths and associated operations. Read more about
+    # capabilities in the capabilities docs.
+    #
+    # @!attribute [r] capability
+    #
+    # @spec TE3
+    #
+    # @return [Hash] capability of the token. If the token request is successful,
+    #                the capability of the returned token will be the intersection of
+    #                this capability with the capability of the issuing key.
+    def capability
+      capability_val = attributes.fetch(:capability) { raise Ably::Exceptions::InvalidTokenRequest, 'Capability is missing' }
+
+      case capability_val
+      when Hash
+        capability_val
+      when Ably::Models::IdiomaticRubyWrapper
+        capability_val.as_json
+      else
+        JSON.parse(attributes.fetch(:capability))
+      end
+    end
+
+    # The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to
+    # perform operations on behalf of that client ID.
+    #
+    # @!attribute [r] client_id
+    #
+    # @spec TE2
+    #
+    # @return [String] the client ID to associate with this token. The generated token
+    #                  may be used to authenticate as this clientId.
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The timestamp of this request as milliseconds since the Unix epoch.
+    #
+    # @!attribute [r] timestamp
+    #
+    # @spec TE5
+    #
+    # @return [Time] the timestamp of this request.
+    #                Timestamps, in conjunction with the nonce, are used to prevent
+    #                token requests from being replayed.
+    #                Timestamp when sent to Ably is in milliseconds.
+    def timestamp
+      timestamp_val = attributes.fetch(:timestamp) { raise Ably::Exceptions::InvalidTokenRequest, 'Timestamp is missing' }
+      as_time_from_epoch(timestamp_val, granularity: :ms)
+    end
+
+    # A cryptographically secure random string of at least 16 characters, used to ensure the TokenRequest cannot be reused.
+    #
+    # @!attribute [r] nonce
+    #
+    # @spec TE2
+    #
+    # @return [String]  an opaque nonce string of at least 16 characters to ensure
+    #                   uniqueness of this request. Any subsequent request using the
+    #                   same nonce will be rejected.
+    def nonce
+      attributes.fetch(:nonce) { raise Ably::Exceptions::InvalidTokenRequest, 'Nonce is missing' }
+    end
+
+    # The Message Authentication Code for this request.
+    #
+    # @!attribute [r] mac
+    #
+    # @spec TE2
+    #
+    # @return [String]  the Message Authentication Code for this request. See the
+    #
+    def mac
+      attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' }
+    end
+
+    # Requests that the token is always persisted
+    #
+    # @api private
+    #
+    def persisted
+      attributes[:persisted]
+    end
+
+    # @!attribute [r] attributes
+    #
+    # @return [Hash] the token request Hash object ruby'fied to use symbolized keys
+    #
+    def attributes
+      @hash_object
+    end
+
+    # A static factory method to create a TokenRequest object from a deserialized TokenRequest-like object or a JSON
+    # stringified TokenRequest object. This method is provided to minimize bugs as a result of differing types by platform
+    # for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as
+    # that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to
+    # the Ably standard which is milliseconds. By using the fromJson() method when constructing a TokenRequest object,
+    # Ably ensures that all fields are consistently serialized and deserialized across platforms.
+    #
+    # @overload from_json(json_like_object)
+    # @spec TE6
+    # @param json_like_object [Hash, String] A deserialized TokenRequest-like object or a JSON stringified TokenRequest object to create a TokenRequest.
+    #
+    # @return [Ably::Models::TokenRequest] An Ably token request object.
+    #
+  end
+end

data/lib/ably/modules/ably.rb

@@ -0,0 +1,26 @@
+# Ably is the base namespace for the Ably {Ably::Realtime Realtime} & {Ably::Rest Rest} client libraries.
+#
+# Please refer to the {file:README.md Readme} on getting started.
+#
+# @see file:README.md README
+module Ably
+  # Fallback hosts to use when a connection to rest/realtime.ably.io is not possible due to
+  # network failures either at the client, between the client and Ably, within an Ably data center, or at the IO domain registrar
+  # see https://ably.com/docs/client-lib-development-guide/features/#RSC15a
+  #
+  FALLBACK_DOMAIN = 'ably-realtime.com'.freeze
+  FALLBACK_IDS = %w(a b c d e).freeze
+
+  # Default production fallbacks a.ably-realtime.com ... e.ably-realtime.com
+  FALLBACK_HOSTS = FALLBACK_IDS.map { |host| "#{host}.#{FALLBACK_DOMAIN}".freeze }.freeze
+
+  # Custom environment default fallbacks {ENV}-a-fallback.ably-realtime.com ... {ENV}-a-fallback.ably-realtime.com
+  CUSTOM_ENVIRONMENT_FALLBACKS_SUFFIXES = FALLBACK_IDS.map do |host|
+    "-#{host}-fallback.#{FALLBACK_DOMAIN}".freeze
+  end.freeze
+
+  INTERNET_CHECK = {
+    url:     '//internet-up.ably-realtime.com/is-the-internet-up.txt',
+    ok_text: 'yes'
+  }.freeze
+end

data/lib/ably/modules/async_wrapper.rb

@@ -0,0 +1,69 @@
+require 'eventmachine'
+
+module Ably::Modules
+  # Provides methods to convert synchronous operations into async operations through the use of
+  # {http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine#defer-class_method EventMachine#defer}.
+  # The async_wrap method can only be called from within an EventMachine reactor, and must be thread safe.
+  #
+  # @note using this AsyncWrapper should only be used for methods that are used less frequently and typically
+  #       not run with levels of concurrency due to the limited number of threads available to EventMachine by default.
+  #       This module requires that the method #logger is defined.
+  #
+  # @example
+  #   class BlockingOperation
+  #     include Aby::Modules::AsyncWrapper
+  #
+  #     def operation(&success_callback)
+  #       async_wrap(success_callback) do
+  #         sleep 1
+  #         'slept'
+  #       end
+  #     end
+  #   end
+  #
+  #   blocking_object = BlockingOperation.new
+  #   deferrable = blocking_object.operation do |result|
+  #     puts "Done with result: #{result}"
+  #   end
+  #   puts "Starting"
+  #
+  #   # => 'Starting'
+  #   # => 'Done with result: slept'
+  #
+  module AsyncWrapper
+    private
+
+    # Will yield the provided block in a new thread and return an {Ably::Util::SafeDeferrable}
+    #
+    # @yield [Object] operation block that is run in a thread
+    #
+    # @return [Ably::Util::SafeDeferrable]
+    #
+    def async_wrap(success_callback = nil, custom_error_handling = nil)
+      raise ArgumentError, 'Block required' unless block_given?
+
+      Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+        deferrable.callback(&success_callback) if success_callback
+
+        operation_with_exception_handling = lambda do
+          begin
+            yield
+          rescue StandardError => err
+            if custom_error_handling
+              custom_error_handling.call err, deferrable
+            else
+              logger.error { "An exception in an AsyncWrapper block was caught. #{err.class}: #{err.message}\n#{err.backtrace.join("\n")}" }
+              deferrable.fail err
+            end
+          end
+        end
+
+        complete_callback = lambda do |result|
+          deferrable.succeed result
+        end
+
+        EventMachine.defer operation_with_exception_handling, complete_callback
+      end
+    end
+  end
+end

data/lib/ably/modules/channels_collection.rb

@@ -0,0 +1,105 @@
+module Ably::Modules
+  # ChannelsCollection module provides common functionality to the Rest and Realtime Channels objects
+  # such as #get, #[], #fetch, and #release
+  module ChannelsCollection
+    include Enumerable
+
+    def initialize(client, channel_klass)
+      @client         = client
+      @channel_klass  = channel_klass
+      @channels       = {}
+    end
+
+    # Return a Channel for the given name
+    #
+    # @param name [String] The name of the channel
+    # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions}
+    #
+    # @return [Channel]
+    #
+    def get(name, channel_options = {})
+      if channels.has_key?(name)
+        channels[name].tap do |channel|
+          if channel_options && !channel_options.empty?
+            if channel.respond_to?(:need_reattach?) && channel.need_reattach?
+              raise_implicit_options_update
+            else
+              warn_implicit_options_update
+              channel.options = channel_options
+            end
+          end
+        end
+      else
+        channels[name] ||= channel_klass.new(client, name, channel_options)
+      end
+    end
+    alias_method :[], :get
+
+    # Return a 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 [Channel]
+    #
+    def fetch(name, &missing_block)
+      channels.fetch(name, &missing_block)
+    end
+
+    # Destroy the Channel and releases the associated resources.
+    #
+    # Releasing a Channel is not typically necessary as a channel consumes no resources other than the memory footprint of the
+    # Channel object. Explicitly release channels to free up resources if required
+    #
+    # @param name [String] The name of the channel
+    #
+    # @return [void]
+    #
+    def release(name)
+      channels.delete(name)
+    end
+
+    # @!attribute [r] length
+    # @return [Integer] number of channels created
+    def length
+      channels.length
+    end
+    alias_method :count, :length
+    alias_method :size,  :length
+
+    # Method to allow {ChannelsCollection} to be {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+    def each(&block)
+      return to_enum(:each) unless block_given?
+      channels.values.each(&block)
+    end
+
+    private
+
+    def raise_implicit_options_update
+      raise ArgumentError, "You are trying to indirectly update channel options which will trigger reattachment of the channel. Please use Channel#set_options directly if you wish to continue"
+    end
+
+    def warn_implicit_options_update
+      logger.warn { "Channels#get: Using this method to update channel options is deprecated and may be removed in a future version of ably-ruby. Please use Channel#setOptions instead" }
+    end
+
+    def logger
+      client.logger
+    end
+
+    def client
+      @client
+    end
+
+    def channel_klass
+      @channel_klass
+    end
+
+    def channels
+      @channels
+    end
+  end
+end