redhound 1.0.0 → 2.0.0.rc1

data/lib/redhound/field.rb

@@ -0,0 +1,62 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Redhound
+  # Immutable description of a field location, type and display metadata.
+  FieldDefinition = Data.define(:key, :name, :type, :offset, :length, :index, :shift, :mask, :scale, :format, :enum)
+
+  # A decoded field with its definition, raw value and absolute location.
+  class Field
+    # Definition, raw decoded value and capture location.
+    attr_reader :definition, :raw_value, :offset, :length
+
+    # @rbs (untyped definition, untyped value, Integer base) -> void
+    # Bind a field definition to its value and layer base offset.
+    def initialize(definition, value, base)
+      @definition, @raw_value = definition, value
+      @offset, @length = base + definition.offset, definition.length
+    end
+
+    # @rbs () -> String
+    # Stable dotted field name.
+    def name = @definition.name
+    # @rbs () -> Symbol
+    # Declared field representation.
+    def type = @definition.type
+
+    # @rbs () -> untyped
+    # Decoded value; addresses are returned in human-readable text.
+    def value
+      case type
+      when :ipv4 then [@raw_value].pack('N').unpack('C4').join('.')
+      when :ipv6 then IPAddr.new_ntoh(@raw_value).to_s
+      when :mac then @raw_value.unpack('H2' * 6).join(':')
+      else @raw_value
+      end
+    end
+
+    # @rbs () -> untyped
+    # JSON-safe value; opaque bytes and invalid text are encoded in hexadecimal.
+    def json_value
+      return @raw_value.unpack1('H*') if type == :bytes
+      val = value
+      return val unless val.is_a?(String)
+      utf8 = val.dup.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? ? utf8 : val.unpack1('H*')
+    end
+
+    # @rbs () -> String
+    # Terminal-safe field text with escaped control and non-ASCII bytes.
+    def display
+      val = value
+      return val if type == :ipv4 || type == :ipv6 || type == :mac
+      return "#{@definition.enum[val]} (#{val})" if @definition.enum&.key?(val)
+      return format('0x%x', val) if @definition.format == :hex
+      return @raw_value.unpack1('H*') if type == :bytes
+      return val.b.gsub(/[^\x20-\x7e]/n) { |c| format('\\x%02x', c.getbyte(0)) } if val.is_a?(String)
+      val.to_s
+    end
+  end
+end

data/lib/redhound/file/format.rb

@@ -0,0 +1,56 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    module Format
+      MAX_RECORD = 16 * 1024 * 1024
+      PCAP_MAGICS = {
+        "\xd4\xc3\xb2\xa1".b => [:little, 1_000], "\xa1\xb2\xc3\xd4".b => [:big, 1_000],
+        "\x4d\x3c\xb2\xa1".b => [:little, 1], "\xa1\xb2\x3c\x4d".b => [:big, 1]
+      }.freeze
+      PCAPNG_MAGIC = "\x0a\x0d\x0d\x0a".b.freeze
+
+      # @rbs (untyped io, Integer length, ?eof: false) -> String
+      # @rbs (untyped io, Integer length, eof: true) -> String?
+      def self.read_exact(io, length, eof: false)
+        raise FileFormatError, "invalid record length #{length}" unless length.between?(0, MAX_RECORD)
+        return ''.b if length.zero?
+
+        result = ''.b
+        while result.bytesize < length
+          part = io.read(length - result.bytesize)
+          if !part || part.empty?
+            return nil if eof && result.empty?
+
+            raise FileFormatError, "truncated capture file (wanted #{length}, read #{result.bytesize})"
+          end
+          result << part
+        end
+        result
+      end
+
+      # @rbs (Integer length) -> Integer
+      def self.padded(length) = (length + 3) & ~3
+
+      # @rbs (String data) -> String
+      def self.pad(data) = data + "\0" * (padded(data.bytesize) - data.bytesize)
+
+      # NULL carries a host-order address family; libpcap also normalizes it on read.
+      # @rbs (String data, Integer linktype, String integer_format) -> String
+      def self.normalize_null(data, linktype, integer_format)
+        data[0, 4] = [data.unpack1(integer_format)].pack('L') if linktype.zero? && data.bytesize >= 4
+        data
+      end
+
+      # @rbs (Integer caplen, Integer original_length, Integer snaplen) -> void
+      def self.check_lengths(caplen, original_length, snaplen)
+        unless caplen.between?(0, MAX_RECORD) && (snaplen.zero? || caplen <= snaplen) && original_length >= caplen
+          raise FileFormatError, "invalid packet lengths (captured #{caplen}, original #{original_length}, snaplen #{snaplen})"
+        end
+      end
+    end
+  end
+end

