ctypes 0.2.0

data/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for the
+`ctypes` project.
+
+- [Disclosing a security issue](#disclosing-a-security-issue)
+- [Vulnerability management](#vulnerability-management)
+- [Suggesting changes](#suggesting-changes)
+
+## Disclosing a security issue
+
+The `ctypes` maintainers take all security issues in the project
+seriously. Thank you for improving the security of `ctypes`. We
+appreciate your dedication to responsible disclosure and will make every effort
+to acknowledge your contributions.
+
+`ctypes` leverages GitHub's private vulnerability reporting.
+
+To learn more about this feature and how to submit a vulnerability report,
+review [GitHub's documentation on private reporting](https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).
+
+Here are some helpful details to include in your report:
+
+- a detailed description of the issue
+- the steps required to reproduce the issue
+- versions of the project that may be affected by the issue
+- if known, any mitigations for the issue
+
+A maintainer will acknowledge the report within three (3) business days, and
+will send a more detailed response within an additional three (3) business days
+indicating the next steps in handling your report.
+
+If you've been unable to successfully draft a vulnerability report via GitHub
+or have not received a response during the alloted response window, please
+reach out via the [Cisco Open security contact email](mailto:oss-security@cisco.com).
+
+After the initial reply to your report, the maintainers will endeavor to keep
+you informed of the progress towards a fix and full announcement, and may ask
+for additional information or guidance.
+
+## Vulnerability management
+
+When the maintainers receive a disclosure report, they will assign it to a
+primary handler.
+
+This person will coordinate the fix and release process, which involves the
+following steps:
+
+- confirming the issue
+- determining affected versions of the project
+- auditing code to find any potential similar problems
+- preparing fixes for all releases under maintenance
+
+## Suggesting changes
+
+If you have suggestions on how this process could be improved please submit an
+issue or pull request.

data/ctypes.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/ctypes/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ctypes"
+  spec.version = CTypes::VERSION
+  spec.authors = ["David M. Lary"]
+  spec.email = ["dmlary@gmail.com"]
+
+  spec.summary = "Manipulate common C types in Ruby"
+  # spec.description = "TODO: Write a longer description or delete this line."
+  spec.homepage = "https://github.com/cisco-open/ruby-ctypes"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  # spec.metadata["homepage_uri"] = spec.homepage
+  # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency("dry-struct", "~> 1.0")
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/ctypes/array.rb

@@ -0,0 +1,180 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # @example array of unsigned 32-bit integers
+  #   t = CTypes::Array.new(type: CTypes::Helpers.uint32)
+  #   t.unpack("\xaa\xaa\xaa\xaa\xbb\xbb\xbb\xbb")
+  #                                     # => [0xaaaaaaaa, 0xbbbbbbbb]
+  #   t.pack([0,0xffffffff])            # => "\0\0\0\0\xff\xff\xff\xff"
+  #
+  # @example array of signed 8-bit integers
+  #   t = CTypes::Array.new(type: CTypes::Helpers.int8)
+  #   t.unpack("\x01\x02\x03\x04")      # => [1, 2, 3, 4]
+  #   t.pack([1, 2, 3, 4])              # => "\x01\x02\x03\x04"
+  #
+  # @example fixed-size array of 8-bit integers
+  #   t = CTypes::Array.new(type: CTypes::Helpers.int8, size: 2)
+  #   t.unpack("\x01\x02\x03\x04")      # => [1, 2]
+  #   t.pack([1, 2])                    # => "\x01\x02"
+  #
+  # @example terminated array of 8-bit integers
+  #   t = CTypes::Array.new(type: CTypes::Helpers.int8, terminator: -1)
+  #   t.unpack("\x01\xff\x03\x04")      # => [1]
+  #   t.pack([1])                       # => "\x01\xff"
+  #
+  # @example array of structures
+  #   include CTypes::Helpers
+  #   s = struct do
+  #     attribute :type, uint8
+  #     attribute :value, uint8
+  #   end
+  #   t = array(s)
+  #   t.unpack("\x01\x02\x03\x04")      # => [ { .type = 1, value = 2 },
+  #                                     #      { .type = 3, value = 4 } ]
+  #   t.pack([{type: 1, value: 2}, {type: 3, value: 4}])
+  #                                     # => "\x01\x02\x03\x04"
+  class Array
+    include Type
+
+    # TODO Add support for a pre-unpack terminator that checks against the
+    # remaining buffer before calling unpack on inner type.  This allows easier
+    # support for DWARF-type types (.debug_line file_names)
+
+    # declare a new Array type
+    # @param type [CTypes::Type] type contained within the array
+    # @param size [Integer] number of elements in the array; nil means greedy
+    #   unpack
+    # @param terminator array value that denotes the end of the array; the
+    #   value will not be appended in `unpack` results, but will be appended
+    #   during `pack`
+    def initialize(type:, size: nil, terminator: nil)
+      raise Error, "cannot use terminator with fixed size array" if
+        size && terminator
+      raise Error, "cannot make an Array of variable-length Unions" if
+        type.is_a?(Class) && type < Union && !type.fixed_size?
+
+      @type = type
+      @size = size
+      if terminator
+        @terminator = terminator
+        @term_packed = @type.pack(terminator)
+        @term_unpacked = @type.unpack(@term_packed)
+      end
+
+      @dry_type = Dry::Types["coercible.array"].of(type.dry_type)
+      @dry_type = if size
+        @dry_type.constrained(size:)
+          .default { ::Array.new(size, type.dry_type[]) }
+      else
+        @dry_type.default([].freeze)
+      end
+    end
+    attr_reader :type, :terminator
+
+    # pack a ruby array into a binary string
+    # @param value [::Array] array value to pack
+    # @param endian [Symbol] optional endian override
+    # @param validate [Boolean] set to false to disable value validation
+    # @return [::String] binary string
+    def pack(value, endian: default_endian, validate: true)
+      value = @dry_type[value] if validate
+      out = value.inject(::String.new) do |o, v|
+        o << @type.pack(v, endian: @type.endian || endian)
+      end
+      out << @term_packed if @term_packed
+      out
+    rescue Dry::Types::ConstraintError
+      raise unless @size && @size > value.size
+
+      # value is short some elements; fill them in and retry
+      value += ::Array.new(@size - value.size, @type.default_value)
+      retry
+    end
+
+    # unpack an instance of an array from the beginning of the supplied binary
+    # string
+    # @param buf [::String] binary string
+    # @param endian [Symbol] optional endian override
+    # @return [Array(Object, ::String)] unpacked Array, unused bytes fron buf
+    def unpack_one(buf, endian: default_endian)
+      rest = buf
+      if @size
+        value = @size.times.map do |i|
+          o, rest = @type.unpack_one(rest, endian: @type.endian || endian)
+          o or raise missing_bytes_error(input: value,
+            need: @size * @type.size)
+        end
+      else
+        # handle variable-length array; both greedy and terminated
+        value = []
+        loop do
+          if rest.empty?
+            if @term_packed
+              raise TerminatorNotFoundError,
+                "terminator not found in: %p" % buf
+            end
+            break
+          end
+
+          v, rest = @type.unpack_one(rest, endian: @type.endian || endian)
+          break if v === @term_unpacked
+          value << v
+        end
+      end
+      [value, rest]
+    end
+
+    # check if this Array is greedy
+    def greedy?
+      !@size && !@terminator
+    end
+
+    # return the size of the array if one is defined
+    def size
+      s = @size ? @size * @type.size : 0
+      s += @term_packed.size if @term_packed
+      s
+    end
+
+    def pretty_print(q) # :nodoc:
+      q.group(1, "array(", ")") do
+        q.pp(@type)
+        if @size
+          q.comma_breakable
+          q.text(@size.to_s)
+        end
+        if @terminator
+          q.comma_breakable
+          q.text("terminator: #{@terminator}")
+        end
+      end
+    end
+    alias_method :inspect, :pretty_inspect # :nodoc:
+
+    def export_type(q) # :nodoc:
+      q << "array("
+      q << @type
+      q << ", #{@size}" if @size
+      q << ", terminator: #{@terminator}" if @terminator
+      q << ")"
+      q << ".with_endian(%p)" % [@endian] if @endian
+    end
+
+    def type_name
+      @size ?
+        "%s[%s]" % [@type.type_name, @size] :
+        "%s[]" % [@type.type_name]
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Array)
+      other.type == @type &&
+        other.size == size &&
+        other.terminator == terminator
+    end
+  end
+end

data/lib/ctypes/bitfield/builder.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # {Bitfield} layout builder
+  #
+  # This class is used to describe the memory layout of a {Bitfield} type.
+  # There are two approaches provided here for describing the layout, the first
+  # is a constructive interface using {Builder#unsigned}, {Builder#signed},
+  # {Builder#align}, and {Builder#skip}, to build the bitfield from
+  # right-to-left.  These methods track how many bits have been used, and
+  # automatically determine the offset of fields as they're declared.
+  #
+  # The second interface is the programmatic interface that can be used to
+  # generate the {Bitfield} layout from data.  This uses {Builder#field} to
+  # explicitly declare fields using bit size, offset, and signedness.
+  #
+  # @example using the constructive interface via {CTypes::Bitfield#layout}
+  #   class MyBits < CTypes::Bitfield
+  #     layout do
+  #       # the body of this block is evaluated within a Builder instance
+  #       unsigned :bit             # single bit for a at offset 0
+  #       unsigned :two, 2          # two bits for this field at offset 1
+  #       signed :nibble, 4         # four bit nibble as a signed int, offset 3
+  #     end
+  #   end
+  #
+  # @example using the programmatic interface via {CTypes::Bitfield#layout}
+  #   class MyBits < CTypes::Bitfield
+  #     layout do
+  #       # the body of this block is evaluated within a Builder instance
+  #       field :bit, size: 1, offset: 0      # single bit at offset 0
+  #       field :two, size: 2, offset: 1      # two bits at offset 1
+  #       field :nibble, size: 4, offset: 3   # four bits at offset 3
+  #     end
+  #   end
+  #
+  # @example construct {CTypes::Bitfield} programmatically
+  #   b = CTypes::Bitfield.builder        # => #<CTypes::Bitfield::Builder>
+  #   b.field(:one, bits: 1, offset: 0)   # one bit at offset 0, named :one
+  #
+  #   # Create additional fields from data loaded from elsewhere
+  #   extra_fields = [
+  #     [:two, 2, 1],                     # two bits for this field named :two
+  #     [:nibble, 4, 3]                   # four bits for the :nibble field
+  #   ]
+  #   extra_fields.each do |name, bits, offset|
+  #     b.field(name, bits:, offset:)
+  #   end
+  #
+  #   # build the type
+  #   t = b.build                         # => #<Bitfield ...>
+  class Bitfield::Builder
+    include Helpers
+
+    def initialize
+      @fields = []
+      @schema = {}
+      @default = {}
+      @offset = 0
+      @layout = []
+      @max = 0
+    end
+
+    # get the offset of the next unused bit in the bitfield
+    attr_reader :offset
+
+    # build a {Bitfield} instance with the layout configured in this builder
+    # @return [Bitfield] bitfield with the layout defined in this builder
+    def build
+      k = Class.new(Bitfield)
+      k.send(:apply_layout, self)
+      k
+    end
+
+    # get the layout description for internal use in {Bitfield}
+    # @api private
+    def result
+      dry_type = Dry::Types["coercible.hash"]
+        .schema(@schema)
+        .strict
+        .default(@default.freeze)
+
+      type = case @max
+      when 0..8
+        UInt8
+      when 9..16
+        UInt16
+      when 17..32
+        UInt32
+      when 32..64
+        UInt64
+      else
+        raise Error, "bitfields greater than 64 bits not supported"
+      end
+
+      [type, @fields, dry_type, @endian, @layout]
+    end
+
+    # set the endian for this {Bitfield}
+    # @param value [Symbol] `:big` or `:little`
+    def endian(value)
+      @endian = Endian[value]
+      self
+    end
+
+    # skip `bits` bits in the layout of this bitfield
+    # @param bits [Integer] number of bits to skip
+    def skip(bits)
+      raise Error, "cannot mix `#skip` and `#field` in Bitfield layout" unless
+          @offset
+      @offset += bits
+      @max = @offset if @offset > @max
+      @layout << "skip #{bits}"
+      self
+    end
+
+    # set the alignment of the next field declared using {Builder#signed} or
+    # {Builder#unsigned}
+    # @param bits [Integer] bit alignment of the next field
+    # @note {Builder#align} cannot be mixed with calls to {Builder#field}
+    #
+    # @example
+    #   class MyBits < CTypes::Bitfield
+    #     layout do
+    #       unsigned :a       # single bit at offset 0
+    #       align 4
+    #       unsigned :b, 2    # two bits at offset 4
+    #       align 4
+    #       unsigned :c       # single bit at offset 8
+    #     end
+    #   end
+    #
+    def align(bits)
+      raise Error, "cannot mix `#align` and `#field` in Bitfield layout" unless
+          @offset
+      @offset += bits - (@offset % bits)
+      @layout << "align #{bits}"
+      self
+    end
+
+    # append a new unsigned field to the bitfield
+    # @param name [String, Symbol] name of the field
+    # @param bits [Integer] number of bits
+    def unsigned(name, bits = 1)
+      unless @offset
+        raise Error,
+          "cannot mix `#unsigned` and `#field` in Bitfield layout"
+      end
+
+      name = name.to_sym
+      raise Error, "duplicate field: %p" % [name] if
+          @fields.any? { |(n, _)| n == name }
+
+      @layout << ((bits == 1) ?
+          "unsigned %p" % [name] :
+          "unsigned %p, %d" % [name, bits])
+
+      __field_impl(name:, bits:, offset: @offset, signed: false)
+      @offset += bits
+      self
+    end
+
+    # append a new signed field to the bitfield
+    # @param name [String, Symbol] name of the field
+    # @param bits [Integer] number of bits
+    def signed(name, bits = 1)
+      unless @offset
+        raise Error,
+          "cannot mix `#signed` and `#field` in Bitfield layout"
+      end
+
+      name = name.to_sym
+      raise Error, "duplicate field: %p" % [name] if
+          @fields.any? { |(n, _)| n == name }
+
+      @layout << ((bits == 1) ?
+          "signed %p" % [name] :
+          "signed %p, %d" % [name, bits])
+
+      __field_impl(name:, bits:, offset: @offset, signed: true)
+      @offset += bits
+      self
+    end
+
+    # set the size of the {Bitfield} in bytes
+    #
+    # Once the size is set, the Bitfield cannot grow past that size.  Any calls
+    # to {Builder#signed} or {Builder#unsigned} that go beyond the size will
+    # raise errors.
+    #
+    # @param n [Integer] size in bytes
+    def bytes(n)
+      @layout << "bytes #{n}"
+      @max = n * 8
+      self
+    end
+
+    # declare a bit field at a specific offset
+    # @param name [String, Symbol] name of the field
+    # @param offset [Integer] right to left bit offset, where 0 is the least
+    #   significant bit in a byte
+    # @param bits [Integer] number of bits used by this bitfield
+    # @param signed [Boolean] set to true to unpack as a signed integer
+    #
+    # This method is an alternative the construtive interface provided by
+    # {Builder#skip}, {Builder#align},
+    # {Builder#unsigned}, and {Builder#signed}.  This is a programmatic
+    # interface for explicitly declaring fields using offset & bitcount.
+    #
+    # @note This method should not be used in combination with
+    # {Builder#skip}, {Builder#align}, {Builder#unsigned}, {Builder#signed}.
+    def field(name, offset:, bits:, signed: false)
+      name = name.to_sym
+      raise Error, "duplicate field: %p" % [name] if
+          @fields.any? { |(n, _)| n == name }
+
+      @layout << "field %p, offset: %d, bits: %d, signed: %p" %
+        [name, offset, bits, signed]
+      @offset = nil
+
+      __field_impl(name:, offset:, bits:, signed:)
+      self
+    end
+
+    private
+
+    # @api private
+    def __field_impl(name:, offset:, bits:, signed:) # :nodoc:
+      mask = (1 << bits) - 1
+
+      schema = Dry::Types["integer"].default(0)
+      @schema[name] = if signed
+        schema.constrained(gteq: 0 - (1 << (bits - 1)), lt: 1 << (bits - 1))
+      else
+        schema.constrained(gteq: 0, lt: 1 << bits)
+      end
+      @default[name] = 0
+
+      @fields << [name, offset, mask, signed ? bits : nil, :"@#{name}"]
+      @max = offset + bits if offset + bits > @max
+    end
+  end
+end