DhanHQ 4.1.0 → 4.1.1

data/lib/DhanHQ/ws/market_depth/client.rb

@@ -13,12 +13,17 @@ module DhanHQ
       # WebSocket client for Full Market Depth data
       # Provides real-time market depth (bid/ask levels) for specified symbols
       class Client < BaseConnection
-        # Feed request codes per the official Annexure "Feed Request Code" table
-        # (dhanhq.co/docs/v2/annexure#feed-request-code): 23 = Subscribe - Full
-        # Market Depth, 24 = Unsubscribe - Full Market Depth. Never 12 - that is
-        # the whole-connection disconnect, not a per-instrument unsubscribe.
+        # Feed request codes per the Annexure "Feed Request Code" table and the
+        # Full Market Depth "Feed Disconnect" section (docs.dhanhq.co):
+        # 23 = Subscribe - Full Market Depth, 25 = Unsubscribe - Full Market Depth.
+        # Never 12 - that is the whole-connection disconnect, not a
+        # per-instrument unsubscribe.
         SUBSCRIBE_REQUEST_CODE    = 23
-        UNSUBSCRIBE_REQUEST_CODE  = 24
+        UNSUBSCRIBE_REQUEST_CODE  = 25
+
+        # Instruments one connection may carry: 50 for 20-level depth, exactly
+        # one for 200-level depth.
+        MAX_INSTRUMENTS = { 20 => 50, 200 => 1 }.freeze
 
         ##
         # Initialize Market Depth WebSocket client
@@ -30,10 +35,12 @@ module DhanHQ
           url = options[:url] || build_market_depth_url(cfg)
           super(url: url, config: cfg, **options)
 
-          @symbols = Array(symbols)
+          @symbols = symbol_list(symbols)
           @subscriptions = Concurrent::Map.new
           @instrument_cache = Concurrent::Map.new
-          @decoder = Decoder.new
+          @depth_level = cfg.market_depth_level.to_i == 200 ? 200 : 20
+          @decoder = Decoder.new(depth_level: @depth_level)
+          @books = {}
         end
 
         ##
@@ -50,7 +57,7 @@ module DhanHQ
         # @param symbols [Array<String, Hash>] Symbols (or metadata hashes) to subscribe to
         # @return [Client] self for method chaining
         def subscribe(symbols)
-          subscribe_to_symbols(Array(symbols))
+          subscribe_to_symbols(symbol_list(symbols))
           self
         end
 
@@ -59,7 +66,7 @@ module DhanHQ
         # @param symbols [Array<String, Hash>] Symbols (or metadata hashes) to unsubscribe from
         # @return [Client] self for method chaining
         def unsubscribe(symbols)
-          unsubscribe_from_symbols(Array(symbols))
+          unsubscribe_from_symbols(symbol_list(symbols))
           self
         end
 
@@ -135,16 +142,77 @@ module DhanHQ
         # Process incoming WebSocket message
         # @param data [String] Raw message data
         def process_message(data)
-          depth_data = @decoder.decode(data)
-          return unless depth_data
+          touched = []
+          @decoder.decode(data).each do |packet|
+            next handle_disconnect_packet(packet) if packet[:type] == :disconnect
+
+            key = [packet[:exchange_segment], packet[:security_id]]
+            book = (@books[key] ||= { bids: [], asks: [] })
+            book[packet[:type] == :bid ? :bids : :asks] = packet[:levels]
+            touched << key unless touched.include?(key)
+          end
 
-          emit(:depth_update, depth_data)
+          touched.each { |key| emit(:depth_update, depth_snapshot(*key)) }
           emit(:raw_depth, data) # For debugging
         rescue StandardError => e
           DhanHQ.logger&.error("[DhanHQ::WS::MarketDepth] Error processing message: #{e.class} #{e.message}")
           emit(:error, e)
         end
 