data/lib/redhound/file/pcap_reader.rb

@@ -0,0 +1,43 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    class PcapReader
+      attr_reader :interfaces, :linktype
+
+      # @rbs (untyped io, String magic) -> void
+      def initialize(io, magic)
+        @io = io
+        endian, @multiplier = Format::PCAP_MAGICS.fetch(magic) #: [Symbol, Integer]
+        @integer_format = endian == :little ? 'V' : 'N'
+        header = Format.read_exact(io, 20)
+        major, minor, _zone, _accuracy, @snaplen, network = header.unpack(endian == :little ? 'vvV4' : 'nnN4') #: [Integer, Integer, Integer, Integer, Integer, Integer]
+        raise FileFormatError, "unsupported pcap version #{major}.#{minor}" unless major == 2 && minor == 4
+        raise FileFormatError, 'invalid pcap snaplen' unless @snaplen.between?(1, Format::MAX_RECORD)
+
+        @linktype = network & 0xffff
+        @interfaces = [Capture::Interface.new(name: 'pcap', linktype: @linktype, snaplen: @snaplen)]
+        @number = 0
+      end
+
+      # @rbs () -> Packet?
+      def next_packet
+        record = Format.read_exact(@io, 16, eof: true)
+        return nil unless record
+
+        seconds, fraction, caplen, original_length = record.unpack("#{@integer_format}4") #: [Integer, Integer, Integer, Integer]
+        Format.check_lengths(caplen, original_length, @snaplen)
+        raise FileFormatError, 'invalid pcap timestamp fraction' unless fraction < 1_000_000_000 / @multiplier
+
+        data = Format.normalize_null(Format.read_exact(@io, caplen), @linktype, @integer_format)
+        @number += 1
+        timestamp_ns = seconds * 1_000_000_000 + fraction * @multiplier #: Integer
+        Packet.new(data, timestamp_ns:,
+                         original_length:, linktype: @linktype, interface: @interfaces.first, number: @number)
+      end
+    end
+  end
+end

data/lib/redhound/file/pcap_writer.rb

@@ -0,0 +1,72 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    class PcapWriter
+      attr_reader :bytes_written, :path
+
+      # @rbs (untyped output, ?linktype: Integer | Symbol | String, ?snaplen: Integer, ?precision: Symbol, ?packet_buffered: bool, **untyped) -> void
+      def initialize(output, linktype: :ethernet, snaplen: 262_144, precision: :nano, packet_buffered: false, **_options)
+        raise ArgumentError, 'snaplen must be between 1 and 16 MiB' unless snaplen.between?(1, Format::MAX_RECORD)
+        raise ArgumentError, 'precision must be micro or nano' unless %i[micro nano].include?(precision)
+
+        @linktype = Capture::Linktype.resolve(linktype)
+        @snaplen, @precision, @packet_buffered = snaplen, precision, packet_buffered
+        @owned = output.is_a?(String) && output != '-'
+        @path = output.is_a?(String) ? output : nil
+        @io = output.is_a?(String) ? (output == '-' ? $stdout : ::File.open(output, ::File::WRONLY | ::File::CREAT | ::File::TRUNC, 0o600)) : output
+        @io.chmod(0o600) if @owned
+        @io.binmode if @io.respond_to?(:binmode)
+        @bytes_written = 0
+        @closed = false
+        magic = precision == :nano ? 0xa1b23c4d : 0xa1b2c3d4
+        write_bytes([magic, 2, 4, 0, 0, snaplen, @linktype].pack('VvvV4'))
+      end
+
+      # @rbs (Packet packet) -> self
+      def write(packet)
+        raise IOError, 'writer is closed' if @closed
+        raise FileFormatError, 'pcap cannot store multiple link types; use pcapng' unless packet.linktype == @linktype
+
+        seconds, nanos = packet.timestamp_ns.divmod(1_000_000_000)
+        raise FileFormatError, 'pcap timestamp exceeds unsigned 32-bit seconds' unless seconds.between?(0, 0xffff_ffff)
+
+        data = packet.data.byteslice(0, @snaplen)
+        fraction = @precision == :nano ? nanos : nanos / 1_000
+        write_bytes([seconds, fraction, data.bytesize, packet.original_length].pack('V4') + data)
+        @io.flush if @packet_buffered
+        self
+      end
+
+      alias << write
+
+      # @rbs (Packet packet) -> Integer
+      def record_size(packet) = 16 + [packet.caplen, @snaplen].min
+
+      # @rbs (Capture::Stats stats, ?interface: Capture::Interface?) -> void
+      def write_stats(stats, interface: nil); end
+
+      # @rbs () -> void
+      def flush = @io.flush
+
+      # @rbs () -> void
+      def close
+        return if @closed
+
+        @io.flush
+        @io.close if @owned
+        @closed = true
+      end
+
+      private
+
+      # @rbs (String bytes) -> void
+      def write_bytes(bytes)
+        @bytes_written += @io.write(bytes)
+      end
+    end
+  end
+end

