ably-pubsub-core 0.0.1.pre

data/lib/ably/exceptions.rb

@@ -0,0 +1,169 @@
+require 'ably/modules/exception_codes'
+
+module Ably
+  module Exceptions
+    TOKEN_EXPIRED_CODE = 40140..40149
+
+    # Base Ably exception class that contains status and code values used by Ably
+    # Refer to https://github.com/ably/ably-common/blob/main/protocol/errors.json
+    #
+    # @!attribute [r] message
+    #   @return [String] Error message from Ably
+    # @!attribute [r] status
+    #   @return [String] HTTP status code of error
+    # @!attribute [r] code
+    #   @return [String] Ably specific error code
+    class BaseAblyException < StandardError
+      attr_reader :status, :code, :request_id
+
+      def initialize(message, status = nil, code = nil, base_exception = nil, options = {})
+        super message
+
+        @base_exception = base_exception
+        @status = status
+        @status ||= base_exception.status if base_exception && base_exception.respond_to?(:status)
+        @status ||= options[:fallback_status]
+        @code = code
+        @code ||= base_exception.code if base_exception && base_exception.respond_to?(:code)
+        @code ||= options[:fallback_code]
+        @request_id ||= options[:request_id]
+      end
+
+      def to_s
+        message = [super]
+        if status || code
+          additional_info = []
+          additional_info << "code: #{code}" if code
+          additional_info << "http status: #{status}" if status
+          additional_info << "base exception: #{@base_exception.class}" if @base_exception
+          additional_info << "request_id: #{request_id}" if request_id
+          message << "(#{additional_info.join(', ')})"
+          message << "-> see https://help.ably.io/error/#{code} for help" if code
+        end
+        message.join(' ')
+      end
+
+      def as_json(*args)
+        {
+          message: "#{self.class}: #{message}",
+          status: @status,
+          code: @code
+        }.delete_if { |key, val| val.nil? }
+      end
+    end
+
+    # Maximum frame size exceeded TO3l9
+    class MaxFrameSizeExceeded < BaseAblyException; end
+
+    # Maximum message size exceeded TO3l8
+    class MaxMessageSizeExceeded < BaseAblyException; end
+
+    # An invalid request was received by Ably
+    class InvalidRequest < BaseAblyException; end
+
+    class InvalidCredentials < BaseAblyException; end
+
+    # Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided
+    class UnauthorizedRequest < BaseAblyException; end
+
+    # The request was a valid request, but Ably is refusing to respond to it
+    class ForbiddenRequest < BaseAblyException; end
+
+    # The requested resource could not be found but may be available again in the future
+    class ResourceMissing < BaseAblyException; end
+
+    # Ably Protocol message received that is invalid
+    class ProtocolError < BaseAblyException; end
+
+    # Encryption or Decryption failure
+    class CipherError < BaseAblyException; end
+
+    # Encoding or decoding failure
+    class EncoderError < BaseAblyException; end
+
+    # Connection error from Realtime or REST service
+    class ConnectionError < BaseAblyException
+      def initialize(message, status = nil, code = nil, base_exception = nil, options = {})
+        super message, status, code, base_exception, options
+      end
+
+      def to_s
+        message = [super]
+        if @base_exception
+          message << "#{@base_exception}"
+          if @base_exception.respond_to?(:message) && @base_exception.message.match(/certificate verify failed/i)
+            message << "See https://goo.gl/eKvfcR to resolve this issue."
+          end
+        end
+        message.join(' < ')
+      end
+    end
+
+    # Connection Timeout accessing Realtime or REST service
+    class ConnectionTimeout < ConnectionError; end
+
+    # Transport closed unexpectedly
+    class TransportClosed < ConnectionError; end
+
+    # Connection closed unexpectedly
+    class ConnectionClosed < ConnectionError; end
+
+    # Connection suspended
+    class ConnectionSuspended < ConnectionError; end
+
+    # Connection failed
+    class ConnectionFailed < ConnectionError; end
+
+    class AuthenticationFailed < ConnectionError; end
+
+    # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
+    class InvalidStateChange < BaseAblyException; end
+
+    class InvalidState < BaseAblyException; end
+
+    # A generic Ably exception taht supports a status & code.
+    # See https://github.com/ably/ably-common/blob/main/protocol/errors.json for a list of Ably errors
+    class Standard < BaseAblyException; end
+
+    # The HTTP request has returned a 500 error
+    class ServerError < BaseAblyException; end
+
+    # PaginatedResult cannot retrieve the page
+    class PageMissing < BaseAblyException; end
+
+    # The expected response from the server was invalid
+    class InvalidResponseBody < BaseAblyException; end
+
+    # The request cannot be performed because it is insecure
+    class InsecureRequest < BaseAblyException; end
+
+    # The token request could not be created
+    class TokenRequestFailed < BaseAblyException; end
+
+    # The token has expired, 40140..40149
+    class TokenExpired < BaseAblyException; end
+
+    # The message could not be delivered to the server
+    class MessageDeliveryFailed < BaseAblyException; end
+
+    # The client has been configured to not queue messages i.e. only publish down an active connection
+    class MessageQueueingDisabled < BaseAblyException; end
+
+    # The data payload type is not supported
+    class UnsupportedDataType < BaseAblyException; end
+
+    # When a channel is detached / failed, certain operations are not permitted such as publishing messages
+    class ChannelInactive < BaseAblyException; end
+
+    class IncompatibleClientId < BaseAblyException
+      def initialize(messages, status = 400, code = Ably::Exceptions::Codes::INVALID_CLIENT_ID, *args)
+        super(message, status, code, *args)
+      end
+    end
+
+    # Token request has missing or invalid attributes
+    class InvalidTokenRequest < BaseAblyException; end
+
+    class PushNotificationsNotSupported < BaseAblyException; end
+  end
+end

