redhound 1.0.1 → 2.0.0.rc2

data/docs/VALIDATION.md

@@ -0,0 +1,175 @@
+# Release validation
+
+## Adversarial review after rc1
+
+The review checked the design, roadmap, work procedures and phase0 patch against
+the running implementation, rather than treating a green test suite as proof
+that every acceptance gate had passed. Reproduced failures included truncated
+headers losing readable fields, incorrect ICMP error fields and dynamic field
+locations, missed split HTTP identification, unreported reassembly loss at EOF
+and flow eviction, underestimated Ruby buffer capacity, unbounded pcapng
+metadata, source timeout violations and capture writer descriptor leaks.
+Regression checks accompany the fixes.
+
+The parser fuzz now retains each fixture's real link type during structured
+mutations. This prevents tests from stopping at an unrelated link header before
+reaching the mutated protocol. `ruby bench/analysis.rb` exercises default state
+limits with 60,000 conversations, 40,000 fragmented datagram identities and 80
+large TCP streams, checking every update and final buffer release. Its retained
+state accounting includes String capacity and object storage. Process RSS is
+reported separately: Ruby may retain allocator pages after state is released.
+
+The manual [Live acceptance workflow](../.github/workflows/acceptance.yml) and
+`bench/live.rb` record requested/sent/captured counts, gaps, byte digests, kernel
+timestamps, drops, RSS and descriptor counts. An insufficient sender rate fails
+the check. Controlled aarch64 runs passed 50,000 pps with simultaneous socket and
+ring capture and 80,000 pps with socket capture for ten seconds. These short
+checks do not replace the hour-long comparison or the x86_64 targets.
+The strengthened live harness checks complete expected wire bytes, every
+timestamp and the entire zero-based sequence. Its mixed TCP/UDP workload and
+capture-only CPU affinity are recorded alongside implementation and harness
+digests. The earlier long-running snapshot uses the original UDP workload and
+verifier; its comparison requires identical complete-frame digests and sampled
+timestamps, and does not establish the new mixed single-core throughput gate.
+
+Local adversarial runtime validation on 2026-10-02 passed all 244 non-live examples
+on Linux, with only the macOS-specific interface test skipped. After adding
+bounded file prefetch and live-harness regressions, the complete macOS Rake task
+passed its 257 examples (20 tshark comparisons are run on Linux), RBS generation
+and Steep, with 92.92% total line coverage. Coverage gates passed; the earlier
+Linux check measured 92.43% total line coverage. The strengthened one-million-case parser fuzz completed without an
+exception. Default state-pressure checks reached exactly 256 MiB accounted
+state without exceeding it and released IP/TCP buffers at EOF. Native RSS
+reached 308 MiB despite retaining only 107 MiB of Ruby heap before finalization;
+this is not reported as a 256 MiB process-RSS guarantee.
+The independent [manual CI and million-case fuzz run](https://github.com/ydah/redhound/actions/runs/36885293639)
+also passed every job on the adversarial runtime fixes.
+
+The GitHub maintenance configuration now includes weekly Bundler/Actions
+dependency updates, actionlint, codespell, strict yamllint, zizmor and Ruby/Actions
+CodeQL analysis. Action revisions are pinned and checkout credentials are not
+retained. All four lint workflows passed on main; the final CodeQL run succeeded
+with no open alerts. HTTP header trimming uses
+bounded byte ranges while preserving SP/HTAB-only whitespace semantics; controls
+remain visible to malformed-header diagnostics.
+After this final parser change, all 16 application-boundary/live-harness examples,
+the one-million-case native fuzz run (94.25 seconds), and Steep passed.
+All 5,013 binary boundary/random inputs preserved the previous trimming bytes
+and encoding. Linux tcpdump/tshark comparisons passed all 26 examples.
+
+Ruby 4.0 introduced an additional restriction in
+[`IO::Buffer.map`](https://docs.ruby-lang.org/en/4.0/IO/Buffer.html#method-c-map):
+it rejects files with zero size even when a mapping size is supplied. Linux
+AF_PACKET sockets have zero file size, so the pure-Ruby ring backend cannot map
+them on that runtime. Ruby 3.3/3.4 ring support remains available; Ruby 4.0 uses
+the socket backend. No C extension or Fiddle workaround is introduced. Ring
+availability on Ruby 4.0 remains an upstream API constraint on full acceptance.
+
+Long-running controlled tests started at 2026-10-01 14:55:57 UTC with a frozen
+capture implementation digest
+`084591da70d195146b37aff76de7ec9495085d045684decc26da6c34c4ebc20e`:
+
+| Check | Requested workload | Evidence directory | Earliest completion |
+| --- | --- | --- | --- |
+| aarch64 socket/ring comparison | 50,000 pps, 3,600 seconds | `tmp/acceptance-arm-hour-final` | 2026-10-01 15:55:58 UTC |
+| Bounded ring pcapng rotation | 100 pps, 259,200 seconds | `tmp/acceptance-rotation-72h-final` | 2026-10-04 14:55:58 UTC |
+
+These directories contain local private captures and are excluded from Git.
+Completion requires the final `result.json` to pass, inspection of the periodic
+resource samples, and successful external validation of rotated files. The
+controlled veth soak does not establish the separate busy physical-interface
+24-hour gate. Results and unfulfilled conditions are recorded explicitly below.
+
+The frozen rotation run first reported 1,178 kernel drops and three ring freezes
+at the 4,200-second sample, after zero drops at 3,600 seconds. The macOS power log
+records hibernation/wake in that interval with a 10.614-second recovery delay.
+This correlation does not isolate the cause, and the run is not loss-free
+acceptance evidence. Its periodic resource observations are retained. External
+capinfos/tshark inspection now runs after capture closes, validating the three
+retained rotation files rather than blocking packet reads at every rotation.
+A four-second rotation smoke captured and verified all 4,000 frames without
+drops, gaps or malformed records and passed both external tools.
+
+A fresh frozen-source rotation run started at 2026-10-01 16:22:04 UTC, using
+capture digest
+`7fd49cc4c24664c298c99dbf35276f64e67a1195093c3e1c4f9190fa9d234014`
+and harness digest
+`55b36abe852549836350d51ea9994b71ded5409794d853777f0634ca6830c760`.
+Its private evidence is in `tmp/acceptance-rotation-72h-rc2`; completion cannot
+be checked before 2026-10-04 16:22:06 UTC. macOS idle/system sleep assertions
+were confirmed on AC power with a 72-hour-plus-ten-minute `caffeinate` timer.
+This run is still in progress and does not count as completed acceptance.
+
+The one-hour aarch64 comparison completed successfully: each backend captured
+all 180,000,000 frames with zero drops/gaps and the same complete-byte digest.
+All 18,000 paired timestamp samples were identical. Ring final drain was
+47.638 ms; descriptor counts remained 10/11. Last-half-hour RSS ranged from
+31.2–40.2 MiB for sockets and 86.5–86.6 MiB for rings. P6-06 is complete, so
+aarch64/arm64 Linux now tries ring capture automatically, retaining socket
+fallback when mapping is unavailable. This does not complete the separate
+72-hour rotation soak or the mixed x86_64 throughput gates.
+
+The physical macOS en0 interface is active, but `/dev/bpf*` requires administrator
+access and `sudo -n` requires a password in this environment. The user could not
+start the privileged run, so the 24-hour physical-interface check has not begun.
+An independent three-second observation measured approximately 82 packets/s and
+21 kB/s; it does not establish a busy workload. `bench/soak.rb` is ready to record
+24-hour elapsed time, bounded private pcapng rotation, traffic rates, RSS and
+descriptor counts once capture privileges are available. Its one-second Linux
+smoke and interrupted-run checks passed, including capinfos/tshark file checks.
+
+## 2.0.0.rc1
+
+The release candidate implements the functional parts of the v2 roadmap: the packet/dissector API, network and
+application protocols, Ruby cBPF compiler/VM, Linux socket/ring and macOS BPF
+backends, capture files/rotation/privilege drop, bounded stateful analysis,
+statistics, follow output and documentation. This is a release candidate,
+not a claim that time-dependent GA acceptance checks have completed.
+
+Reproducible checks:
+
+- `bundle exec rake`: RSpec, generated RBS and Steep.
+- `REDHOUND_COVERAGE_GATE=1 bundle exec rake`: at least 90% total line coverage
+  and 95% protocol line coverage.
+- `bundle exec rspec spec/differential`: tcpdump filter match/bytecode parity
+  (163 expressions across five link types), tshark protocol and stateful analysis
+  field/statistics/follow comparisons.
+- `FUZZ_ITERATIONS=1000000 bundle exec rspec spec/fuzz`: strict parser fuzzing.
+- `sudo -E env "PATH=$PATH" REDHOUND_LIVE=1 bundle exec rspec --tag live`:
+  native capture, attached filters, kernel time, snaplen, stop and loopback.
+- `sudo -E env "PATH=$PATH" REDHOUND_LIVE=1 REDHOUND_NETNS=1 bundle exec rspec spec/integration/netns_capture_spec.rb --tag live`:
+  Linux veth socket/ring parity and offloaded VLAN restoration/filtering.
+- `bundle exec yard stats --list-undoc`: documented public API.
+- `actionlint`: test and release workflow validation.
+
+Fixtures are generated without runtime dependencies. Golden output freezes
+addresses and timestamps, and validates all JSON snapshots against the schema.
+The CI matrix checks Ruby 3.3/3.4/4.0/head, Linux/macOS live capture and tool
+comparisons. Scheduled runs execute one million fuzz cases. Benchmark jobs warn
+on a summary throughput regression over 15% compared with the previous commit.
+
+Local validation on 2026-10-01: Linux aarch64 Ruby 3.4 passed all 171 non-live
+examples, including tcpdump/tshark differential checks, and five live capture
+examples using socket and ring backends. Native macOS Ruby 4.0 passed unit,
+golden and filter checks; BPF ioctl constants match the installed SDK. Native
+BPF loopback and en0 Ethernet capture, attached filters, timestamps, truncation,
+termination, privilege dropping and pcapng metadata passed the macOS CI job.
+The Linux namespace test passed socket/ring parity and offloaded VLAN checks.
+Ruby 3.3/3.4/4.0/head all passed the CI type, signature and coverage gates.
+Whole-library line coverage measured 90.92%; isolated protocol line coverage
+measured 99.90%. See [benchmarks](../bench/RESULTS.md)
+for throughput figures and measurement limits.
+
+## Remaining GA acceptance gates
+
+- Run a 24-hour continuous capture stability check.
+- Run a 72-hour rotation soak and record RSS, descriptor counts and drop rates.
+- Confirm x86_64 single-core throughput and live drop targets on the specified
+  workload; file benchmarks alone cannot establish loss-free live throughput.
+- Keep rc1 available for two weeks, classify reports, and fix critical/high
+  failures before GA.
+
+These elapsed-time/hardware gates are not marked complete by unit tests.
+Promote to 2.0.0 only after their evidence is recorded. A 1.x maintenance
+end date is set at GA plus six months; no maintenance branch is created by this
+main-only implementation.

data/docs/json-schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ydah/redhound/blob/main/docs/json-schema.json",
+  "title": "Redhound packet",
+  "description": "One packet object emitted by Packet#to_h, NDJSON, or an element of the JSON output array. Nanosecond timestamps and lengths are integers; byte fields use hexadecimal strings; repeated fields use arrays.",
+  "type": "object",
+  "required": ["frame", "layers", "diagnostics"],
+  "additionalProperties": false,
+  "properties": {
+    "frame": {
+      "type": "object",
+      "required": ["number", "time_epoch_ns", "time", "caplen", "len", "interface", "direction", "linktype"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "time_epoch_ns": { "type": "integer" },
+        "time": { "type": "string", "description": "UTC calendar time with nine fractional digits; years outside 0000..9999 use expanded signed/long year notation. time_epoch_ns preserves the exact instant.", "pattern": "^-?[0-9]{4,}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{9}Z$" },
+        "caplen": { "type": "integer", "minimum": 0 },
+        "len": { "type": "integer", "minimum": 0 },
+        "interface": { "type": ["string", "null"] },
+        "direction": { "enum": ["in", "out", null] },
+        "linktype": { "type": "integer", "minimum": 0, "maximum": 65535 }
+      }
+    },
+    "layers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["protocol", "offset", "length", "embedded", "fields"],
+        "additionalProperties": false,
+        "properties": {
+          "protocol": { "type": "string" },
+          "offset": { "type": "integer", "minimum": 0 },
+          "length": { "type": "integer", "minimum": 0 },
+          "embedded": { "type": "boolean" },
+          "fields": { "type": "object", "additionalProperties": { "$ref": "#/$defs/fieldValue" } }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["layer", "severity", "code", "message", "field"],
+        "additionalProperties": false,
+        "properties": {
+          "layer": { "type": "string" },
+          "severity": { "enum": ["note", "warn", "warning", "error"] },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "field": { "type": ["string", "null"] }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "fieldValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/$defs/fieldValue" } }
+      ]
+    }
+  }
+}