data/lib/redhound/file/pcapng_reader.rb

@@ -0,0 +1,209 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    class PcapngReader
+      attr_reader :interfaces, :stats
+
+      # @rbs (untyped io, String magic) -> void
+      def initialize(io, magic)
+        @io = io
+        @interfaces = [] #: Array[Capture::Interface]
+        @section_interfaces = [] #: Array[Capture::Interface]
+        @statistics = {} #: Hash[Integer, Hash[Symbol, Integer]]
+        @packet_counts = {} #: Hash[Integer, Integer]
+        @stats = Capture::Stats.new
+        @number = 0
+        @magic = magic
+        @integer_format = 'V'
+        read_block
+        while (block = read_block)
+          type, body = block
+          if type == 1
+            read_interface(body)
+            break
+          end
+          raise FileFormatError, 'pcapng packet precedes interface description' if [3, 5, 6].include?(type)
+        end
+      end
+
+      # @rbs () -> Integer
+      def linktype = @interfaces.first&.linktype || 1
+
+      # @rbs () -> bool
+      def statistics? = !@statistics.empty?
+
+      # @rbs () -> Packet?
+      def next_packet
+        while (block = read_block)
+          type, body = block
+          case type
+          when 1 then read_interface(body)
+          when 6 then return read_enhanced(body)
+          when 3 then return read_simple(body)
+          when 5 then read_statistics(body)
+          end
+        end
+        nil
+      end
+
+      private
+
+      # @rbs () -> [Integer, String]?
+      def read_block
+        header = @magic ? @magic + Format.read_exact(@io, 4) : Format.read_exact(@io, 8, eof: true)
+        @magic = nil
+        return nil unless header
+
+        section = header.byteslice(0, 4) == Format::PCAPNG_MAGIC
+        prefix = section ? Format.read_exact(@io, 4) : ''.b
+        if section
+          @integer_format = case prefix
+                            when "\x4d\x3c\x2b\x1a".b then 'V'
+                            when "\x1a\x2b\x3c\x4d".b then 'N'
+                            else raise FileFormatError, 'invalid pcapng byte order magic'
+                            end
+        end
+        type, length = header.unpack("#{@integer_format}2") #: [Integer, Integer]
+        minimum = section ? 28 : 12
+        unless length.between?(minimum, Format::MAX_RECORD) && (length & 3).zero?
+          raise FileFormatError, "invalid pcapng block length #{length}"
+        end
+        contents = prefix + Format.read_exact(@io, length - 8 - prefix.bytesize)
+        raise FileFormatError, 'pcapng block lengths do not match' unless contents.unpack1(@integer_format, offset: contents.bytesize - 4) == length
+
+        body = contents.byteslice(0, contents.bytesize - 4) #: String
+        if section
+          version = body.unpack(@integer_format == 'V' ? 'vv' : 'nn', offset: 4)
+          raise FileFormatError, 'unsupported pcapng section version' unless version == [1, 0]
+
+          @section_interfaces = [] #: Array[Capture::Interface]
+        end
+        [type, body]
+      end
+
+      # @rbs (String body) -> void
+      def read_interface(body)
+        require_size(body, 8)
+        linktype, _reserved, snaplen = body.unpack(@integer_format == 'V' ? 'vvV' : 'nnN') #: [Integer, Integer, Integer]
+        raise FileFormatError, 'invalid pcapng snaplen' if snaplen > Format::MAX_RECORD
+
+        opts = options(body, 8)
+        resolution = opts.fetch(9, ["\x06".b]).fetch(0)
+        raise FileFormatError, 'invalid pcapng timestamp resolution' unless resolution.bytesize == 1
+
+        exponent = resolution.getbyte(0) #: Integer
+        units = exponent < 128 ? 10**exponent : 2**(exponent & 127)
+        offset = opts.fetch(14, ["\0" * 8]).fetch(0)
+        raise FileFormatError, 'invalid pcapng timestamp offset' unless offset.bytesize == 8
+
+        index = @section_interfaces.size
+        filter_option = opts[11]&.first
+        interface = Capture::Interface.new(name: opts.fetch(2, ["interface#{index}"]).fetch(0), index:, linktype:, snaplen:,
+                                           description: opts[3]&.first, filter: filter_option && filter_option.getbyte(0) == 0 ? filter_option.byteslice(1..) : nil,
+                                           meta: { timestamp_units: units, timestamp_offset: offset.unpack1(@integer_format == 'V' ? 'q<' : 'q>') })
+        @section_interfaces << interface
+        @interfaces << interface
+      end
+
+      # @rbs (String body) -> Packet
+      def read_enhanced(body)
+        require_size(body, 20)
+        index, high, low, caplen, original_length = body.unpack("#{@integer_format}5") #: [Integer, Integer, Integer, Integer, Integer]
+        interface = interface_at(index)
+        Format.check_lengths(caplen, original_length, interface.snaplen)
+        require_size(body, 20 + Format.padded(caplen))
+        opts = options(body, 20 + Format.padded(caplen))
+        flags_option = opts[2]&.first
+        raise FileFormatError, 'invalid pcapng packet flags' if flags_option && flags_option.bytesize != 4
+
+        flags = flags_option ? flags_option.unpack1(@integer_format) : 0 #: Integer
+        direction = { 1 => :in, 2 => :out }[flags & 3]
+        meta = { epb_flags: flags } #: Hash[Symbol, untyped]
+        meta[:comment] = opts[1].join("\n") if opts[1]
+        pkttype = direction == :out ? 4 : { 1 => 0, 2 => 2, 3 => 1, 4 => 3 }[(flags >> 2) & 7]
+        meta[:pkttype] = pkttype if pkttype
+        timestamp_ns = ((high << 32) | low) * 1_000_000_000 / interface.meta.fetch(:timestamp_units) +
+                       interface.meta.fetch(:timestamp_offset) * 1_000_000_000
+        data = body.byteslice(20, caplen) #: String
+        make_packet(data, interface, original_length, timestamp_ns, direction, meta)
+      end
+
+      # @rbs (String body) -> Packet
+      def read_simple(body)
+        require_size(body, 4)
+        interface = interface_at(0)
+        original_length = body.unpack1(@integer_format) #: Integer
+        caplen = interface.snaplen.zero? ? original_length : [original_length, interface.snaplen].min
+        Format.check_lengths(caplen, original_length, interface.snaplen)
+        raise FileFormatError, 'invalid pcapng simple packet length' unless body.bytesize == 4 + Format.padded(caplen)
+
+        data = body.byteslice(4, caplen) #: String
+        make_packet(data, interface, original_length, 0, nil, {})
+      end
+
+      # @rbs (String body) -> void
+      def read_statistics(body)
+        require_size(body, 12)
+        index = body.unpack1(@integer_format) #: Integer
+        interface = interface_at(index)
+        opts = options(body, 12)
+        values = {} #: Hash[Symbol, Integer]
+        { received: 4, dropped: 5, if_dropped: 7, captured: 8 }.each do |name, code|
+          option = opts[code]&.first
+          next unless option
+          raise FileFormatError, 'invalid pcapng statistics counter' unless option.bytesize == 8
+
+          count = option.unpack1(@integer_format == 'V' ? 'Q<' : 'Q>') #: Integer
+          values[name] = count
+        end
+        @statistics[interface.object_id] = values
+        totals = %i[received dropped if_dropped captured].to_h { |name| [name, @statistics.values.sum { |entry| entry.fetch(name, 0) }] }
+        %i[received captured].each do |name|
+          totals[name] = @packet_counts.values.sum unless @statistics.values.any? { |entry| entry.key?(name) }
+        end
+        @stats = Capture::Stats.new(**totals)
+      end
+
+      # @rbs (String data, Capture::Interface interface, Integer original_length, Integer timestamp_ns, Symbol? direction, Hash[Symbol, untyped] meta) -> Packet
+      def make_packet(data, interface, original_length, timestamp_ns, direction, meta)
+        data = Format.normalize_null(data, interface.linktype, @integer_format)
+        @number += 1
+        @packet_counts[interface.object_id] = @packet_counts.fetch(interface.object_id, 0) + 1
+        Packet.new(data, timestamp_ns:, original_length:, linktype: interface.linktype, interface:, direction:, number: @number, meta:)
+      end
+
+      # @rbs (Integer index) -> Capture::Interface
+      def interface_at(index)
+        @section_interfaces.fetch(index) { raise FileFormatError, "pcapng references unknown interface #{index}" }
+      end
+
+      # @rbs (String body, Integer offset) -> Hash[Integer, Array[String]]
+      def options(body, offset)
+        result = {} #: Hash[Integer, Array[String]]
+        while offset < body.bytesize
+          require_size(body, offset + 4)
+          code, length = body.unpack(@integer_format == 'V' ? 'vv' : 'nn', offset:) #: [Integer, Integer]
+          offset += 4
+          if code.zero?
+            raise FileFormatError, 'invalid pcapng end of options' unless length.zero?
+            break
+          end
+          require_size(body, offset + Format.padded(length))
+          value = body.byteslice(offset, length) #: String
+          (result[code] ||= []) << value
+          offset += Format.padded(length)
+        end
+        result
+      end
+
+      # @rbs (String body, Integer size) -> void
+      def require_size(body, size)
+        raise FileFormatError, 'truncated pcapng block' if body.bytesize < size
+      end
+    end
+  end
+end

