ably-pubsub-core 0.0.1.pre

data/lib/ably/modules/state_machine.rb

@@ -0,0 +1,59 @@
+require 'statesman'
+require 'ably/modules/statesman_monkey_patch'
+
+module Ably::Modules
+  # Module providing Statesman StateMachine functionality
+  #
+  # Expects method #logger to be defined
+  #
+  # @api private
+  module StateMachine
+    def self.included(klass)
+      klass.class_eval do
+        include Statesman::Machine
+      end
+      klass.extend Ably::Modules::StatesmanMonkeyPatch
+      klass.extend ClassMethods
+    end
+
+    # Alternative to Statesman's #transition_to that:
+    # * log state change failures to {Logger}
+    #
+    # @return [void]
+    #
+    def transition_state(state, *args)
+      unless result = transition_to(state.to_sym, *args)
+        exception = exception_for_state_change_to(state)
+        logger.fatal { "#{self.class}: #{exception.message}\n#{caller[0..20].join("\n")}" }
+      end
+      result
+    end
+
+    # @return [Statesman History Object]
+    #
+    def previous_transition
+      history[-2]
+    end
+
+    # @return [Symbol]
+    #
+    def previous_state
+      previous_transition.to_state if previous_transition
+    end
+
+    # @return [Ably::Exceptions::InvalidStateChange]
+    #
+    def exception_for_state_change_to(state)
+      error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}"
+      Ably::Exceptions::InvalidStateChange.new(error_message, nil, Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_INVALID_CHANNEL_STATE)
+    end
+
+    module ClassMethods
+      private
+
+      def is_error_type?(error)
+        error.kind_of?(Ably::Models::ErrorInfo) || error.kind_of?(StandardError)
+      end
+    end
+  end
+end

data/lib/ably/modules/statesman_monkey_patch.rb

@@ -0,0 +1,33 @@
+module Ably::Modules
+  # @api private
+  module StatesmanMonkeyPatch
+    # Override Statesman's #before_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def before_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super(*options_without_from_array, &block)
+      end
+    end
+
+    # Override Statesman's #after_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def after_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super(*options_without_from_array, &block)
+      end
+    end
+
+    private
+    def arrayify_transition(options, &block)
+      if options.nil?
+        yield []
+      elsif options.fetch(:from, nil).kind_of?(Array)
+        options[:from].each do |from_state|
+          yield [options.merge(from: from_state)]
+        end
+      else
+        yield [options]
+      end
+    end
+  end
+end

data/lib/ably/modules/uses_state_machine.rb

@@ -0,0 +1,111 @@
+module Ably::Modules
+  # Mixing module that assists with {https://github.com/gocardless/statesman Statemans State Machine} state transitions
+  # and maintaining state of this object's #state.
+  #
+  # Expects:
+  #   - @state_machine is set to the StateMachine
+  #   - StateEmitter is included in the object
+  #
+  module UsesStateMachine
+    extend Forwardable
+
+    # Call #transition_to on the StateMachine
+    #
+    # @return [Boolean] true if new_state can be transitioned to by state machine
+    # @api private
+    def transition_state_machine(new_state, emit_params = {})
+      state_machine.transition_state(new_state, emit_object(new_state, emit_params))
+    end
+
+    # Call #transition_to! on the StateMachine
+    # An exception wil be raised if new_state cannot be transitioned to by state machine
+    #
+    # @return [void]
+    # @api private
+    def transition_state_machine!(new_state, emit_params = {})
+      state_machine.transition_to!(new_state, emit_object(new_state, emit_params))
+    end
+
+    # Provides an internal method for this object's state to match the StateMachine's current state.
+    # The current object's state will be changed to the StateMachine state and will emit an event
+    # @api private
+    def synchronize_state_with_statemachine(*args)
+      log_state_machine_state_change
+      change_state state_machine.current_state, state_machine.last_transition.metadata
+    end
+
+    # @!attribute [r] previous_state
+    # @return [STATE,nil] The previous state for this connection
+    # @api private
+    def previous_state
+      if state_machine.previous_state
+        STATE(state_machine.previous_state)
+      end
+    end
+
+    # @!attribute [r] state_history
+    # @return [Array<Hash>] All previous states including the current state in date ascending order with Hash properties :state, :metadata, :transitioned_at
+    # @api private
+    def state_history
+      state_machine.history.map do |transition|
+        {
+          state:           STATE(transition.to_state),
+          metadata:        transition.metadata,
+          transitioned_at: transition.created_at
+        }
+      end
+    end
+
+    def_delegators :state_machine, :can_transition_to?
+
+    private
+    def state_machine
+      @state_machine
+    end
+
+    def_delegators :state_machine, :exception_for_state_change_to
+
+    def log_state_machine_state_change
+      if state_machine.previous_state
+        logger.debug { "#{self.class.name}: Transitioned from #{state_machine.previous_state} => #{state_machine.current_state}" }
+      else
+        logger.debug { "#{self.class.name}: Transitioned to #{state_machine.current_state}" }
+      end
+    end
+
+    def emit_object(new_state, emit_params)
+      if self.class.emits_klass
+        self.class.emits_klass.new((emit_params || {}).merge(
+          current: STATE(new_state),
+          previous: STATE(state_machine.current_state),
+          event: EVENT(new_state)
+        ))
+      else
+        emit_params
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def emits_klass
+        @emits_klass ||= if defined?(@emits_klass_name) && @emits_klass_name
+          get_const(@emits_klass_name)
+        end
+      end
+
+      def ensure_state_machine_emits(klass)
+        @emits_klass_name = klass
+      end
+
+      def get_const(klass_name)
+        klass_names = klass_name.split('::')
+        klass_names.inject(Kernel) do |klass, name|
+          klass.const_get(name)
+        end
+      end
+    end
+  end
+end

