coindcx-client 0.1.0

data/lib/coindcx/ws/connection_manager.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CoinDCX
+  module WS
+    # rubocop:disable Metrics/ClassLength
+    class ConnectionManager
+      MAX_RETRIES = 5
+      MAX_BACKOFF_INTERVAL = 30.0
+
+      def initialize(configuration:, backend:, logger:, sleeper: Kernel, thread_factory: nil, monotonic_clock: nil, randomizer: nil)
+        @configuration = configuration
+        @backend = backend
+        @logger = logger
+        @sleeper = sleeper
+        @thread_factory = thread_factory || ->(&block) { Thread.new(&block) }
+        @monotonic_clock = monotonic_clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @randomizer = randomizer || -> { rand }
+        @state = ConnectionState.new
+        @subscriptions = SubscriptionRegistry.new
+        @handlers = Hash.new { |hash, key| hash[key] = [] }
+        @registered_event_names = Set.new
+        @mutex = Mutex.new
+        # Lock-free liveness clock: Socket.IO callbacks and the heartbeat thread both touch this.
+        # Using Mutex here caused rare ThreadError (unlock from wrong thread/fiber) under concurrent WS load.
+        @last_activity_usec = (monotonic_time * 1_000_000).to_i
+        @engine_io_open = false
+      end
+
+      def connect
+        return self if state.connected? || state.connecting? || state.reconnecting?
+
+        transition_to(:connecting)
+        connect_with_retries
+        start_heartbeat
+        self
+      end
+
+      def disconnect
+        return self if state.current == :disconnected || state.stopping?
+
+        transition_to(:stopping)
+        stop_heartbeat
+        backend.disconnect
+        transition_to(:disconnected)
+        self
+      rescue Errors::SocketError
+        transition_to(:disconnected)
+        self
+      end
+
+      def on(event_name, &block)
+        return self unless block_given?
+
+        mutex.synchronize do
+          handlers[event_name] << block
+          register_event_bridge(event_name) if state.connected?
+        end
+
+        self
+      end
+
+      def subscribe(type:, channel_name:, event_name:, payload_builder:, delivery_mode:)
+        subscriptions.add(
+          type: type,
+          channel_name: channel_name,
+          event_name: event_name,
+          payload_builder: payload_builder,
+          delivery_mode: delivery_mode
+        )
+        register_event_bridge(event_name) if state.connected?
+        emit_join(subscription_for(type: type, channel_name: channel_name, event_name: event_name)) if state.connected? && @engine_io_open
+        transition_to(:subscribed) if state.connected? && subscriptions.any?
+        self
+      end
+
+      def alive?
+        return false unless state.connected?
+        return true unless subscriptions.any?
+
+        !stale_connection?
+      end
+
+      private
+
+      attr_reader :configuration, :backend, :logger, :sleeper, :thread_factory,
+                  :monotonic_clock, :randomizer, :state, :subscriptions, :handlers, :mutex,
+                  :registered_event_names
+
+      # rubocop:disable Metrics/MethodLength
+      def connect_with_retries
+        attempts = 0
+
+        begin
+          attempts += 1
+          establish_connection
+        rescue Errors::SocketAuthenticationError => e
+          transition_to(:failed)
+          log(
+            :error,
+            event: "ws_failed",
+            endpoint: configuration.socket_base_url,
+            retries: attempts - 1,
+            latency: nil,
+            error_class: e.class.name,
+            message: e.message,
+            subscription_count: subscriptions.count
+          )
+          raise e
+        rescue Errors::SocketConnectionError => e
+          handle_reconnect_failure(attempts, e)
+          retry
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def establish_connection
+        @engine_io_open = false
+        backend.connect(configuration.socket_base_url)
+        register_runtime_handlers
+        backend.start_transport!
+        touch_activity!
+        transition_to(:authenticated)
+      end
+
+      def register_runtime_handlers
+        @registered_event_names = Set.new
+        # socket.io-client-simple uses event_emitter's instance_exec(socket, *args) for listeners,
+        # so blocks must not rely on implicit self (handle_* would resolve on the socket client).
+        manager = self
+        backend.on(:connect) { |*_args| manager.send(:handle_connect) }
+        backend.on(:disconnect) { |*_args| manager.send(:handle_disconnect) }
+        subscriptions.event_names.each { |event_name| register_event_bridge(event_name) }
+      end
+
+      def handle_connect
+        touch_activity!
+        @engine_io_open = true
+        resubscribe_all
+        transition_to(subscriptions.any? ? :subscribed : :authenticated)
+      end
+
+      def handle_disconnect
+        return if state.stopping? || state.reconnecting?
+
+        @engine_io_open = false
+        transition_to(:disconnected)
+        log(
+          :warn,
+          event: "ws_disconnected",
+          endpoint: configuration.socket_base_url,
+          retries: 0,
+          latency: nil,
+          subscription_count: subscriptions.count
+        )
+        reconnect
+      end
+
+      def reconnect
+        return unless begin_reconnect?
+
+        transition_to(:reconnecting)
+        stop_heartbeat
+        backend.disconnect
+        connect_with_retries
+        start_heartbeat
+      ensure
+        finish_reconnect
+      end
+
+      def begin_reconnect?
+        mutex.synchronize do
+          return false if @reconnecting
+
+          @reconnecting = true
+        end
+
+        true
+      end
+
+      def finish_reconnect
+        mutex.synchronize { @reconnecting = false }
+      end
+
+      def resubscribe_all
+        subscriptions.each { |subscription| emit_join(subscription) }
+      end
+
+      def emit_join(subscription)
+        payload = subscription.payload
+        backend.emit("join", payload)
+      rescue Errors::AuthError => e
+        raise Errors::SocketAuthenticationError,
+              "private websocket authentication failed for #{subscription.channel_name}: #{e.message}"
+      end
+
+      def register_event_bridge(event_name)
+        return if registered_event_names.include?(event_name)
+
+        manager = self
+        # Socket.IO may emit multiple data frames after the event name, e.g. [channelName, payloadHash].
+        # Forwarding only the first argument often yields a bare String and drops the price object.
+        backend.on(event_name) do |*args|
+          manager.send(:touch_activity!)
+          coalesced = manager.send(:coalesce_socket_event_payload, args)
+          normalized = manager.send(:normalize_coin_dcx_event_payload, coalesced)
+          manager.send(:dispatch, event_name, normalized)
+        end
+
+        registered_event_names << event_name
+      end
+
+      def coalesce_socket_event_payload(args)
+        parts = Array(args).flatten(1).compact
+        return nil if parts.empty?
+        return parts.first if parts.size == 1
+
+        hashes = parts.grep(Hash)
+        return hashes.reduce { |acc, h| acc.merge(h) } if hashes.size > 1
+        return hashes.first if hashes.size == 1
+
+        parts.last
+      end
+
+      # CoinDCX often sends { "event" => "...", "data" => "<JSON string of fields>" }. Merge parsed
+      # fields into the top-level hash so consumers see p / s / etc. without a second parse.
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def normalize_coin_dcx_event_payload(payload)
+        return payload unless payload.is_a?(Hash)
+
+        %w[data payload].each do |key|
+          raw = payload[key] || payload[key.to_sym]
+          next unless raw.is_a?(String) && !raw.strip.empty?
+
+          parsed = JSON.parse(raw)
+          next unless parsed.is_a?(Hash)
+
+          merged = payload.merge(parsed)
+          merged.delete(key)
+          merged.delete(key.to_sym)
+          return merged
+        end
+
+        payload
+      rescue JSON::ParserError
+        payload
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      def dispatch(event_name, payload)
+        handlers.fetch(event_name, []).each do |handler|
+          handler.call(payload)
+        rescue StandardError => e
+          log(
+            :error,
+            event: "ws_handler_error",
+            endpoint: event_name,
+            retries: 0,
+            latency: nil,
+            error_class: e.class.name,
+            message: e.message
+          )
+        end
+      end
+
+      def start_heartbeat
+        stop_heartbeat
+        token = Object.new
+        @heartbeat_token = token
+        @heartbeat_thread = thread_factory.call { heartbeat_loop(token) }
+      end
+
+      def stop_heartbeat
+        @heartbeat_token = nil
+        @heartbeat_thread = nil
+      end
+
+      def heartbeat_loop(token)
+        loop do
+          sleeper.sleep(configuration.socket_heartbeat_interval)
+          break unless @heartbeat_token.equal?(token)
+
+          check_liveness!
+        end
+      rescue StandardError => e
+        log(
+          :error,
+          event: "ws_heartbeat_failed",
+          endpoint: configuration.socket_base_url,
+          retries: 0,
+          latency: nil,
+          error_class: e.class.name,
+          message: e.message
+        )
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def check_liveness!
+        return unless heartbeat_required?
+        return unless stale_connection?
+
+        timeout_error = Errors::SocketHeartbeatTimeoutError.new(
+          "CoinDCX websocket heartbeat timed out",
+          category: :socket_timeout,
+          code: "socket_heartbeat_timeout",
+          retryable: true
+        )
+        log(
+          :warn,
+          event: "ws_heartbeat_stale",
+          endpoint: configuration.socket_base_url,
+          retries: 0,
+          latency: liveness_age,
+          subscription_count: subscriptions.count,
+          error_class: timeout_error.class.name,
+          message: timeout_error.message
+        )
+        reconnect
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def heartbeat_required?
+        return false unless state.connected?
+
+        subscriptions.any?
+      end
+
+      def stale_connection?
+        liveness_age > configuration.socket_liveness_timeout
+      end
+
+      def liveness_age
+        now_usec = (monotonic_time * 1_000_000).to_i
+        (now_usec - @last_activity_usec) / 1_000_000.0
+      end
+
+      def touch_activity!
+        @last_activity_usec = (monotonic_time * 1_000_000).to_i
+      end
+
+      def monotonic_time
+        monotonic_clock.call
+      end
+
+      def reconnect_interval(attempts)
+        raw = configuration.socket_reconnect_interval * (2**(attempts - 1))
+        base = [raw, MAX_BACKOFF_INTERVAL].min
+        base + (base * 0.25 * randomizer.call)
+      end
+
+      def max_retries
+        configuration.socket_reconnect_attempts || MAX_RETRIES
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def handle_reconnect_failure(attempts, error)
+        if attempts > max_retries
+          transition_to(:failed)
+          log(
+            :error,
+            event: "ws_failed",
+            endpoint: configuration.socket_base_url,
+            retries: attempts - 1,
+            latency: nil,
+            error_class: error.class.name,
+            message: error.message,
+            subscription_count: subscriptions.count
+          )
+          raise error
+        end
+
+        transition_to(:reconnecting)
+        sleep_interval = reconnect_interval(attempts)
+        log(
+          :warn,
+          event: "ws_reconnect_retry",
+          endpoint: configuration.socket_base_url,
+          retries: attempts,
+          latency: nil,
+          error_class: error.class.name,
+          message: error.message,
+          sleep_interval: sleep_interval,
+          subscription_count: subscriptions.count
+        )
+        sleeper.sleep(sleep_interval)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def transition_to(next_state)
+        previous_state = state.current
+        return if previous_state == next_state
+
+        state.transition_to(next_state)
+        log(
+          :info,
+          event: "ws_state_transition",
+          endpoint: configuration.socket_base_url,
+          retries: 0,
+          latency: nil,
+          from: previous_state,
+          to: next_state,
+          subscription_count: subscriptions.count
+        )
+      end
+
+      def subscription_for(type:, channel_name:, event_name:)
+        subscriptions.each do |subscription|
+          return subscription if subscription.type == type &&
+                                 subscription.channel_name == channel_name &&
+                                 subscription.event_name == event_name
+        end
+
+        raise Errors::SocketStateError, "subscription intent not registered for #{event_name}"
+      end
+
+      def log(level, payload)
+        Logging::StructuredLogger.log(logger, level, payload)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/coindcx/ws/connection_state.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module CoinDCX
+  module WS
+    class ConnectionState
+      VALID_STATES = %i[disconnected connecting authenticated subscribed reconnecting failed stopping].freeze
+
+      # Allowed forward-transitions for each state.  Any transition not listed here
+      # is a programming error and will raise +SocketStateError+.
+      VALID_TRANSITIONS = {
+        disconnected: %i[connecting reconnecting],
+        connecting: %i[authenticated failed reconnecting stopping],
+        authenticated: %i[subscribed reconnecting stopping disconnected],
+        subscribed: %i[reconnecting stopping authenticated disconnected],
+        reconnecting: %i[authenticated subscribed failed stopping disconnected],
+        failed: %i[connecting stopping disconnected],
+        stopping: %i[disconnected]
+      }.freeze
+
+      def initialize
+        @value = :disconnected
+        @mutex = Mutex.new
+      end
+
+      def transition_to(next_state)
+        raise Errors::SocketError, "invalid connection state: #{next_state.inspect}" unless VALID_STATES.include?(next_state)
+
+        @mutex.synchronize do
+          return if @value == next_state
+
+          allowed = VALID_TRANSITIONS.fetch(@value, [])
+          unless allowed.include?(next_state)
+            raise Errors::SocketStateError,
+                  "invalid state transition: #{@value} → #{next_state} " \
+                  "(allowed from #{@value}: #{allowed.inspect})"
+          end
+
+          @value = next_state
+        end
+      end
+
+      def current
+        @mutex.synchronize { @value }
+      end
+
+      def connected?
+        authenticated? || subscribed?
+      end
+
+      def connecting?
+        current == :connecting
+      end
+
+      def authenticated?
+        current == :authenticated
+      end
+
+      def subscribed?
+        current == :subscribed
+      end
+
+      def reconnecting?
+        current == :reconnecting
+      end
+
+      def failed?
+        current == :failed
+      end
+
+      def stopping?
+        current == :stopping
+      end
+    end
+  end
+end