+        # A single instrument hash is one symbol; Array(hash) would split it into pairs.
+        def symbol_list(symbols)
+          symbols.is_a?(Hash) ? [symbols] : Array(symbols)
+        end
+
+        # Merged order book for one instrument, combining the latest bid and ask
+        # packets (they arrive separately on the wire).
+        def depth_snapshot(segment, security_id)
+          book = @books.fetch([segment, security_id])
+          meta = @subscriptions.values.find { |m| m[:security_id] == security_id && m[:exchange_segment] == segment }
+          best_bid = book[:bids].first&.fetch(:price)
+          best_ask = book[:asks].first&.fetch(:price)
+
+          {
+            type: :depth_update,
+            depth_level: @depth_level,
+            symbol: meta&.fetch(:symbol, nil),
+            exchange_segment: segment,
+            security_id: security_id,
+            timestamp: Time.now.to_i,
+            bids: book[:bids],
+            asks: book[:asks],
+            best_bid: best_bid,
+            best_ask: best_ask,
+            spread: best_bid && best_ask ? best_ask - best_bid : nil,
+            total_bid_qty: book[:bids].sum { |level| level[:quantity] },
+            total_ask_qty: book[:asks].sum { |level| level[:quantity] }
+          }
+        end
+
+        def handle_disconnect_packet(packet)
+          DhanHQ.logger&.warn("[DhanHQ::WS::MarketDepth] Server disconnect packet, reason code #{packet[:code]}")
+          emit(:disconnect, packet)
+        end
+
+        # 20-level takes an instrument list; 200-level takes one flat instrument
+        # (docs.dhanhq.co Full Market Depth, "Adding Instruments").
+        def subscription_message(resolution)
+          instrument = { "ExchangeSegment" => resolution[:exchange_segment], "SecurityId" => resolution[:security_id] }
+          return { "RequestCode" => SUBSCRIBE_REQUEST_CODE }.merge(instrument) if @depth_level == 200
+
+          { "RequestCode" => SUBSCRIBE_REQUEST_CODE, "InstrumentCount" => 1, "InstrumentList" => [instrument] }
+        end
+
+        def capacity_reached?(resolution)
+          return false if @subscriptions.size < MAX_INSTRUMENTS.fetch(@depth_level)
+
+          DhanHQ.logger&.error(
+            "[DhanHQ::WS::MarketDepth] Not subscribing #{resolution[:original_label]}: #{@depth_level}-level depth " \
+            "allows #{MAX_INSTRUMENTS.fetch(@depth_level)} instrument(s) per connection"
+          )
+          true
+        end
+
         ##
         # Subscribe to symbols
         # @param symbols [Array<String, Hash>] Symbols to subscribe to
@@ -155,19 +223,9 @@ module DhanHQ
 
             label = resolution[:label]
             next if @subscriptions.key?(label)
+            next if capacity_reached?(resolution)
 