data/lib/ably/logger.rb

@@ -0,0 +1,119 @@
+module Ably
+  # Logger unifies logging for #debug, #info, #warn, #error, and #fatal messages.
+  # A new Ably client uses this Logger and sets the appropriate log level.
+  # A custom Logger can be configured when instantiating the client, refer to the {Ably::Rest::Client} and {Ably::Realtime::Client} documentation
+  #
+  class Logger
+    extend Forwardable
+
+    # @param client        [Ably::Rest::Client,Ably::Realtime::Client] Rest or Realtime Ably client
+    # @param log_level     [Integer] {http://www.ruby-doc.org/stdlib-3.1.1/libdoc/logger/rdoc/Logger.html Ruby Logger} log level
+    # @param custom_logger [nil,Object] A custom logger can optionally be used instead of the,
+    #                      however it must provide a {http://www.ruby-doc.org/stdlib-3.1.1/libdoc/logger/rdoc/Logger.html Ruby Logger} compatible interface.
+    #
+    def initialize(client, log_level, custom_logger = nil)
+      @client        = client
+      @custom_logger = custom_logger
+      @logger        = custom_logger || default_logger
+      @log_level     = log_level
+
+      ensure_logger_interface_is_valid
+
+      @logger.level = log_level
+
+      @log_mutex = Mutex.new
+    end
+
+    # The logger used by this class, defaults to {http://www.ruby-doc.org/stdlib-3.1.1/libdoc/logger/rdoc/Logger.html Ruby Logger}
+    # @return {Object,Logger}
+    attr_reader :logger
+
+    # If a custom logger is being used with this Logger, this property is not nil
+    # @return {nil,Object}
+    attr_reader :custom_logger
+
+    # The log level ranging from DEBUG to FATAL, refer to http://www.ruby-doc.org/stdlib-3.1.1/libdoc/logger/rdoc/Logger.html
+    # @return {Integer}
+    attr_reader :log_level
+
+    # Catch exceptiosn in blocks passed to the logger, log the error and continue
+    %w(fatal error warn info debug).each do |method_name|
+      define_method(method_name) do |*args, &block|
+        begin
+          log_mutex.synchronize do
+            logger.public_send(method_name, *args, &block)
+          end
+        rescue StandardError => e
+          logger.error "Logger: Failed to log #{method_name} block - #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+        end
+      end
+    end
+
+    private
+    attr_reader :log_mutex
+
+    def client
+      @client
+    end
+
+    def color(color_value, string)
+      "\033[#{color_value}m#{string}\033[0m"
+    end
+
+    def red(string)
+      color(31, string)
+    end
+
+    def magenta(string)
+      color(35, string)
+    end
+
+    def cyan(string)
+      color(36, string)
+    end
+
+    def connection_id
+      if realtime?
+        if client.connection.id
+          "[#{cyan(client.connection.id)}] "
+        else
+          "[ #{cyan('--')} ] "
+        end
+      end
+    end
+
+    def realtime?
+      defined?(Ably::Realtime::Client) && client.kind_of?(Ably::Realtime::Client)
+    end
+
+    def default_logger
+      ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = lambda do |severity, datetime, progname, msg|
+          severity = ::Logger::SEV_LABEL.index(severity) if severity.kind_of?(String)
+
+          formatted_date = if severity == ::Logger::DEBUG
+            datetime.strftime("%H:%M:%S.%L")
+          else
+            datetime.strftime("%Y-%m-%d %H:%M:%S.%L")
+          end
+
+          severity_label = if severity <= ::Logger::INFO
+            magenta(::Logger::SEV_LABEL[severity])
+          else
+            red(::Logger::SEV_LABEL[severity])
+          end
+
+          "#{formatted_date} #{severity_label} #{connection_id}#{msg}\n"
+        end
+      end
+    end
+
+    def ensure_logger_interface_is_valid
+      %w(fatal error warn info debug level level=).each do |method|
+        unless logger.respond_to?(method)
+          raise ArgumentError, "The custom Logger's interface does not provide the method '#{method}'"
+        end
+      end
+    end
+  end
+end