data/lib/ably/realtime/auth.rb

@@ -0,0 +1,283 @@
+require 'ably/auth'
+
+module Ably
+  module Realtime
+    # Auth is responsible for authentication with {https://www.ably.com Ably} using basic or token authentication
+    # This {Ably::Realtime::Auth Realtime::Auth} class wraps the {Ably::Auth Synchronous Ably::Auth} class in an EventMachine friendly way using Deferrables for all IO.  See {Ably::Auth Ably::Auth} for more information
+    #
+    # Find out more about Ably authentication at: https://www.ably.com/docs/general/authentication/
+    #
+    # @!attribute [r] client_id
+    #   (see Ably::Auth#client_id)
+    # @!attribute [r] current_token_details
+    #   (see Ably::Auth#current_token_details)
+    # @!attribute [r] token
+    #   (see Ably::Auth#token)
+    # @!attribute [r] key
+    #   (see Ably::Auth#key)
+    # @!attribute [r] key_name
+    #   (see Ably::Auth#key_name)
+    # @!attribute [r] key_secret
+    #   (see Ably::Auth#key_secret)
+    # @!attribute [r] options
+    #   (see Ably::Auth#options)
+    # @!attribute [r] token_params
+    #   (see Ably::Auth#options)
+    # @!attribute [r] using_basic_auth?
+    #   (see Ably::Auth#using_basic_auth?)
+    # @!attribute [r] using_token_auth?
+    #   (see Ably::Auth#using_token_auth?)
+    # @!attribute [r] token_renewable?
+    #   (see Ably::Auth#token_renewable?)
+    # @!attribute [r] authentication_security_requirements_met?
+    #   (see Ably::Auth#authentication_security_requirements_met?)
+    #
+    class Auth
+      extend Forwardable
+      include Ably::Modules::AsyncWrapper
+
+      def_delegators :auth_sync, :client_id
+      def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
+      def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
+      def_delegators :auth_sync, :current_token_details, :token
+      def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
+      def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
+      def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
+      def_delegators :client, :logger
+      def_delegators :client, :connection
+
+      def initialize(client)
+        @client = client
+        @auth_sync = client.rest_client.auth
+      end
+
+      # For new connections, ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+      # If a connection is already established, the connection will be upgraded with a new token
+      #
+      # In the event that a new token request is made, the provided options are used
+      #
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Ably::Models::TokenDetails]
+      #
+      # @example
+      #    # will issue a simple token request using basic auth
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
+      #    client.auth.authorize do |token_details|
+      #      token_details #=> Ably::Models::TokenDetails
+      #    end
+      #
+      def authorize(token_params = nil, auth_options = nil, &success_callback)
+        Ably::Util::SafeDeferrable.new(logger).tap do |authorize_method_deferrable|
+          # Wrap the sync authorize method and wait for the result from the deferrable
+          async_wrap do
+            authorize_sync(token_params, auth_options)
+          end.tap do |auth_operation|
+            # Authorize operation succeeded and we have a new token, now let's perform inline authentication
+            auth_operation.callback do |token|
+              case connection.state.to_sym
+              when :initialized, :disconnected, :suspended, :closed, :closing, :failed
+                connection.connect
+              when :connected
+                perform_inline_auth token
+              when :connecting
+                # Fail all current connection attempts and try again with the new token, see #RTC8b
+                connection.manager.release_and_establish_new_transport
+              else
+                logger.fatal { "Auth#authorize: unsupported state #{connection.state}" }
+                authorize_method_deferrable.fail Ably::Exceptions::InvalidState.new("Unsupported state #{connection.state} for Auth#authorize")
+                next
+              end
+
+              # Indicate success or failure based on response from realtime, see #RTC8b1
+              auth_deferrable_resolved = false
+
+              connection.unsafe_once(:connected, :update) do
+                auth_deferrable_resolved = true
+                authorize_method_deferrable.succeed token
+              end
+              connection.unsafe_once(:suspended, :closed, :failed) do |state_change|
+                auth_deferrable_resolved = true
+                authorize_method_deferrable.fail state_change.reason
+              end
+            end
+
+            # Authorize failed, likely due to auth_url or auth_callback failing
+            auth_operation.errback do |error|
+              client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
+              authorize_method_deferrable.fail error
+            end
+          end
+
+          # Call the block provided to this method upon success of this deferrable
+          authorize_method_deferrable.callback do |token|
+            yield token if block_given?
+          end
+        end
+      end
+
+      # @deprecated Use {#authorize} instead
+      def authorise(*args, &block)
+        logger.warn { "Auth#authorise is deprecated and will be removed in 1.0. Please use Auth#authorize instead" }
+        authorize(*args, &block)
+      end
+
+      # Synchronous version of {#authorize}. See {Ably::Auth#authorize} for method definition
+      # Please note that authorize_sync will however not upgrade the current connection's token as this requires
+      # an synchronous operation to send the new authentication details to Ably over a realtime connection
+      #
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
+      # @return [Ably::Models::TokenDetails]
+      #
+      def authorize_sync(token_params = nil, auth_options = nil)
+        @authorization_in_flight = true
+        auth_sync.authorize(token_params, auth_options)
+      ensure
+        @authorization_in_flight = false
+      end
+
+      # @api private
+      def authorization_in_flight?
+        @authorization_in_flight
+      end
+
+      # @deprecated Use {#authorize_sync} instead
+      def authorise_sync(*args)
+        logger.warn { "Auth#authorise_sync is deprecated and will be removed in 1.0. Please use Auth#authorize_sync instead" }
+        authorize_sync(*args)
+      end
+
+      # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
+      #
+      # @param (see Ably::Auth#request_token)
+      # @option (see Ably::Auth#request_token)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Ably::Models::TokenDetails]
+      #
+      # @example
+      #    # simple token request using basic auth
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
+      #    client.auth.request_token do |token_details|
+      #      token_details #=> Ably::Models::TokenDetails
+      #    end
+      #
+      def request_token(token_params = {}, auth_options = {}, &success_callback)
+        async_wrap(success_callback) do
+          request_token_sync(token_params, auth_options)
+        end
+      end
+
+      # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
+      # @return [Ably::Models::TokenDetails]
+      #
+      def request_token_sync(token_params = {}, auth_options = {})
+        auth_sync.request_token(token_params, auth_options)
+      end
+
+      # Creates and signs a token request that can then subsequently be used by any client to request a token
+      #
+      # @param (see Ably::Auth#create_token_request)
+      # @option (see Ably::Auth#create_token_request)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Models::TokenRequest]
+      #
+      # @example
+      #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
+      #     token_request #=> Ably::Models::TokenRequest
+      #   end
+      def create_token_request(token_params = {}, auth_options = {}, &success_callback)
+        async_wrap(success_callback) do
+          create_token_request_sync(token_params, auth_options)
+        end
+      end
+
+      # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
+      # @return [Ably::Models::TokenRequest]
+      #
+      def create_token_request_sync(token_params = {}, auth_options = {})
+        auth_sync.create_token_request(token_params, auth_options)
+      end
+
+      # Auth header string used in HTTP requests to Ably
+      # Will reauthorize implicitly if required and capable
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
+      #
+      def auth_header(&success_callback)
+        async_wrap(success_callback) do
+          auth_header_sync
+        end
+      end
+
+      # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
+      # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
+      #
+      def auth_header_sync
+        auth_sync.auth_header
+      end
+
+      def client_id_for_request_sync
+        auth_sync.client_id_for_request
+      end
+
+      # Auth params used in URI endpoint for Realtime connections
+      # Will reauthorize implicitly if required and capable
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Hash] Auth params for a new Realtime connection
+      #
+      def auth_params(&success_callback)
+        fail_callback = lambda do |error, deferrable|
+          logger.error { "Failed to authenticate: #{error}" }
+          if error.kind_of?(Ably::Exceptions::BaseAblyException)
+            # Use base exception if it exists carrying forward the status codes
+            deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, nil, nil, error)
+          else
+            deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, 500, Ably::Exceptions::Codes::CLIENT_CONFIGURED_AUTHENTICATION_PROVIDER_REQUEST_FAILED)
+          end
+        end
+        async_wrap(success_callback, fail_callback) do
+          auth_params_sync
+        end
+      end
+
+      # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
+      # @return [Hash] Auth params for a new Realtime connection
+      #
+      def auth_params_sync
+        auth_sync.auth_params
+      end
+
+      private
+      # The synchronous Auth class instanced by the Rest client
+      # @return [Ably::Auth]
+      def auth_sync
+        @auth_sync
+      end
+
+      def client
+        @client
+      end
+
+      # Sends an AUTH ProtocolMessage on the existing connection triggering
+      # an inline AUTH process, see #RTC8a
+      def perform_inline_auth(token)
+        logger.debug { "Performing inline AUTH with Ably using token #{token}" }
+        connection.send_protocol_message(
+          action: Ably::Models::ProtocolMessage::ACTION.Auth.to_i,
+          auth: { access_token: token.token }
+        )
+      end
+    end
+  end
+end