-            subscription_message = {
-              "RequestCode" => SUBSCRIBE_REQUEST_CODE,
-              "InstrumentCount" => 1,
-              "InstrumentList" => [
-                {
-                  "ExchangeSegment" => resolution[:exchange_segment],
-                  "SecurityId" => resolution[:security_id]
-                }
-              ]
-            }
-
-            send_message(subscription_message)
+            send_message(subscription_message(resolution))
             @subscriptions[label] = resolution
             DhanHQ.logger&.info(
               "[DhanHQ::WS::MarketDepth] Subscribed to #{resolution[:original_label]} " \
@@ -200,6 +258,7 @@ module DhanHQ
 
             send_message(unsubscribe_message)
             @subscriptions.delete(label)
+            @books.delete([security_data[:exchange_segment], security_data[:security_id]])
             DhanHQ.logger&.info(
               "[DhanHQ::WS::MarketDepth] Unsubscribed from #{security_data[:original_label]} " \
               "(#{security_data[:exchange_segment]}:#{security_data[:security_id]})"

data/lib/DhanHQ/ws/market_depth/decoder.rb

@@ -1,129 +1,136 @@
 # frozen_string_literal: true
 
+require_relative "../segments"
+
 module DhanHQ
   module WS
     module MarketDepth
       ##
-      # Decoder for Market Depth WebSocket messages
-      # Handles parsing of market depth data (bid/ask levels)
+      # Decoder for the binary 20/200-level Full Market Depth feed.
+      #
+      # Wire format (docs.dhanhq.co "Full Market Depth", little-endian, no padding):
+      #
+      #   Header (12 bytes)
+      #     0-1   int16   message length of the packet
+      #     2     byte    feed response code: 41 = bid side, 51 = ask side, 50 = disconnect
+      #     3     byte    exchange segment (Annexure numeric enum)
+      #     4-7   int32   security id
+      #     8-11  uint32  20-level: message sequence (ignored) / 200-level: number of rows
+      #   Rows (16 bytes each; 20 for 20-level, "number of rows" for 200-level)
+      #     0-7   float64 price
+      #     8-11  uint32  quantity
+      #     12-15 uint32  number of orders
+      #
+      # Bid and ask arrive as separate packets, and several packets (per side,
+      # per instrument) are stacked in one WebSocket message, so {#decode}
+      # walks the frame packet by packet using each header's length.
       class Decoder
+        HEADER_SIZE = 12
+        ROW_SIZE = 16
+        BID_CODE = 41
+        ASK_CODE = 51
+        DISCONNECT_CODE = 50
+        TWENTY_LEVEL_ROWS = 20
+
+        # @param depth_level [Integer] 20 or 200; decides how header bytes 8-11 are read.
+        def initialize(depth_level: 20)
+          @depth_level = depth_level.to_i == 200 ? 200 : 20
+        end
+
         ##
-        # Decode raw WebSocket message to market depth data
-        # @param data [String] Raw WebSocket message
-        # @return [Hash, nil] Parsed market depth data or nil if invalid
+        # Decode one WebSocket message into its side packets.
+        #
+        # @param data [String, Array<Integer>] Raw frame (Faye delivers binary frames as byte arrays).
+        # @return [Array<Hash>] One entry per packet, in wire order. Side packets are
+        #   +{ type: :bid | :ask, exchange_segment:, security_id:, levels: [{ price:, quantity:, orders: }] }+;
+        #   a disconnect packet is +{ type: :disconnect, exchange_segment:, security_id:, code: }+.
+        #   Malformed trailing bytes are dropped (and logged), never raised.
         def decode(data)
-          return nil if data.nil? || data.empty?
-
-          begin
-            # Parse JSON message
-            message = JSON.parse(data)
-
-            # Handle different message types
-            case message["Type"]
-            when "depth_update"
-              parse_depth_update(message["Data"])
-            when "depth_snapshot"
-              parse_depth_snapshot(message["Data"])
-            else
-              # Unknown message type
-              nil
-            end
-          rescue JSON::ParserError => e
-            DhanHQ.logger&.error("[DhanHQ::WS::MarketDepth::Decoder] JSON parse error: #{e.message}")
-            nil
-          rescue StandardError => e
-            DhanHQ.logger&.error("[DhanHQ::WS::MarketDepth::Decoder] Decode error: #{e.class} #{e.message}")
-            nil
+          bytes = to_binary(data)
+          packets = []
+          offset = 0
+
+          while bytes.bytesize - offset >= HEADER_SIZE
+            packet, consumed = read_packet(bytes, offset)
+            break unless packet
+
+            packets << packet
+            offset += consumed
           end
+
+          log_trailing(bytes.bytesize - offset) if offset < bytes.bytesize
+          packets
+        rescue StandardError => e
+          DhanHQ.logger&.error("[DhanHQ::WS::MarketDepth::Decoder] Decode error: #{e.class} #{e.message}")
+          []
         end
 
         private
 
-        ##
-        # Parse depth update message
-        # @param data [Hash] Message data
-        # @return [Hash] Parsed depth update
-        def parse_depth_update(data)
-          {
-            type: :depth_update,
-            symbol: data["Symbol"],
-            exchange_segment: data["ExchangeSegment"],
-            security_id: data["SecurityId"],
-            timestamp: data["Timestamp"],
-            bids: parse_bid_levels(data["Bids"]),
-            asks: parse_ask_levels(data["Asks"]),
-            best_bid: data["BestBid"],
-            best_ask: data["BestAsk"],
-            spread: calculate_spread(data["BestBid"], data["BestAsk"]),
-            total_bid_qty: data["TotalBidQty"],
-            total_ask_qty: data["TotalAskQty"]
-          }
+        def to_binary(data)
+          return "".b if data.nil?
+
+          data.is_a?(Array) ? data.pack("C*") : data.to_s.b
         end
 
-        ##
-        # Parse depth snapshot message
-        # @param data [Hash] Message data
-        # @return [Hash] Parsed depth snapshot
-        def parse_depth_snapshot(data)
-          {
-            type: :depth_snapshot,
-            symbol: data["Symbol"],
-            exchange_segment: data["ExchangeSegment"],
-            security_id: data["SecurityId"],
-            timestamp: data["Timestamp"],
-            bids: parse_bid_levels(data["Bids"]),
-            asks: parse_ask_levels(data["Asks"]),
-            best_bid: data["BestBid"],
-            best_ask: data["BestAsk"],
-            spread: calculate_spread(data["BestBid"], data["BestAsk"]),
-            total_bid_qty: data["TotalBidQty"],
-            total_ask_qty: data["TotalAskQty"]
+        # @return [Array(Hash, Integer), nil] The packet and the bytes it spans.
+        def read_packet(bytes, offset)
+          length, code, segment, security_id, tail = bytes.byteslice(offset, HEADER_SIZE).unpack("s<CCl<L<")
+          segment_name = Segments.from_code(segment)
+
+          return [disconnect(bytes, offset, segment_name, security_id), packet_span(length, HEADER_SIZE + 2)] if code == DISCONNECT_CODE
+
+          unless [BID_CODE, ASK_CODE].include?(code)
+            DhanHQ.logger&.warn("[DhanHQ::WS::MarketDepth::Decoder] Unknown response code #{code}; dropping rest of frame")
+            return nil
+          end
+
+          rows = @depth_level == 200 ? tail : TWENTY_LEVEL_ROWS
+          span = side_span(length, rows)
+          available = [(bytes.bytesize - offset - HEADER_SIZE) / ROW_SIZE, rows, (span - HEADER_SIZE) / ROW_SIZE].min
+
+          packet = {
+            type: code == BID_CODE ? :bid : :ask,
+            exchange_segment: segment_name,
+            security_id: security_id.to_s,
+            levels: read_levels(bytes, offset + HEADER_SIZE, available)
           }
+          [packet, span]
         end
 
-        ##
-        # Parse bid levels
-        # @param bids [Array] Raw bid levels
-        # @return [Array<Hash>] Parsed bid levels
-        def parse_bid_levels(bids)
-          return [] unless bids.is_a?(Array)
-
-          bids.map do |bid|
-            {
-              price: bid["Price"].to_f,
-              quantity: bid["Quantity"].to_i,
-              orders: bid["Orders"] || 1
-            }
-          end
+        # Packet span from the header's length field, falling back to the
+        # documented fixed size when the field is absent or implausible.
+        def packet_span(length, expected)
+          length.to_i >= HEADER_SIZE ? length : expected
         end
 
-        ##
-        # Parse ask levels
-        # @param asks [Array] Raw ask levels
-        # @return [Array<Hash>] Parsed ask levels
-        def parse_ask_levels(asks)
-          return [] unless asks.is_a?(Array)
-
-          asks.map do |ask|
-            {
-              price: ask["Price"].to_f,
-              quantity: ask["Quantity"].to_i,
-              orders: ask["Orders"] || 1
-            }
+        # The docs call the length field "message length of the entire payload
+        # packet" without saying whether the 12-byte header is included. A value
+        # equal to exactly the rows (rows * 16) is read as payload-only; anything
+        # else as the full packet. Both readings stay aligned on stacked frames.
+        def side_span(length, rows)
+          payload = rows * ROW_SIZE
+          return HEADER_SIZE + payload if length.to_i == payload
+
+          packet_span(length, HEADER_SIZE + payload)
+        end
+
+        def read_levels(bytes, start, count)
+          levels = Array.new([count, 0].max) do |i|
+            price, quantity, orders = bytes.byteslice(start + (i * ROW_SIZE), ROW_SIZE).unpack("EL<L<")
+            { price: price, quantity: quantity, orders: orders }
           end
+          # Unfilled rows of a partially populated book are zeroed on the wire.
+          levels.reject { |level| level[:quantity].zero? && level[:price].zero? }
         end
 
-        ##
-        # Calculate spread between best bid and ask
-        # @param best_bid [Float, String] Best bid price
-        # @param best_ask [Float, String] Best ask price
-        # @return [Float] Spread amount
-        def calculate_spread(best_bid, best_ask)
-          bid = best_bid.to_f
-          ask = best_ask.to_f
-          return 0.0 if bid.zero? || ask.zero?
-
-          ask - bid
+        def disconnect(bytes, offset, segment_name, security_id)
+          code = bytes.byteslice(offset + HEADER_SIZE, 2)&.unpack1("s<")
+          { type: :disconnect, exchange_segment: segment_name, security_id: security_id.to_s, code: code }
+        end
+
+        def log_trailing(count)
+          DhanHQ.logger&.warn("[DhanHQ::WS::MarketDepth::Decoder] Ignoring #{count} trailing byte(s) in depth frame")
         end
       end
     end

data/lib/dhan_hq.rb

@@ -62,6 +62,8 @@ module DhanHQ
   # Eager-load risk utilities (PositionSizer, SLCalculator, TrailManager)
   # and the pre-execution risk pipeline so they are available immediately.
   require_relative "DhanHQ/risk"
+  require_relative "DhanHQ/risk/limits"
+  require_relative "DhanHQ/risk/exposure"
   require_relative "DhanHQ/risk/checks/trading_permission"
   require_relative "DhanHQ/risk/checks/asm_gsm"
   require_relative "DhanHQ/risk/checks/product_support"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -384,6 +384,8 @@ files:
 - lib/DhanHQ/risk/checks/product_support.rb
 - lib/DhanHQ/risk/checks/quantity.rb
 - lib/DhanHQ/risk/checks/trading_permission.rb
+- lib/DhanHQ/risk/exposure.rb
+- lib/DhanHQ/risk/limits.rb
 - lib/DhanHQ/risk/pipeline.rb
 - lib/DhanHQ/skills.rb
 - lib/DhanHQ/skills/base.rb