data/exe/redhound

@@ -4,4 +4,5 @@
 $LOAD_PATH << File.join(__dir__, '../lib')
 require 'redhound'
 
-Redhound::Command.new.run(ARGV.dup)
+RubyVM::YJIT.enable if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable) && !ARGV.include?('--no-yjit')
+exit Redhound::CLI::Command.new.run(ARGV.dup)

data/lib/redhound/analysis/flow_key.rb

@@ -0,0 +1,59 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module FlowKey
+      # @rbs (Packet packet, ?Symbol? type) -> untyped
+      def self.from(packet, type = nil)
+        layers = packet.layers.reject(&:embedded)
+        if type == :eth
+          layer = layers.find { |item| item.protocol == :eth }
+          return nil unless layer && layer[:src] && layer[:dst]
+          return normalize(:eth, [layer.display(:src), 0], [layer.display(:dst), 0])
+        end
+        transport = layers.reverse.find { |item| %i[tcp udp icmp icmpv6].include?(item.protocol) }
+        if type && %i[tcp udp].include?(type)
+          return nil unless transport && transport.protocol == type
+        end
+        network = if type == :ip || type == :ipv6
+                    layers.find { |item| item.protocol == (type == :ip ? :ipv4 : :ipv6) }
+                  elsif transport
+                    position = layers.index(transport) #: Integer
+                    layers.take(position).reverse.find { |item| %i[ipv4 ipv6].include?(item.protocol) }
+                  else
+                    layers.reverse.find { |item| %i[ipv4 ipv6].include?(item.protocol) }
+                  end
+        return nil unless network && network[:src] && network[:dst]
+        proto = type || transport&.protocol
+        unless proto
+          position = layers.index(network) #: Integer
+          extensions = layers.drop(position + 1).take_while { |item| item.protocol == :ipv6_ext }
+          number = network.protocol == :ipv4 ? network[:proto] : extensions.last&.[](:next) || network[:nxt]
+          proto = "ip_proto_#{number}".to_sym
+        end
+        if %i[tcp udp].include?(proto)
+          return nil unless transport && transport[:srcport] && transport[:dstport]
+          ports = [transport[:srcport], transport[:dstport]]
+        elsif %i[icmp icmpv6].include?(proto)
+          return nil unless transport
+          # Echo request/reply share a type series and identifier in both directions.
+          series = { 8 => 0, 128 => 129 }.fetch(transport[:type], transport[:type])
+          ports = [[series, transport[:ident] || 0], [series, transport[:ident] || 0]]
+        else
+          ports = [0, 0]
+        end
+        normalize(proto, [network.display(:src), ports[0]], [network.display(:dst), ports[1]])
+      end
+
+      # @rbs (Symbol proto, untyped src, untyped dst) -> untyped
+      def self.normalize(proto, src, dst)
+        reverse = (src <=> dst).positive?
+        a, b = reverse ? [dst, src] : [src, dst]
+        [[proto, *a, *b].freeze, reverse ? 1 : 0]
+      end
+    end
+  end
+end