data/lib/coindcx/ws/parsers/order_book_snapshot.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CoinDCX
+  module WS
+    module Parsers
+      class OrderBookSnapshot
+        MAXIMUM_RECENT_ORDERS = 50
+
+        def self.parse(payload)
+          new(payload).to_h
+        end
+
+        def initialize(payload)
+          @payload = Utils::Payload.symbolize_keys(payload || {})
+        end
+
+        def to_h
+          {
+            source: :snapshot,
+            maximum_recent_orders: MAXIMUM_RECENT_ORDERS,
+            timestamp: payload[:E] || payload[:ts] || payload[:timestamp],
+            version: payload[:vs],
+            bids: levels_for(payload[:bids]),
+            asks: levels_for(payload[:asks])
+          }.compact
+        end
+
+        private
+
+        attr_reader :payload
+
+        def levels_for(levels)
+          return [] unless levels.is_a?(Hash)
+
+          levels.map do |price, quantity|
+            { price: price.to_s, quantity: quantity.to_s }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coindcx/ws/private_channels.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CoinDCX
+  module WS
+    class PrivateChannels
+      DEFAULT_CHANNEL_NAME = "coindcx"
+      BALANCE_UPDATE_EVENT = "balance-update"
+      ORDER_UPDATE_EVENT = "order-update"
+      TRADE_UPDATE_EVENT = "trade-update"
+      # Derivatives (futures) user stream — same authenticated `coindcx` channel as spot private.
+      DF_POSITION_UPDATE_EVENT = "df-position-update"
+      DF_ORDER_UPDATE_EVENT = "df-order-update"
+
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def join_payload(channel_name: DEFAULT_CHANNEL_NAME)
+        signer.private_channel_join(channel_name: channel_name)
+      end
+
+      private
+
+      attr_reader :configuration
+
+      def signer
+        @signer ||= Auth::Signer.new(
+          api_key: configuration.api_key || missing_configuration!(:api_key),
+          api_secret: configuration.api_secret || missing_configuration!(:api_secret)
+        )
+      end
+
+      def missing_configuration!(setting_name)
+        raise Errors::AuthenticationError, "#{setting_name} is required for private websocket subscriptions"
+      end
+    end
+  end
+end