data/lib/redhound/file/pcapng_writer.rb

@@ -0,0 +1,143 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    class PcapngWriter
+      attr_reader :bytes_written, :path
+
+      # @rbs (untyped output, ?linktype: Integer | Symbol | String, ?snaplen: Integer, ?precision: Symbol, ?packet_buffered: bool, ?filter: String?, ?comment: String?, **untyped) -> void
+      def initialize(output, linktype: :ethernet, snaplen: 262_144, precision: :nano, packet_buffered: false,
+                     filter: nil, comment: nil, **_options)
+        raise ArgumentError, 'snaplen must be between 1 and 16 MiB' unless snaplen.between?(1, Format::MAX_RECORD)
+
+        @linktype, @snaplen, @packet_buffered = Capture::Linktype.resolve(linktype), snaplen, packet_buffered
+        @filter, @comment = filter, comment
+        @owned = output.is_a?(String) && output != '-'
+        @path = output.is_a?(String) ? output : nil
+        @io = output.is_a?(String) ? (output == '-' ? $stdout : ::File.open(output, ::File::WRONLY | ::File::CREAT | ::File::TRUNC, 0o600)) : output
+        @io.chmod(0o600) if @owned
+        @io.binmode if @io.respond_to?(:binmode)
+        @bytes_written = 0
+        @interfaces, @counts, @start_times, @end_times, @statistics = {}, {}, {}, {}, {}
+        @closed = false
+        opts = { 3 => RUBY_PLATFORM, 4 => "Redhound #{VERSION}" }
+        opts[1] = comment if comment
+        write_block(0x0a0d0d0a, [0x1a2b3c4d, 1, 0, 0xffff_ffff_ffff_ffff].pack('VvvQ<') + options(opts))
+      end
+
+      # @rbs (Packet packet) -> self
+      def write(packet)
+        raise IOError, 'writer is closed' if @closed
+        raise FileFormatError, 'pcapng timestamp must be nonnegative' if packet.timestamp_ns.negative?
+
+        index = ensure_interface(packet)
+        data = packet.data.byteslice(0, @snaplen)
+        flags = packet_flags(packet)
+        opts = { 2 => [flags].pack('V') }
+        opts[1] = packet.meta[:comment].to_s if packet.meta[:comment]
+        high, low = packet.timestamp_ns >> 32, packet.timestamp_ns & 0xffff_ffff
+        raise FileFormatError, 'pcapng timestamp exceeds unsigned 64-bit range' if high > 0xffff_ffff
+
+        body = [index, high, low, data.bytesize, packet.original_length].pack('V5') + Format.pad(data) + options(opts)
+        write_block(6, body)
+        @counts[index] = @counts.fetch(index, 0) + 1
+        @start_times[index] ||= packet.timestamp_ns
+        @end_times[index] = packet.timestamp_ns
+        @io.flush if @packet_buffered
+        self
+      end
+
+      alias << write
+
+      # @rbs (Packet packet) -> Integer
+      def record_size(packet)
+        44 + Format.padded([packet.caplen, @snaplen].min) + (packet.meta[:comment] ? 4 + Format.padded(packet.meta[:comment].to_s.bytesize) : 0)
+      end
+
+      # @rbs (Capture::Stats stats, ?interface: Capture::Interface?) -> void
+      def write_stats(stats, interface: nil)
+        if interface
+          @interfaces.each { |key, index| @statistics[index] = stats if key[0] == interface.object_id }
+        elsif @interfaces.size == 1
+          @statistics[0] = stats
+        elsif @interfaces.size > 1
+          # Source statistics describe the entire capture; record them once to avoid double counting.
+          @statistics[0] = stats
+        end
+      end
+
+      # @rbs () -> void
+      def flush = @io.flush
+
+      # @rbs () -> void
+      def close
+        return if @closed
+
+        @interfaces.each_value do |index|
+          stats = @statistics[index]
+          start_time, end_time = @start_times.fetch(index, 0), @end_times.fetch(index, 0)
+          opts = { 2 => timestamp_words(start_time), 3 => timestamp_words(end_time),
+                   8 => [@counts.fetch(index, 0)].pack('Q<') }
+          if stats
+            opts[4], opts[5], opts[7] = [stats.received].pack('Q<'), [stats.dropped].pack('Q<'), [stats.if_dropped].pack('Q<')
+            opts[6] = [stats.captured].pack('Q<')
+          end
+          write_block(5, [index].pack('V') + timestamp_words(end_time) + options(opts))
+        end
+        @io.flush
+        @io.close if @owned
+        @closed = true
+      end
+
+      private
+
+      # @rbs (Packet packet) -> Integer
+      def ensure_interface(packet)
+        interface = packet.interface
+        key = [interface&.object_id || 0, packet.linktype]
+        return @interfaces[key] if @interfaces.key?(key)
+
+        index = @interfaces.size
+        @interfaces[key] = index
+        opts = { 2 => interface&.name || "interface#{index}", 9 => "\x09".b, 12 => RUBY_PLATFORM }
+        opts[3] = interface.description if interface&.description
+        expression = interface&.filter || @filter
+        opts[11] = "\0" + expression if expression
+        write_block(1, [packet.linktype, 0, @snaplen].pack('vvV') + options(opts))
+        index
+      end
+
+      # @rbs (Packet packet) -> Integer
+      def packet_flags(packet)
+        direction = { in: 1, out: 2 }.fetch(packet.direction, 0)
+        pkttype = packet.meta[:pkttype]
+        direction = pkttype == 4 ? 2 : 1 if direction.zero? && pkttype
+        reception = { 0 => 1, 1 => 3, 2 => 2, 3 => 4 }.fetch(pkttype, 0)
+        direction | (reception << 2)
+      end
+
+      # @rbs (Integer timestamp) -> String
+      def timestamp_words(timestamp) = [timestamp >> 32, timestamp & 0xffff_ffff].pack('V2')
+
+      # @rbs (Hash[Integer, String] values) -> String
+      def options(values)
+        values.map do |code, value|
+          raise FileFormatError, 'pcapng option exceeds 65535 bytes' if value.bytesize > 65_535
+
+          [code, value.bytesize].pack('vv') + Format.pad(value.b)
+        end.join.b + "\0" * 4
+      end
+
+      # @rbs (Integer type, String body) -> void
+      def write_block(type, body)
+        length = body.bytesize + 12
+        raise FileFormatError, 'pcapng block exceeds 16 MiB' if length > Format::MAX_RECORD
+
+        @bytes_written += @io.write([type, length].pack('V2') + body + [length].pack('V'))
+      end
+    end
+  end
+end