data/lib/redhound/analysis/flow_table.rb

@@ -0,0 +1,124 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class Flow
+      BASE_BYTES = 4096
+      attr_reader :key, :id, :first_ns, :packets, :bytes, :streams, :applications, :acks, :keep_alives, :http_methods, :probes, :probe_disabled
+      attr_accessor :last_ns, :closed_ns, :syn_ns, :syn_direction, :synack_ns, :synack_seq, :initial_rtt, :accounted_bytes
+      # @rbs (untyped key, Integer id, Integer timestamp_ns) -> void
+      def initialize(key, id, timestamp_ns)
+        @key, @id, @first_ns, @last_ns = key, id, timestamp_ns, timestamp_ns
+        @packets, @bytes, @streams, @applications, @acks = [0, 0], [0, 0], [nil, nil], [nil, nil], [nil, nil]
+        @keep_alives = [false, false]
+        @http_methods = [Array.new, Array.new] #: Array[untyped]
+        @probes = [Array.new, Array.new] #: Array[untyped]
+        @probe_disabled = [false, false]
+        @closed_ns = @syn_ns = @syn_direction = @synack_ns = @synack_seq = @initial_rtt = nil # @rbs untyped
+        @accounted_bytes = BASE_BYTES
+      end
+      # @rbs () -> bool
+      def closed? = !@closed_ns.nil?
+      # @rbs () -> Integer
+      def bytesize = BASE_BYTES + @streams.compact.sum(&:bytesize) + @applications.compact.sum(&:bytesize) + @http_methods.sum { |methods| methods.size * 16 } + @probes.sum { |parts| parts.sum { |data, _frame| data.bytesize * 2 + 128 } }
+    end
+
+    # @api private
+    class FlowTable
+      attr_reader :evicted, :expired
+      attr_accessor :on_remove
+      # @rbs (?max_flows: Integer) -> void
+      def initialize(max_flows: 100_000)
+        raise ArgumentError, 'max_flows must be positive' unless max_flows.positive?
+        @max_flows, @next_id, @evicted, @expired, @clock = max_flows, 0, 0, 0, 0
+        @next_sweep, @bytes, @tcp_bytes = 0, 0, 0
+        @on_remove = nil # @rbs untyped
+        @entries = {} #: Hash[untyped, Flow]
+      end
+      # @rbs (Packet packet) -> untyped
+      def update(packet)
+        advance(packet.timestamp_ns)
+        result = FlowKey.from(packet)
+        return nil unless result
+        key, direction = result
+        flow = @entries.delete(key)
+        transport = packet.layers.reverse.find { |layer| layer.protocol == :tcp && !layer.embedded }
+        if flow && transport && transport[:flags] && transport[:flags] & 0x12 == 2
+          previous = flow.streams[direction]
+          if flow.closed? || (previous && previous.base_seq && previous.base_seq != transport[:seq])
+            discard(flow)
+            flow = nil
+          end
+        end
+        unless flow
+          evict if @entries.size >= @max_flows
+          flow = Flow.new(key, key[0] == :tcp ? @next_id : -1, @clock)
+          @next_id += 1 if key[0] == :tcp
+          @bytes += flow.accounted_bytes
+        end
+        flow.last_ns = @clock
+        flow.packets[direction] += 1
+        flow.bytes[direction] += packet.original_length
+        flow.closed_ns = @clock if transport && transport[:flags] && transport[:flags] & 4 != 0
+        @entries[key] = flow
+        [flow, direction]
+      end
+      # @rbs (Integer now_ns) -> void
+      def advance(now_ns)
+        @clock = [@clock, now_ns].max
+        expire(@clock) if @clock >= @next_sweep
+      end
+      # @rbs (Integer now_ns) -> void
+      def expire(now_ns)
+        @next_sweep = now_ns + 1_000_000_000
+        @entries.delete_if do |_key, flow|
+          timeout = flow.closed? ? 10 : flow.key[0] == :tcp ? 120 : 30
+          stale = now_ns - flow.last_ns >= timeout * 1_000_000_000
+          if stale
+            discard(flow)
+            @expired += 1
+          end
+          stale
+        end
+      end
+      # @rbs (?Symbol? type) -> Flow?
+      def evict(type = nil)
+        pair = if type
+                 key = @entries.each_key.find { |item| item[0] == type }
+                 key ? [key, @entries.delete(key)] : nil
+               else
+                 @entries.shift
+               end
+        return nil unless pair
+        @evicted += 1
+        discard(pair[1])
+        pair[1]
+      end
+      # @rbs (Flow flow) -> void
+      def discard(flow)
+        @bytes -= flow.accounted_bytes
+        @tcp_bytes -= flow.accounted_bytes - Flow::BASE_BYTES if flow.key[0] == :tcp
+        @on_remove&.call(flow)
+      end
+      # @rbs (Flow flow) -> void
+      def account(flow)
+        size = flow.bytesize
+        delta = size - flow.accounted_bytes
+        @bytes += delta
+        @tcp_bytes += delta if flow.key[0] == :tcp
+        flow.accounted_bytes = size
+      end
+      # @rbs () -> Integer
+      def size = @entries.size
+      # @rbs () -> Array[Flow]
+      def values = @entries.values
+      # @rbs () -> Integer
+      def bytesize = @bytes
+      # @rbs () -> Integer
+      def tcp_bytesize = @tcp_bytes
+    end
+  end
+end