data/lib/coindcx/ws/public_channels.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module CoinDCX
+  module WS
+    module PublicChannels
+      VALID_SPOT_ORDER_BOOK_DEPTHS = [10, 20, 50].freeze
+      VALID_FUTURES_ORDER_BOOK_DEPTHS = VALID_SPOT_ORDER_BOOK_DEPTHS
+      VALID_CURRENT_PRICES_SPOT_INTERVALS = %w[1s 10s].freeze
+      CURRENT_PRICES_SPOT_UPDATE_EVENT = "currentPrices@spot#update"
+      CURRENT_PRICES_FUTURES_CHANNEL = "currentPrices@futures@rt"
+      CURRENT_PRICES_FUTURES_UPDATE_EVENT = "currentPrices@futures#update"
+      PRICE_STATS_SPOT_UPDATE_EVENT = "priceStats@spot#update"
+      CANDLESTICK_EVENT = "candlestick"
+      DEPTH_SNAPSHOT_EVENT = "depth-snapshot"
+      DEPTH_UPDATE_EVENT = "depth-update"
+      NEW_TRADE_EVENT = "new-trade"
+      PRICE_CHANGE_EVENT = "price-change"
+
+      module_function
+
+      def candlestick(pair:, interval:)
+        "#{Contracts::Identifiers.validate_pair!(pair)}_#{interval}"
+      end
+
+      def order_book(pair:, depth: 20)
+        return "#{Contracts::Identifiers.validate_pair!(pair)}@orderbook@#{depth}" if VALID_SPOT_ORDER_BOOK_DEPTHS.include?(depth)
+
+        raise Errors::ValidationError,
+              "spot order book updates are snapshot-based and only documented for depths #{VALID_SPOT_ORDER_BOOK_DEPTHS.sort.join(', ')}"
+      end
+
+      def current_prices_spot(interval:)
+        key = interval.to_s.strip
+        unless VALID_CURRENT_PRICES_SPOT_INTERVALS.include?(key)
+          raise Errors::ValidationError,
+                "currentPrices@spot intervals must be one of #{VALID_CURRENT_PRICES_SPOT_INTERVALS.join(', ')}"
+        end
+
+        "currentPrices@spot@#{key}"
+      end
+
+      def price_stats_spot
+        "priceStats@spot@60s"
+      end
+
+      def price_stats(pair:)
+        "#{Contracts::Identifiers.validate_pair!(pair)}@prices"
+      end
+
+      def ltp(pair:)
+        price_stats(pair: pair)
+      end
+
+      def new_trade(pair:)
+        "#{Contracts::Identifiers.validate_pair!(pair)}@trades"
+      end
+
+      def futures_candlestick(instrument:, interval:)
+        ins = Contracts::Identifiers.validate_instrument!(instrument)
+        iv = interval.to_s.strip
+        raise Errors::ValidationError, "futures candlestick interval must be non-empty" if iv.empty?
+
+        "#{ins}_#{iv}-futures"
+      end
+
+      def futures_order_book(instrument:, depth: 20)
+        ins = Contracts::Identifiers.validate_instrument!(instrument)
+        return "#{ins}@orderbook@#{depth}-futures" if VALID_FUTURES_ORDER_BOOK_DEPTHS.include?(depth)
+
+        depths = VALID_FUTURES_ORDER_BOOK_DEPTHS.sort.join(", ")
+        raise Errors::ValidationError,
+              "futures order book channels are snapshot-based; documented depths are #{depths}"
+      end
+
+      def current_prices_futures
+        CURRENT_PRICES_FUTURES_CHANNEL
+      end
+
+      def futures_price_stats(instrument:)
+        "#{Contracts::Identifiers.validate_instrument!(instrument)}@prices-futures"
+      end
+
+      def futures_ltp(instrument:)
+        futures_price_stats(instrument: instrument)
+      end
+
+      def futures_new_trade(instrument:)
+        "#{Contracts::Identifiers.validate_instrument!(instrument)}@trades-futures"
+      end
+    end
+  end
+end