redhound 1.0.1 → 2.0.0.rc2

data/lib/redhound/analysis/stats.rb

@@ -0,0 +1,150 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module Stats
+      # @api private
+      class Table
+        attr_reader :evicted
+        # @rbs (?max_rows: Integer) -> void
+        def initialize(max_rows: 100_000)
+          @max_rows, @evicted = max_rows, 0
+          @rows = {} #: Hash[untyped, untyped]
+        end
+        # @rbs (untyped key) { () -> untyped } -> untyped
+        def row(key)
+          item = @rows.delete(key)
+          unless item
+            if @rows.size >= @max_rows
+              @rows.shift
+              @evicted += 1
+            end
+            item = yield
+          end
+          @rows[key] = item
+          item
+        end
+        # @rbs () -> Integer
+        def bytesize = @rows.size * 1024
+        # @rbs () -> void
+        def evict
+          @evicted += 1 if @rows.shift
+        end
+        # @rbs (untyped io) -> void
+        def format(io)
+          result = to_h
+          io.puts("#{result[:kind]}#{result[:type] ? ",#{result[:type]}" : ''}")
+          result[:rows].each { |item| io.puts(item.map { |name, value| "#{name}=#{value.is_a?(Array) ? value.join(':') : value}" }.join(' ')) }
+          io.puts("#{result[:omitted_intervals]} earlier IO intervals omitted") if result[:omitted_intervals] && result[:omitted_intervals].positive?
+          io.puts("#{@evicted} statistics rows evicted") if @evicted.positive?
+        end
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h = { kind: :stats, rows: @rows.values }
+      end
+
+      # @api private
+      class Io < Table
+        # @rbs ((Integer | Float) seconds, ?max_rows: Integer) -> void
+        def initialize(seconds, max_rows: 100_000)
+          super(max_rows: max_rows)
+          @interval_ns = (seconds * 1_000_000_000).to_i
+          raise ArgumentError, 'statistics interval must be positive' unless @interval_ns.positive?
+          @start_ns = nil # @rbs Integer?
+        end
+        # @rbs (Packet packet) -> void
+        def update(packet)
+          @start_ns ||= packet.timestamp_ns
+          start = @start_ns #: Integer
+          interval = [(packet.timestamp_ns - start) / @interval_ns, 0].max
+          item = row(interval) { interval_row(interval) }
+          item[:packets] += 1
+          item[:bytes] += packet.original_length
+        end
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h
+          return { kind: :io, interval_ns: @interval_ns, rows: [] } if @rows.empty?
+          last = @rows.keys.max #: Integer
+          first = [@rows.keys.min, last - @max_rows + 1].max #: Integer
+          rows = (first..last).map { |interval| @rows[interval] || interval_row(interval) }
+          { kind: :io, interval_ns: @interval_ns, omitted_intervals: first, rows: rows }
+        end
+        # @rbs (Integer interval) -> Hash[Symbol, Integer]
+        def interval_row(interval)
+          start = @start_ns || 0
+          { interval: interval, start_ns: start + interval * @interval_ns, end_ns: start + (interval + 1) * @interval_ns, packets: 0, bytes: 0 }
+        end
+      end
+
+      # @api private
+      class Conversations < Table
+        # @rbs (Symbol type, ?max_rows: Integer) -> void
+        def initialize(type, max_rows: 100_000)
+          super(max_rows: max_rows)
+          @type = type
+        end
+        # @rbs (Packet packet) -> void
+        def update(packet)
+          result = FlowKey.from(packet, @type)
+          return unless result
+          key, direction = result
+          item = row(key) do
+            { addr_a: key[1], port_a: key[2], addr_b: key[3], port_b: key[4],
+              packets_ab: 0, packets_ba: 0, bytes_ab: 0, bytes_ba: 0,
+              start_ns: packet.timestamp_ns, end_ns: packet.timestamp_ns, duration_ns: 0 }
+          end
+          suffix = direction.zero? ? 'ab' : 'ba'
+          item["packets_#{suffix}".to_sym] += 1
+          item["bytes_#{suffix}".to_sym] += packet.original_length
+          item[:start_ns] = [item[:start_ns], packet.timestamp_ns].min
+          item[:end_ns] = [item[:end_ns], packet.timestamp_ns].max
+          item[:duration_ns] = item[:end_ns] - item[:start_ns]
+        end
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h = { kind: :conv, type: @type, rows: @rows.values }
+      end
+
+      # @api private
+      class Endpoints < Table
+        # @rbs (Symbol type, ?max_rows: Integer) -> void
+        def initialize(type, max_rows: 100_000)
+          super(max_rows: max_rows)
+          @type = type
+        end
+        # @rbs (Packet packet) -> void
+        def update(packet)
+          result = FlowKey.from(packet, @type)
+          return unless result
+          key, direction = result
+          endpoints = [[key[1], key[2]], [key[3], key[4]]]
+          endpoints.each_with_index do |endpoint, index|
+            item = row(endpoint) { { address: endpoint[0], port: endpoint[1], packets_tx: 0, packets_rx: 0, bytes_tx: 0, bytes_rx: 0 } }
+            suffix = index == direction ? 'tx' : 'rx'
+            item["packets_#{suffix}".to_sym] += 1
+            item["bytes_#{suffix}".to_sym] += packet.original_length
+          end
+        end
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h = { kind: :endpoints, type: @type, rows: @rows.values }
+      end
+
+      # @api private
+      class Hierarchy < Table
+        # @rbs (Packet packet) -> void
+        def update(packet)
+          path = [] #: Array[Symbol]
+          packet.layers.reject(&:embedded).each do |layer|
+            path << layer.protocol
+            item = row(path.dup) { { path: path.dup, packets: 0, bytes: 0 } }
+            item[:packets] += 1
+            item[:bytes] += packet.original_length
+          end
+        end
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h = { kind: :phs, rows: @rows.values }
+      end
+    end
+  end
+end

data/lib/redhound/analysis/tcp_analysis.rb

@@ -0,0 +1,43 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module TcpAnalysis
+      # @rbs (Flow flow, Integer direction, TcpStream stream, Layer layer, Integer timestamp_ns) -> void
+      def self.update(flow, direction, stream, layer, timestamp_ns)
+        flags, seq, ack, length = layer[:flags], layer[:seq], layer[:ack], layer[:length]
+        layer.add(:stream, 'tcp.stream', flow.id)
+        layer.add(:seq_relative, 'tcp.seq_relative', Util::Seq.diff(seq, stream.base_seq || seq))
+        peer = flow.streams[1 - direction]
+        layer.add(:ack_relative, 'tcp.ack_relative', Util::Seq.diff(ack, peer.base_seq)) if peer && peer.base_seq && flags & 0x10 != 0
+        keep_alive = stream.base_seq && flags & 7 == 0 && length <= 1 && seq == (stream.next_sequence - 1) % Util::Seq::MOD
+        keep_alive_ack = flow.keep_alives[1 - direction] && peer && flags & 0x17 == 0x10 && length.zero? && ack == peer.next_sequence
+        if flags & 0x10 != 0
+          flag(layer, :duplicate_ack) if flags & 7 == 0 && length.zero? && layer[:window].positive? && flow.acks[direction] == [ack, layer[:window], 0] && !keep_alive_ack
+          flow.acks[direction] = [ack, layer[:window], length]
+          flow.keep_alives[1 - direction] = false
+        end
+        flag(layer, :zero_window) if layer[:window].zero? && flags & 6 == 0
+        if keep_alive
+          flag(layer, :keep_alive)
+          flow.keep_alives[direction] = true
+        end
+        if flags & 2 != 0 && flags & 0x10 == 0
+          flow.syn_ns ||= timestamp_ns
+          flow.syn_direction ||= direction
+        elsif flags & 0x12 == 0x12 && flow.syn_ns && flow.syn_direction != direction
+          flow.synack_ns ||= timestamp_ns
+          flow.synack_seq ||= seq
+        elsif flags & 0x10 != 0 && flow.synack_ns && flow.syn_direction == direction && !flow.initial_rtt && ack == (flow.synack_seq + 1) % Util::Seq::MOD
+          flow.initial_rtt = [timestamp_ns - flow.syn_ns, 0].max.fdiv(1_000_000_000)
+        end
+        layer.add(:initial_rtt, 'tcp.analysis.initial_rtt', flow.initial_rtt) if flow.initial_rtt && flags & 0x17 == 0x10
+      end
+      # @rbs (Layer layer, Symbol name) -> void
+      def self.flag(layer, name) = layer.add("analysis_#{name}".to_sym, "tcp.analysis.#{name}", true, type: :boolean)
+    end
+  end
+end

data/lib/redhound/analysis/tcp_reassembler.rb

@@ -0,0 +1,176 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class TcpReassembler
+      # @rbs (?registry: Registry, ?max_bytes: Integer, ?stream_bytes: Integer, ?protocol_streams: bool, ?follow: untyped) -> void
+      def initialize(registry: Registry.default, max_bytes: 64 << 20, stream_bytes: 1 << 20, protocol_streams: true, follow: nil)
+        @registry, @max_bytes, @stream_bytes, @protocol_streams, @follow = registry, max_bytes, stream_bytes, protocol_streams, follow
+      end
+      # @rbs (Packet packet, Flow flow, Integer direction) -> void
+      def update(packet, flow, direction)
+        layer = packet.layers.reverse.find { |item| item.protocol == :tcp && !item.embedded }
+        return unless layer && !layer.error? && layer[:seq] && layer[:flags]
+        stream = flow.streams[direction] ||= TcpStream.new(max_bytes: @stream_bytes)
+        application = flow.applications[direction]
+        if !application && @protocol_streams
+          klass = @registry.by_port('tcp.port', layer[:srcport], layer[:dstport])
+          unless klass
+            recognized = packet.layers.find { |item| (candidate = @registry.protocols[item.protocol]) && candidate <= StreamDissector }
+            klass = recognized ? @registry.protocols[recognized.protocol] : flow.applications[1 - direction]&.class
+          end
+          flow.applications[direction] = create_application(klass, flow, direction, layer) if klass && klass <= StreamDissector
+          application = flow.applications[direction]
+        end
+        TcpAnalysis.update(flow, direction, stream, layer, packet.timestamp_ns)
+        flags = layer[:flags]
+        data = packet.data.byteslice(layer.payload_offset, layer.payload_end - layer.payload_offset) #: String
+        stream.push(layer[:seq], data, syn: flags & 2 != 0, fin: flags & 1 != 0, frame: packet.number)
+        # Packet-local application parsing cannot frame a multi-segment PDU.
+        if application
+          index = packet.layers.index(layer) #: Integer
+          packet.layers.slice!(index + 1, packet.layers.length)
+        end
+        stream.diagnostics.uniq.each do |code|
+          if %i[retransmission out_of_order lost_segment].include?(code)
+            TcpAnalysis.flag(layer, code) unless layer.field_value('tcp.analysis.keep_alive')
+          else
+            layer.diagnose(:warning, code)
+          end
+        end
+        deliver(flow, direction, stream, application, packet)
+        if flags & 4 != 0
+          finish_flow(flow, packet)
+        elsif flow.streams.compact.size == 2 && flow.streams.compact.all?(&:fin_seen?)
+          finish_flow(flow, packet)
+        elsif stream.fin
+          attach(packet, invoke(flow, direction, application, :on_close)) if application
+          flow.closed_ns ||= packet.timestamp_ns if flow.streams.compact.size == 2 && flow.streams.compact.all?(&:fin)
+        end
+      end
+      # @rbs (Flow flow, Integer direction, TcpStream stream, untyped application, Packet? packet) -> Array[Layer]
+      def deliver(flow, direction, stream, application, packet)
+        completed = [] #: Array[Layer]
+        stream.deliveries.each do |data, origin|
+          unless data
+            gap = Layer.new(:tcp, 0, 0, 0).diagnose(:warning, :reassembly_gap, "#{origin} TCP bytes missing")
+            packet&.[](:tcp)&.diagnose(:warning, :reassembly_gap, gap.diagnostics.first.message)
+            completed << gap unless packet
+            flow.probes[direction].clear
+            flow.probe_disabled[direction] = false
+            application = flow.applications[direction]
+            layers = application ? invoke(flow, direction, application, :on_gap, origin) : Array.new #: Array[Layer]
+            completed.concat(layers)
+            attach(packet, layers) if packet
+            next
+          end
+          @follow&.write(flow, direction, data)
+          layers = application_data(flow, direction, data, origin, packet)
+          attach(packet, layers) if packet
+          completed.concat(layers)
+        end
+        completed
+      ensure
+        stream.clear_deliveries
+      end
+      # @rbs (Flow flow, Integer direction, String data, Integer origin, Packet? packet) -> Array[Layer]
+      def application_data(flow, direction, data, origin, packet)
+        application = flow.applications[direction]
+        probe = flow.probes[direction]
+        unless application
+          return [] unless @protocol_streams && !flow.probe_disabled[direction]
+          sample = (probe.map(&:first).join + data.byteslice(0, 128)).byteslice(0, 128) #: String
+          ctx = Context.new(Packet.new(sample), registry: @registry)
+          ctx.layers << Layer.new(:tcp, 0, 0, sample.bytesize)
+          klass = @registry.heuristic(:tcp, ctx, ctx.cursor)
+          if klass && klass <= StreamDissector
+            diagnostic_layer = packet&.[](:tcp) || Layer.new(:tcp, 0, 0, 0)
+            application = flow.applications[direction] = create_application(klass, flow, direction, diagnostic_layer)
+            return packet ? [] : [diagnostic_layer] unless application
+            if packet
+              position = packet.layers.index { |layer| layer.protocol == :tcp && !layer.embedded }
+              packet.layers.slice!(position + 1, packet.layers.size) if position
+            end
+          else
+            if sample.bytesize < 128 && probe.sum { |bytes, _frame| bytes.bytesize * 2 + 128 } + data.bytesize * 2 + 128 <= @stream_bytes
+              probe << [data.dup, origin]
+            else
+              probe.clear
+              flow.probe_disabled[direction] = true
+            end
+            return []
+          end
+        end
+        chunks = probe + [[data, origin]]
+        probe.clear
+        chunks.flat_map { |bytes, frame| invoke(flow, direction, application, :on_data, bytes, frame) }
+      rescue StandardError => error
+        [application_error(flow, direction, :tcp, error)]
+      end
+      # @rbs (untyped klass, Flow flow, Integer direction, Layer layer) -> untyped
+      def create_application(klass, flow, direction, layer)
+        klass.new(registry: @registry, max_bytes: @stream_bytes)
+      rescue StandardError => error
+        layer.diagnostics.concat(application_error(flow, direction, klass.protocol_id, error).diagnostics)
+        nil
+      end
+      # @rbs (Flow flow, Integer direction, untyped application, Symbol method, *untyped arguments) -> Array[Layer]
+      def invoke(flow, direction, application, method, *arguments)
+        layers = application.public_send(method, flow, direction, *arguments)
+        raise TypeError, 'stream callback must return an array of Layers' unless layers.is_a?(Array) && layers.all? { |layer| layer.is_a?(Layer) }
+        layers
+      rescue StandardError => error
+        [application_error(flow, direction, application.class.protocol_id, error)]
+      end
+      # @rbs (Flow flow, Integer direction, Symbol protocol, StandardError error) -> Layer
+      def application_error(flow, direction, protocol, error)
+        raise error if ENV['REDHOUND_STRICT'] == '1'
+        flow.applications[direction] = nil
+        flow.probes[direction].clear
+        flow.probe_disabled[direction] = true
+        Layer.new(protocol, 0, 0, 0).diagnose(:error, :dissector_bug, "#{error.class}: #{error.message}")
+      end
+      # @rbs (Packet packet, Array[Layer] layers) -> void
+      def attach(packet, layers)
+        layers.each do |layer|
+          layer.add(:reassembled_in, 'tcp.reassembled_in', packet.number)
+          packet.layers << layer
+        end
+      end
+      # @rbs (Flow flow, ?Packet? packet) -> Array[Layer]
+      def finish_flow(flow, packet = nil)
+        completed = [] #: Array[Layer]
+        flow.streams.each_with_index do |stream, direction|
+          next unless stream
+          application = flow.applications[direction]
+          while stream.pending?
+            stream.flush_gap
+            completed.concat(deliver(flow, direction, stream, application, packet))
+          end
+          application = flow.applications[direction]
+          if application
+            layers = invoke(flow, direction, application, :on_close)
+            attach(packet, layers) if packet
+            completed.concat(layers)
+          end
+          stream.release
+        end
+        flow.http_methods.each(&:clear)
+        flow.probes.each(&:clear)
+        flow.closed_ns ||= packet ? packet.timestamp_ns : flow.last_ns
+        completed
+      end
+      # @rbs (FlowTable flows, Packet packet) -> void
+      def enforce_limit(flows, packet)
+        while flows.tcp_bytesize > @max_bytes
+          flow = flows.evict(:tcp)
+          break unless flow
+          packet.layers.last.diagnose(:warning, :reassembly_gap, 'TCP reassembly memory limit exceeded')
+        end
+      end
+    end
+  end
+end

data/lib/redhound/analysis/tcp_stream.rb

@@ -0,0 +1,156 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class TcpStream
+      attr_reader :base_seq, :expected, :diagnostics, :deliveries, :gap_lengths, :fin
+      # @rbs (?max_bytes: Integer) -> void
+      def initialize(max_bytes: 1 << 20)
+        raise ArgumentError, 'max_bytes must be positive' unless max_bytes.positive?
+        @max_bytes, @expected, @history_start = max_bytes, 0, 0
+        @highest = 0
+        @base_seq = nil # @rbs Integer?
+        @history = ''.b
+        @queue = [] #: Array[untyped]
+        @diagnostics, @deliveries, @gap_lengths = [], [], [] # @rbs untyped
+        @fin, @fin_offset = false, nil # @rbs untyped
+      end
+      # @rbs (Integer sequence, String data, ?syn: bool, ?fin: bool, ?frame: Integer) -> Array[String]
+      def push(sequence, data, syn: false, fin: false, frame: 0)
+        @diagnostics, @deliveries, @gap_lengths = [], [], []
+        if @base_seq && ((syn && sequence == @base_seq) || (fin && Util::Seq.lt((sequence + data.bytesize) % Util::Seq::MOD, next_sequence)))
+          @diagnostics << :retransmission
+        end
+        unless @base_seq
+          @base_seq = sequence
+          @expected = syn ? 1 : 0
+          @history_start = @expected
+          @highest = @expected
+        end
+        base = @base_seq #: Integer
+        start = @expected + Util::Seq.signed_diff(sequence, (base + @expected) % Util::Seq::MOD) + (syn ? 1 : 0)
+        @fin_offset = start + data.bytesize if fin
+        @diagnostics << :out_of_order if !data.empty? && start >= @expected && start < @highest
+        @diagnostics << :lost_segment if (!data.empty? || fin) && start > @highest
+        @diagnostics << :retransmission if !data.empty? && start < @expected
+        @highest = [@highest, start + data.bytesize + (fin ? 1 : 0)].max
+        pieces = [[start, data, frame]]
+        if start < @expected
+          length = [data.bytesize, @expected - start].min
+          compare_overlap(start, data, @history_start, @history)
+          pieces = length >= data.bytesize ? Array.new : [[start + length, data.byteslice(length..), frame]] #: Array[untyped]
+        end
+        @queue.each do |old_start, old_data, _old_frame|
+          replacement = [] #: Array[untyped]
+          pieces.each do |pos, bytes, origin|
+            compare_overlap(pos, bytes, old_start, old_data)
+            ending, old_end = pos + bytes.bytesize, old_start + old_data.bytesize
+            if pos < old_end && ending > old_start
+              replacement << [pos, bytes.byteslice(0, old_start - pos), origin] if pos < old_start
+              replacement << [old_end, bytes.byteslice(old_end - pos..), origin] if ending > old_end
+            else
+              replacement << [pos, bytes, origin]
+            end
+          end
+          pieces = replacement
+        end
+        if !data.empty? && pieces.empty?
+          @diagnostics.delete(:out_of_order)
+          @diagnostics.delete(:lost_segment)
+          @diagnostics << :retransmission unless @diagnostics.include?(:retransmission)
+        end
+        pieces.each do |piece|
+          next if piece[1].empty?
+          index = @queue.bsearch_index { |entry| entry[0] >= piece[0] } || @queue.length
+          @queue.insert(index, piece)
+        end
+        drain
+        while bytesize > @max_bytes || (@queue.first && @queue.first[0] - @expected > @max_bytes)
+          break if @queue.empty?
+          flush_gap(false)
+        end
+        trim_history
+        consume_fin
+        @deliveries.filter_map(&:first)
+      end
+
+      # @rbs (Integer start, String data, Integer old_start, String old_data) -> void
+      def compare_overlap(start, data, old_start, old_data)
+        from = [start, old_start].max
+        to = [start + data.bytesize, old_start + old_data.bytesize].min
+        return unless from < to
+        if data.byteslice(from - start, to - from) != old_data.byteslice(from - old_start, to - from) && !@diagnostics.include?(:overlap_mismatch)
+          @diagnostics << :overlap_mismatch
+        end
+      end
+      # @rbs () -> void
+      def drain
+        while @queue.first && @queue.first[0] == @expected
+          pos, data, frame = @queue.shift
+          @deliveries << [data, frame]
+          @history_start = pos if @history.empty?
+          @history << data
+          @expected += data.bytesize
+        end
+      end
+      # @rbs (?bool clear) -> Array[String]
+      def flush_gap(clear = true)
+        @deliveries, @gap_lengths = [], [] if clear
+        target = @queue.empty? ? @fin_offset : @queue.first[0]
+        return [] unless target
+        gap = target - @expected
+        if gap.positive?
+          @diagnostics << :reassembly_gap
+          @gap_lengths << gap
+          @deliveries << [nil, gap]
+          @expected += gap
+          @history.clear
+          @history_start = @expected
+        end
+        drain
+        consume_fin
+        trim_history
+        @deliveries.filter_map(&:first)
+      end
+      # @rbs () -> void
+      def trim_history
+        # Previously delivered bytes share the stream's bounded budget with holes.
+        # Ruby grows mutable String buffers geometrically. Reserve twice their
+        # length plus object storage so capacity also stays inside the budget.
+        limit = [(@max_bytes - @queue.sum { |item| item[1].bytesize * 2 + 168 } - 40) / 2, 0].max
+        excess = @history.bytesize - limit
+        if excess.positive?
+          @history = @history.byteslice(excess..) #: String
+          @history_start += excess
+        end
+      end
+      # @rbs () -> Integer
+      def bytesize = (@history.empty? ? 0 : @history.bytesize * 2 + 40) + @queue.sum { |item| item[1].bytesize * 2 + 168 }
+      # @rbs () -> bool
+      def pending? = !@queue.empty? || (!@fin && !@fin_offset.nil?)
+      # @rbs () -> bool
+      def fin_seen? = !@fin_offset.nil?
+      # @rbs () -> void
+      def consume_fin
+        if !@fin && @fin_offset && @expected >= @fin_offset
+          @fin = true
+          @expected += 1
+        end
+      end
+      # @rbs () -> Integer
+      def next_sequence = ((@base_seq || 0) + @expected) % Util::Seq::MOD
+      # @rbs () -> void
+      def clear_deliveries = @deliveries.clear
+      # @rbs () -> void
+      def release
+        @history.clear
+        @queue.clear
+        @deliveries.clear
+        @gap_lengths.clear
+      end
+    end
+  end
+end

data/lib/redhound/analysis.rb

@@ -0,0 +1,157 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative 'util/seq'
+require_relative 'stream_dissector'
+require_relative 'analysis/flow_key'
+require_relative 'analysis/tcp_stream'
+require_relative 'analysis/flow_table'
+require_relative 'analysis/ip_reassembler'
+require_relative 'analysis/tcp_analysis'
+require_relative 'analysis/tcp_reassembler'
+require_relative 'analysis/stats'
+require_relative 'output/follow'
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class Session
+      attr_reader :flows, :ip_reassembler, :tcp_reassembler, :statistics
+      # @rbs (?stats: Array[String], ?follow: String?, ?registry: Registry, ?max_state_bytes: Integer, ?max_flows: Integer, ?ip_bytes: Integer, ?tcp_bytes: Integer, ?stream_bytes: Integer, ?protocol_streams: bool) -> void
+      def initialize(stats: [], follow: nil, registry: Registry.default, max_state_bytes: 256 << 20, max_flows: 100_000,
+                     ip_bytes: 16 << 20, tcp_bytes: 64 << 20, stream_bytes: 1 << 20, protocol_streams: true)
+        raise ArgumentError, 'state limit must be positive' unless max_state_bytes.positive?
+        @max_state_bytes, @finished = max_state_bytes, false
+        @flows = FlowTable.new(max_flows: max_flows)
+        @ip_reassembler = IpReassembler.new(max_bytes: [ip_bytes, max_state_bytes].min)
+        @follow = follow ? Output::Follow.new(follow) : nil
+        @tcp_reassembler = TcpReassembler.new(registry: registry, max_bytes: [tcp_bytes, max_state_bytes].min,
+                                             stream_bytes: stream_bytes, protocol_streams: protocol_streams, follow: @follow)
+        @removed_gaps, @removed_incomplete, @removed_bugs = 0, 0, 0
+        @flows.on_remove = lambda do |flow|
+          @tcp_reassembler.finish_flow(flow).each do |layer|
+            layer.diagnostics.each do |diagnostic|
+              @removed_gaps += 1 if diagnostic.code == :reassembly_gap
+              @removed_incomplete += 1 if diagnostic.code == :truncated
+              @removed_bugs += 1 if diagnostic.code == :dissector_bug
+            end
+          end
+        end
+        specs = stats.uniq
+        raise ConfigurationError, 'too many statistics specifications (maximum 64)' if specs.size > 64
+        row_limit = [100_000, [((128 << 20) / [specs.size, 1].max) / 1024, 1].max].min
+        @statistics = specs.map { |spec| statistic(spec, row_limit) }
+      end
+      # @rbs (String specification, Integer max_rows) -> untyped
+      def statistic(specification, max_rows)
+        kind, argument = specification.split(',', 2)
+        case kind
+        when 'io'
+          raise ConfigurationError, 'io statistics requires an interval of at least one nanosecond' unless argument && argument.match?(/\A(?:\d+(?:\.\d*)?|\.\d+)\z/) && argument.to_f.finite? && argument.to_f >= 0.000_000_001
+          Stats::Io.new(argument.to_f, max_rows: max_rows)
+        when 'conv', 'endpoints'
+          raise ConfigurationError, 'statistics type must be eth, ip, ipv6, tcp or udp' unless argument && %w[eth ip ipv6 tcp udp].include?(argument)
+          klass = kind == 'conv' ? Stats::Conversations : Stats::Endpoints
+          klass.new(argument.to_sym, max_rows: max_rows)
+        when 'phs'
+          raise ConfigurationError, 'phs does not accept an argument' if argument
+          Stats::Hierarchy.new(max_rows: max_rows)
+        else raise ConfigurationError, "unknown statistics: #{specification}"
+        end
+      end
+      # @rbs (Packet packet) -> void
+      def update(packet)
+        return if @finished
+        @flows.advance(packet.timestamp_ns)
+        @ip_reassembler.advance(packet.timestamp_ns)
+        fragment = @ip_reassembler.descriptor(packet)
+        analyzed = packet
+        if fragment
+          boundary = packet.layers.index(fragment[1]) #: Integer
+          packet.layers.slice!(boundary + 1, packet.layers.length)
+          virtual = @ip_reassembler.update(packet)
+          if virtual
+            packet.meta[:reassembled_from] = virtual.meta[:reassembled_from]
+            packet.meta[:reassembled_packet] = virtual
+            analyzed = virtual
+          else
+            @statistics.each { |stat| stat.update(packet) }
+            enforce_limit(packet)
+            return
+          end
+        end
+        result = @flows.update(analyzed)
+        if result
+          flow, direction = result
+          @tcp_reassembler.update(analyzed, flow, direction) if flow.key[0] == :tcp
+          @flows.account(flow)
+        end
+        if analyzed != packet
+          packet.layers.concat(analyzed.layers.reject { |layer| %i[ipv4 ipv6 ipv6_ext].include?(layer.protocol) })
+          packet.layers.last.add(:ip_reassembled_from, 'ip.reassembled_from', packet.meta[:reassembled_from])
+        end
+        @statistics.each { |stat| stat.update(packet) }
+        @tcp_reassembler.enforce_limit(@flows, packet)
+        enforce_limit(packet)
+      end
+      # @rbs (Packet packet) -> void
+      def enforce_limit(packet)
+        while bytesize > @max_state_bytes
+          flow = @flows.evict
+          unless flow
+            statistic = @statistics.max_by(&:bytesize)
+            break unless statistic && statistic.bytesize.positive?
+            statistic.evict
+          end
+          packet.layers.last.diagnose(:warning, :state_evicted, 'analysis state memory limit exceeded')
+        end
+      end
+      # @rbs () -> Integer
+      def bytesize = @flows.bytesize + @ip_reassembler.bytesize + @statistics.sum(&:bytesize)
+      # @rbs (untyped err) -> void
+      def snapshot(err)
+        @statistics.each { |stat| stat.format(err) }
+        err.puts("#{@removed_gaps} TCP reassembly_gap events during flow removal") if @removed_gaps.positive?
+        err.puts("#{@removed_incomplete} truncated application PDUs during flow removal") if @removed_incomplete.positive?
+        err.puts("#{@removed_bugs} dissector_bug events during flow removal") if @removed_bugs.positive?
+        err.puts("#{@flows.evicted} flows evicted; #{@flows.expired} flows expired") if @flows.evicted.positive? || @flows.expired.positive?
+        err.puts("#{@ip_reassembler.evicted} fragmented datagrams evicted; #{@ip_reassembler.expired} expired") if @ip_reassembler.evicted.positive? || @ip_reassembler.expired.positive?
+      end
+      # @rbs (untyped out, untyped err) -> void
+      def finish(out, err)
+        return if @finished
+        @flows.values.each do |flow|
+          @tcp_reassembler.finish_flow(flow).each do |layer|
+            layer.diagnostics.each do |diagnostic|
+              message = diagnostic.message.b.gsub(/[^\x20-\x7e]/n) { |byte| format('\\x%02x', byte.getbyte(0)) }
+              err.puts("stream #{flow.id} #{layer.protocol}: #{diagnostic.code}: #{message}")
+            end
+          end
+          @flows.account(flow)
+        end
+        incomplete = @ip_reassembler.finish
+        err.puts("#{incomplete} incomplete IP datagrams: reassembly_gap at EOF") if incomplete.positive?
+        @follow&.format(out)
+        snapshot(err)
+      ensure
+        original_error = $!
+        @finished = true
+        @flows.values.each do |flow|
+          flow.streams.compact.each(&:release)
+          flow.applications.fill(nil)
+          flow.http_methods.each(&:clear)
+          flow.probes.each(&:clear)
+          flow.closed_ns ||= flow.last_ns
+          @flows.account(flow)
+        end
+        @ip_reassembler.finish
+        begin
+          @follow&.close
+        rescue StandardError
+          raise unless original_error
+        end
+      end
+    end
+  end
+end