data/lib/ably/models/auth_details.rb

@@ -0,0 +1,45 @@
+module Ably::Models
+  # Convert auth details attributes to a {AuthDetails} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [AuthDetails]
+  #
+  def self.AuthDetails(attributes)
+    case attributes
+    when AuthDetails
+      return attributes
+    else
+      AuthDetails.new(attributes || {})
+    end
+  end
+
+  # AuthDetails are included in an +AUTH+ {Ably::Models::ProtocolMessage#auth} attribute
+  # to provide the realtime service with new token authentication details following a re-auth workflow
+  #
+  class AuthDetails
+    include Ably::Modules::ModelCommon
+
+    # @param attributes [Hash]
+    # @option attributes [String]    :access_token     token string
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+      self.attributes.freeze
+    end
+
+    # The authentication token string.
+    #
+    # @spec AD2
+    #
+    # @return [String]
+    #
+    def access_token
+      attributes[:access_token]
+    end
+
+    def attributes
+      @hash_object
+    end
+  end
+end

data/lib/ably/models/channel_details.rb

@@ -0,0 +1,69 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelDetails} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelDetails]
+  #
+  def self.ChannelDetails(attributes)
+    case attributes
+    when ChannelDetails
+      return attributes
+    else
+      ChannelDetails.new(attributes)
+    end
+  end
+
+  # Contains the details of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
+  # such as its ID and {Ably::Models::ChannelStatus}.
+  #
+  class ChannelDetails
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    # The attributes of ChannelDetails
+    #
+    # @spec CHD2
+    #
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    # Initialize a new ChannelDetails
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+    end
+
+    # The identifier of the channel
+    #
+    # @spec CHD2a
+    #
+    # @return [String]
+    #
+    def channel_id
+      attributes[:channel_id]
+    end
+
+    # The identifier of the channel
+    #
+    # @spec CHD2a
+    #
+    # @return [String]
+    #
+    def name
+      attributes[:name]
+    end
+
+    # A {Ably::Models::ChannelStatus} object.
+    #
+    # @spec CHD2b
+    #
+    # @return [Ably::Models::ChannelStatus, nil]
+    #
+    def status
+      Ably::Models::ChannelStatus(attributes[:status])
+    end
+  end
+end

data/lib/ably/models/channel_metrics.rb

@@ -0,0 +1,107 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelMetrics} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelMetrics]
+  #
+  def self.ChannelMetrics(attributes)
+    case attributes
+    when ChannelMetrics
+      return attributes
+    else
+      ChannelMetrics.new(attributes)
+    end
+  end
+
+  # Contains the metrics associated with a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel},
+  # such as the number of publishers, subscribers and connections it has.
+  #
+  # @spec CHM1
+  #
+  class ChannelMetrics
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    # The attributes of ChannelMetrics (CHM2)
+    #
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    # Initialize a new ChannelMetrics
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+    end
+
+    # The number of realtime connections attached to the channel.
+    #
+    # @spec CHM2a
+    #
+    # @return [Integer]
+    #
+    def connections
+      attributes[:connections]
+    end
+
+    # The number of realtime connections attached to the channel with permission to enter the presence set, regardless
+    # of whether or not they have entered it. This requires the presence capability and for a client to not have specified
+    # a {Ably::Models::ChannelOptions::MODES} flag that excludes {Ably::Models::ChannelOptions::MODES}#PRESENCE.
+    #
+    # @spec CHM2b
+    #
+    # @return [Integer]
+    #
+    def presence_connections
+      attributes[:presence_connections]
+    end
+
+    # The number of members in the presence set of the channel.
+    #
+    # @spec CHM2c
+    #
+    # @return [Integer]
+    #
+    def presence_members
+      attributes[:presence_members]
+    end
+
+    # The number of realtime attachments receiving presence messages on the channel. This requires the subscribe capability
+    # and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#PRESENCE_SUBSCRIBE.
+    #
+    # @spec CHM2d
+    #
+    # @return [Integer]
+    #
+    def presence_subscribers
+      attributes[:presence_subscribers]
+    end
+
+    # The number of realtime attachments permitted to publish messages to the channel. This requires the publish
+    # capability and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#PUBLISH.
+    #
+    # @spec CHM2e
+    #
+    # @return [Integer]
+    #
+    def publishers
+      attributes[:publishers]
+    end
+
+    # The number of realtime attachments receiving messages on the channel. This requires the subscribe capability and
+    # for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#SUBSCRIBE.
+    #
+    # @spec CHM2f
+    #
+    # @return [Integer]
+    #
+    def subscribers
+      attributes[:subscribers]
+    end
+  end
+end