data/lib/redhound/file/rotating_writer.rb

@@ -0,0 +1,98 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Redhound
+  # @api private
+  module File
+    # @api private
+    class RotatingWriter
+      attr_reader :path
+
+      # @rbs (String path, ?max_bytes: Integer?, ?interval: Numeric?, ?file_count: Integer?, ?post_rotate_command: String?, **untyped options) -> void
+      def initialize(path, max_bytes: nil, interval: nil, file_count: nil, post_rotate_command: nil, **options)
+        raise ArgumentError, 'cannot rotate standard output' if path == '-'
+        raise ArgumentError, 'max_bytes must be positive' if max_bytes && max_bytes <= 0
+        raise ArgumentError, 'interval must be positive' if interval && interval <= 0
+        raise ArgumentError, 'file_count must be positive' if file_count && file_count <= 0
+
+        @base, @max_bytes, @interval, @file_count = path, max_bytes, interval, file_count
+        @post_rotate_command, @options = post_rotate_command && Shellwords.split(post_rotate_command), options
+        raise ArgumentError, 'post-rotate command must not be empty' if @post_rotate_command&.empty?
+        @sequence, @packet_count, @closed = 0, 0, false
+        open_next
+      end
+
+      # @rbs (Packet packet) -> self
+      def write(packet)
+        raise IOError, 'writer is closed' if @closed
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @opened_at
+        size_due = @max_bytes && @writer.bytes_written >= @max_bytes
+        time_due = @interval && elapsed >= @interval
+        rotate if @packet_count.positive? && (size_due || time_due)
+        @writer.write(packet)
+        @packet_count += 1
+        self
+      end
+
+      alias << write
+
+      # @rbs (Capture::Stats stats, ?interface: Capture::Interface?) -> void
+      def write_stats(stats, interface: nil) = @writer.write_stats(stats, interface:)
+
+      # @rbs () -> Integer
+      def bytes_written = @writer.bytes_written
+
+      # @rbs () -> void
+      def flush = @writer.flush
+
+      # @rbs () -> void
+      def close
+        return if @closed
+
+        @writer.close
+        run_command
+        @closed = true
+      end
+
+      private
+
+      # @rbs () -> void
+      def rotate
+        @writer.close
+        run_command
+        @closed = true
+        @sequence += 1
+        if @interval && !@max_bytes && @file_count && @sequence >= @file_count
+          @closed = true
+          raise RotationComplete, 'rotation file count reached'
+        end
+        open_next
+      end
+
+      # @rbs () -> void
+      def open_next
+        sequence = @max_bytes && @file_count ? @sequence % @file_count : @sequence
+        base = @interval ? Time.now.strftime(@base) : @base
+        extension = ::File.extname(base)
+        stem = extension.empty? ? base : base.delete_suffix(extension)
+        @path = "#{stem}_#{format('%05d', sequence)}#{extension}"
+        @writer = Writer.open(@path, **@options)
+        @opened_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @packet_count = 0
+        @closed = false
+      end
+
+      # @rbs () -> void
+      def run_command
+        return unless @post_rotate_command
+
+        pid = Process.spawn(*@post_rotate_command, @path)
+        _, status = Process.wait2(pid)
+        raise CaptureError, "post-rotate command failed: #{status.exitstatus}" unless status.success?
+      end
+    end
+  end
+end