data/lib/redhound/analysis/ip_reassembler.rb

@@ -0,0 +1,209 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class IpReassembler
+      attr_reader :evicted, :expired
+      # @rbs (?max_bytes: Integer, ?timeout_ns: Integer) -> void
+      def initialize(max_bytes: 16 << 20, timeout_ns: 30_000_000_000)
+        raise ArgumentError, 'fragment limits must be positive' unless max_bytes.positive? && timeout_ns.positive?
+        @max_bytes, @timeout_ns, @clock, @evicted, @expired = max_bytes, timeout_ns, 0, 0, 0
+        @next_sweep = 0
+        @bytes = 0
+        @entries, @discarded = {}, {} # @rbs untyped
+      end
+      # @rbs (Packet packet) -> untyped
+      def descriptor(packet)
+        layers = packet.layers.reject(&:embedded)
+        layers.each_with_index do |layer, index|
+          if layer.protocol == :ipv4 && layer[:src] && layer[:dst] && (layer[:mf] == 1 || layer[:frag_offset].to_i.positive?)
+            return [layer, layer, [4, layer[:src], layer[:dst], layer[:proto], layer[:id]], layer[:frag_offset], layer[:mf] == 1]
+          elsif layer.protocol == :ipv6_ext && layer[:type] == 44 && layer[:fragment_offset] && layer[:identification]
+            # RFC 6946: atomic fragments bypass queued fragments and tombstones.
+            next if layer[:fragment_offset].zero? && layer[:more] == 0
+            network = layers.take(index).reverse.find { |item| item.protocol == :ipv6 }
+            return [network, layer, [6, network[:src], network[:dst], layer[:identification]], layer[:fragment_offset], layer[:more] == 1] if network && network[:src] && network[:dst]
+          end
+        end
+        nil
+      end
+      # @rbs (Packet packet) -> Packet?
+      def update(packet)
+        advance(packet.timestamp_ns)
+        info = descriptor(packet)
+        return nil unless info
+        network, fragment, key, offset, more = info
+        return nil if @discarded[key]
+        return nil if network.error? || fragment.error?
+        length = network.payload_end - fragment.payload_offset
+        if offset + length > 65_535 || length.negative? || (more && (length.zero? || length % 8 != 0))
+          fragment.diagnose(:error, :malformed, 'invalid IP fragment size or offset')
+          remove(key)
+          return nil
+        end
+        if network.diagnostics.any? { |diagnostic| diagnostic.code == :truncated }
+          fragment.diagnose(:note, :reassembly_gap, 'truncated IP fragment cannot be reassembled')
+          return nil
+        end
+        data = packet.data.byteslice(fragment.payload_offset, length) #: String
+        state = remove(key) || { parts: Array.new, frames: Array.new, header: nil, next_offset: 6, next: fragment[:next], end: nil } #: untyped
+        if key[0] == 6 && state[:next] != fragment[:next]
+          fragment.diagnose(:error, :malformed, 'IPv6 fragments have inconsistent next headers')
+          return nil
+        end
+        state[:time] = @clock
+        old_parts = state[:parts]
+        overlap = old_parts.any? { |pos, bytes| offset < pos + bytes.bytesize && offset + length > pos }
+        if overlap
+          fragment.diagnose(:warning, :fragment_overlap, 'overlapping IP fragments')
+          if key[0] == 6
+            @discarded[key] = @clock
+            @bytes += 128
+            while @discarded.size > [4096, @max_bytes / 128].min
+              @discarded.shift
+              @bytes -= 128
+              @evicted += 1
+            end
+            while bytesize > @max_bytes && remove_oldest
+              @evicted += 1
+            end
+            return nil
+          end
+        end
+        pieces = [[offset, data]]
+        old_parts.each do |pos, bytes|
+          replacement = [] #: Array[untyped]
+          pieces.each do |start, payload|
+            ending, old_end = start + payload.bytesize, pos + bytes.bytesize
+            if start < old_end && ending > pos
+              from, to = [start, pos].max, [ending, old_end].min
+              fragment.diagnose(:warning, :overlap_mismatch) if payload.byteslice(from - start, to - from) != bytes.byteslice(from - pos, to - from)
+              replacement << [start, payload.byteslice(0, pos - start)] if start < pos
+              replacement << [old_end, payload.byteslice(old_end - start..)] if ending > old_end
+            else
+              replacement << [start, payload]
+            end
+          end
+          pieces = replacement
+        end
+        first_final = !more && !state[:end]
+        unless more
+          if state[:end] && state[:end] != offset + length
+            fragment.diagnose(:error, :malformed, 'inconsistent final IP fragment length')
+            return nil
+          end
+          state[:end] = offset + length
+        end
+        state[:frames] << packet.number if !pieces.empty? || first_final
+        state[:parts].concat(pieces).sort_by!(&:first)
+        if offset.zero? && !state[:header]
+          state[:header] = packet.data.byteslice(network.offset, fragment.payload_offset - network.offset - (key[0] == 6 ? 8 : 0))
+          if key[0] == 6
+            position = packet.layers.index(fragment) #: Integer
+            previous = packet.layers.take(position).last #: Layer
+            state[:next_offset] = previous == network ? 6 : previous.offset - network.offset
+          end
+        end
+        @entries[key] = state
+        @bytes += state_bytesize(state)
+        if complete?(state)
+          remove(key)
+          return virtual_packet(packet, state, key[0])
+        end
+        while bytesize > @max_bytes
+          removed = remove_oldest
+          break unless removed
+          @evicted += 1
+          fragment.diagnose(:warning, :reassembly_gap, 'IP reassembly memory limit exceeded')
+        end
+        nil
+      end
+      # @rbs (untyped state) -> bool
+      def complete?(state)
+        return false unless state[:header] && state[:end]
+        expected = 0
+        state[:parts].each do |offset, bytes|
+          return false unless offset == expected
+          expected += bytes.bytesize
+        end
+        expected == state[:end]
+      end
+      # @rbs (Packet packet, untyped state, Integer version) -> Packet?
+      def virtual_packet(packet, state, version)
+        payload = state[:parts].map(&:last).join.b
+        header = state[:header].dup
+        if header.bytesize + payload.bytesize > 65_535
+          packet.layers.last.diagnose(:error, :bad_length, 'reassembled IP datagram exceeds 65535 bytes')
+          return nil
+        end
+        if version == 4
+          header[2, 2] = [header.bytesize + payload.bytesize].pack('n')
+          header[6, 2] = [header.unpack1('n', offset: 6) & 0x4000].pack('n')
+          header[10, 2] = "\0\0"
+          header[10, 2] = [Protocols::Checksum.value(header)].pack('n')
+        else
+          header.setbyte(state[:next_offset], state[:next])
+          header[4, 2] = [header.bytesize - 40 + payload.bytesize].pack('n')
+        end
+        result = Packet.new(header + payload, linktype: 101, timestamp_ns: packet.timestamp_ns, number: packet.number,
+                            interface: packet.interface, direction: packet.direction,
+                            meta: packet.meta.merge(reassembled_from: state[:frames].uniq.sort))
+        result.engine = packet.engine
+        result
+      end
+      # @rbs (Integer now_ns) -> void
+      def advance(now_ns)
+        @clock = [@clock, now_ns].max
+        expire(@clock) if @clock >= @next_sweep
+      end
+      # @rbs (Integer now_ns) -> void
+      def expire(now_ns)
+        @next_sweep = now_ns + 1_000_000_000
+        @entries.delete_if do |_key, state|
+          stale = now_ns - state[:time] >= @timeout_ns
+          if stale
+            @expired += 1
+            @bytes -= state_bytesize(state)
+          end
+          stale
+        end
+        @discarded.delete_if do |_key, time|
+          stale = now_ns - time >= @timeout_ns
+          @bytes -= 128 if stale
+          stale
+        end
+      end
+      # @rbs () -> Integer
+      def bytesize = @bytes
+      # @rbs (untyped state) -> Integer
+      def state_bytesize(state)
+        512 + (state[:header]&.bytesize || 0) * 2 + state[:frames].size * 32 + state[:parts].sum { |_pos, bytes| bytes.bytesize * 2 + 168 }
+      end
+      # @rbs (untyped key) -> untyped
+      def remove(key)
+        state = @entries.delete(key)
+        @bytes -= state_bytesize(state) if state
+        state
+      end
+      # @rbs () -> untyped
+      def remove_oldest
+        pair = @entries.shift
+        @bytes -= state_bytesize(pair[1]) if pair
+        pair
+      end
+      # @rbs () -> Integer
+      def finish
+        incomplete = @entries.size
+        @entries.clear
+        @discarded.clear
+        @bytes = 0
+        incomplete
+      end
+      # @rbs () -> Integer
+      def size = @entries.size
+    end
+  end
+end