data/lib/ably/models/channel_occupancy.rb

@@ -0,0 +1,50 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelOccupancy} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelOccupancy]
+  #
+  def self.ChannelOccupancy(attributes)
+    case attributes
+    when ChannelOccupancy
+      return attributes
+    else
+      ChannelOccupancy.new(attributes)
+    end
+  end
+
+  # Contains the metrics of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
+  #
+  # @spec CHO1
+  #
+  class ChannelOccupancy
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    # The attributes of ChannelOccupancy.
+    #
+    # @spec CH02
+    #
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    # Initialize a new ChannelOccupancy
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+    end
+
+    # A {Ably::Models::ChannelMetrics} object.
+    #
+    # @spec CHO2a
+    #
+    # @return [Ably::Models::ChannelMetrics, nil]
+    #
+    def metrics
+      Ably::Models::ChannelMetrics(attributes[:metrics])
+    end
+  end
+end

data/lib/ably/models/channel_options.rb

@@ -0,0 +1,120 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelOptions} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelOptions]
+  #
+  def self.ChannelOptions(attributes)
+    case attributes
+    when ChannelOptions
+      return attributes
+    else
+      ChannelOptions.new(attributes)
+    end
+  end
+
+  # Represents options of a channel
+  class ChannelOptions
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    # Describes the possible flags used to configure client capabilities, using {Ably::Models::ChannelOptions::MODES}.
+    #
+    #   PRESENCE		          The client can enter the presence set.
+    #   PUBLISH		            The client can publish messages.
+    #   SUBSCRIBE		          The client can subscribe to messages.
+    #   PRESENCE_SUBSCRIBE		The client can receive presence messages.
+    #
+    # @spec TB2d
+    #
+    MODES = ruby_enum('MODES',
+      presence: 0,
+      publish: 1,
+      subscribe: 2,
+      presence_subscribe: 3
+    )
+
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    def_delegators :attributes, :fetch, :size, :empty?
+    # Initialize a new ChannelOptions
+    #
+    # @spec TB3
+    #
+    # @option params [Hash] (TB2c) params (for realtime client libraries only) a  of key/value pairs
+    # @option modes [Hash] modes (for realtime client libraries only) an array of ChannelMode
+    # @option cipher [Hash,Ably::Models::CipherParams]   :cipher   A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+
+      attributes[:modes] = modes.to_a.map { |mode| Ably::Models::ChannelOptions::MODES[mode] } if modes
+      attributes[:cipher] = Ably::Models::CipherParams(cipher) if cipher
+      attributes.clone
+    end
+
+    # Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm,
+    # chaining mode, key length and key). See an example.
+    #
+    # @spec RSL5a, TB2b
+    #
+    # @return [CipherParams]
+    #
+    def cipher
+      attributes[:cipher]
+    end
+
+    # Channel Parameters that configure the behavior of the channel.
+    #
+    # @spec TB2c
+    #
+    # @return [Hash]
+    #
+    def params
+      attributes[:params].to_h
+    end
+
+    # An array of {Ably:Models:ChannelOptions::MODES} objects.
+    #
+    # @spec TB2d
+    #
+    # @return [Array<ChannelOptions::MODES>]
+    #
+    def modes
+      attributes[:modes]
+    end
+
+    # Converts modes to a bitfield that coresponds to ProtocolMessage#flags
+    #
+    # @return [Integer]
+    #
+    def modes_to_flags
+      modes.map { |mode| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym] }.reduce(:|)
+    end
+
+    # @return [Hash]
+    # @api private
+    def set_params(hash)
+      attributes[:params] = hash
+    end
+
+    # Sets modes from ProtocolMessage#flags
+    #
+    # @return [Array<ChannelOptions::MODES>]
+    # @api private
+    def set_modes_from_flags(flags)
+      return unless flags
+
+      message_modes = MODES.select do |mode|
+        flag = Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym]
+        flags & flag == flag
+      end
+
+      attributes[:modes] = message_modes.map { |mode| Ably::Models::ChannelOptions::MODES[mode] }
+    end
+  end
+end