ciborium 0.1.0

data/lib/ciborium/extensions.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  # Tag handling beyond Tagged, enabled per call through the extensions: option.
+  #
+  # An extension is any object that responds to:
+  #
+  # - tags: the tag numbers it decodes
+  # - classes: the classes whose instances it encodes
+  # - decode(tag, value): the object for a tag's decoded content
+  # - encode(object): an object to encode in place of object, typically a Tagged
+  #
+  # Symbols name the built-in extensions.
+  module Extensions
+    BUILTIN = {
+      bignum: "BigInteger",
+      time: "Time",
+      uri: "URI",
+      regexp: "Regexp",
+    }.freeze #: Hash[Symbol, String]
+
+    # Resolves Symbols to the built-in extensions and checks every entry is an extension.
+    #
+    #: (untyped extensions) -> Array[_Extension]
+    def self.resolve(extensions)
+      unless extensions.is_a?(Array)
+        raise ArgumentError, "extensions must be an Array, got #{extensions.inspect}"
+      end
+
+      extensions.map do |extension|
+        next builtin(extension) if extension.is_a?(Symbol)
+
+        unless [:tags, :classes, :decode, :encode].all? { |m| extension.respond_to?(m) }
+          raise ArgumentError, "#{extension.inspect} does not implement tags, classes, decode and encode"
+        end
+
+        extension
+      end
+    end
+
+    # Maps each tag to a callable that wraps the extension's failures in ExtensionError.
+    #
+    #: (Array[_Extension] extensions) -> Hash[Integer, ^(Integer, untyped) -> untyped]?
+    def self.tag_handlers(extensions)
+      return if extensions.empty?
+
+      handlers = {} #: Hash[Integer, ^(Integer, untyped) -> untyped]
+      extensions.each do |extension|
+        extension.tags.each do |tag|
+          raise ArgumentError, "more than one extension decodes tag #{tag}" if handlers.key?(tag)
+
+          handlers[tag] = ->(t, value) do
+            extension.decode(t, value)
+          rescue StandardError
+            raise ExtensionError, "#{extension.inspect} failed to decode tag #{t}"
+          end
+        end
+      end
+      handlers.freeze
+    end
+
+    # Pairs each class with a callable that wraps the extension's failures in EncodeError.
+    #
+    #: (Array[_Extension] extensions) -> Array[[Module, ^(untyped) -> untyped]]?
+    def self.class_handlers(extensions)
+      return if extensions.empty?
+
+      extensions.flat_map do |extension|
+        handler = ->(object) do
+          extension.encode(object)
+        rescue StandardError
+          raise EncodeError, "#{extension.inspect} failed to encode an instance of #{object.class}"
+        end
+        extension.classes.map do |klass|
+          raise ArgumentError, "#{extension.inspect} lists #{klass.inspect}, which is not a Module" unless klass.is_a?(Module)
+
+          [klass, handler] #: [Module, ^(untyped) -> untyped]
+        end
+      end.freeze
+    end
+
+    #: (Symbol name) -> _Extension
+    private_class_method def self.builtin(name)
+      class_name = BUILTIN.fetch(name) do
+        raise ArgumentError, "unknown extension #{name.inspect}; built-in ones are #{BUILTIN.keys.inspect}"
+      end
+      require_relative "extensions/#{name}"
+      const_get(class_name).new
+    end
+  end
+end

data/lib/ciborium/native.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "rbconfig"
+
+# Precompiled gems carry one extension per Ruby minor under lib/ciborium/<X.Y>/.
+fat = File.expand_path("#{RUBY_VERSION[/\A\d+\.\d+/]}/ciborium_native", __dir__.to_s)
+if File.exist?("#{fat}.#{RbConfig::CONFIG.fetch("DLEXT")}")
+  require fat
+else
+  require_relative "ciborium_native"
+end
+
+module Ciborium
+  module Native
+    # Called by the encoder for text in an encoding other than UTF-8 or US-ASCII.
+    #
+    #: (String string) -> String
+    def self.transcode(string)
+      string.encode(Encoding::UTF_8)
+    rescue EncodingError
+      raise EncodeError, "cannot transcode a #{string.encoding} string to UTF-8"
+    end
+  end
+end

data/lib/ciborium/replace.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Installs Ciborium::Compat as CBOR, the constant of the cbor gem, in the manner of resolv-replace.
+# Require it before anything requires "cbor": with Bundler, after bundler/setup and before
+# Bundler.require.
+
+require_relative "compat"
+
+module Ciborium
+  module Compat
+    # Classes the cbor gem gives to_cbor. URI::Generic is included when URI is loaded.
+    CORE_EXT_CLASSES = [
+      NilClass,
+      TrueClass,
+      FalseClass,
+      Integer,
+      Float,
+      String,
+      Array,
+      Hash,
+      Symbol,
+      Time,
+      Regexp,
+      Ciborium::Tagged,
+      Ciborium::Simple,
+    ].freeze #: Array[Module]
+
+    # Constants of the cbor gem that CBOR carries.
+    CBOR_CONSTANTS = [
+      :Packer, :Unpacker, :Buffer, :Tagged, :Simple, :UnpackError, :MalformedFormatError, :StackError, :TypeError,
+    ].freeze #: Array[Symbol]
+
+    # Module functions of the cbor gem that CBOR carries.
+    CBOR_FUNCTIONS = [:encode, :pack, :dump, :decode, :unpack, :load].freeze #: Array[Symbol]
+
+    # @rbs self.@facade: Module?
+
+    # The frozen module installed as CBOR. It delegates to Compat rather than being Compat, so the
+    # cbor gem's extension, should it load anyway, fails on reopening it instead of replacing
+    # Compat's methods with its own.
+    #
+    #: () -> Module
+    def self.facade
+      @facade ||= begin
+        compat = self
+        facade = Module.new
+        CBOR_CONSTANTS.each { |name| facade.const_set(name, const_get(name)) }
+        CBOR_FUNCTIONS.each do |name|
+          facade.define_singleton_method(name) { |*args| compat.public_send(name, *args) }
+        end
+        [Packer, Unpacker, Buffer].each(&:freeze)
+        facade.freeze
+      end
+    end
+
+    # Marks every file of the installed cbor gems that require "cbor" could load as loaded.
+    #
+    #: () -> void
+    def self.block_cbor_gem
+      $LOADED_FEATURES.concat(cbor_gem_features - $LOADED_FEATURES)
+    end
+
+    # The cbor gem's entry point and extension: as found on the load path, and in every
+    # installed version, since RubyGems may activate any of them later.
+    #
+    #: () -> Array[String]
+    def self.cbor_gem_features
+      paths = ["cbor", "cbor/cbor"].filter_map do |feature|
+        _type, path = $LOAD_PATH.resolve_feature_path(feature)
+        path
+      rescue LoadError
+        nil
+      end
+      if defined?(Gem::Specification)
+        Gem::Specification.find_all_by_name("cbor").each do |spec|
+          spec.full_require_paths.each do |dir|
+            paths.concat(Dir[File.join(dir, "cbor.rb"), File.join(dir, "cbor", "{,*/}cbor.{so,bundle}")])
+          end
+        end
+      end
+      paths.uniq
+    end
+
+    #: () -> void
+    def self.install
+      block_cbor_gem
+      if Object.const_defined?(:CBOR, false) && !Object.const_get(:CBOR, false).equal?(facade)
+        warn(
+          "ciborium/replace: CBOR was already defined, likely by the cbor gem, and is now replaced. " \
+            "Require ciborium/replace before Bundler.require so the cbor gem is never loaded.",
+        )
+        Object.send(:remove_const, :CBOR)
+      end
+      Object.const_set(:CBOR, facade) unless Object.const_defined?(:CBOR, false)
+
+      classes = CORE_EXT_CLASSES.dup
+      classes << ::URI::Generic if defined?(::URI::Generic)
+      # prepend rather than include, so these replace to_cbor the cbor gem defined on the class.
+      classes.each { |klass| klass.prepend(CoreExt) }
+    end
+  end
+end
+
+Ciborium::Compat.install

data/lib/ciborium/simple.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# rbs_inline: disabled
+
+module Ciborium
+  # A simple value (RFC 8949 section 3.3) other than false, true and null.
+  Simple = Data.define(:value)
+
+  class Simple
+    def initialize(value:)
+      raise ::TypeError, "simple value must be an Integer, got #{value.inspect}" unless value.is_a?(Integer)
+      # 24 to 31 are reserved, so no well-formed encoding exists for them.
+      unless value.between?(0, 23) || value.between?(32, 255)
+        raise ::RangeError, "simple value must be in 0..23 or 32..255, got #{value}"
+      end
+
+      super
+    end
+  end
+
+  UNDEFINED = Simple.new(23)
+end

data/lib/ciborium/tagged.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# rbs_inline: disabled
+
+module Ciborium
+  # A tagged data item (RFC 8949 section 3.4) that no allowlisted extension interprets.
+  Tagged = Data.define(:tag, :value)
+
+  class Tagged
+    MAX_TAG = 2**64 - 1
+
+    def initialize(tag:, value:)
+      raise ::TypeError, "tag must be an Integer, got #{tag.inspect}" unless tag.is_a?(Integer)
+      raise ::RangeError, "tag must be between 0 and 2**64-1, got #{tag}" unless tag.between?(0, MAX_TAG)
+
+      super
+    end
+  end
+end

data/lib/ciborium/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  VERSION = "0.1.0" #: String
+end

data/lib/ciborium.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "ciborium/version"
+require_relative "ciborium/errors"
+require_relative "ciborium/tagged"
+require_relative "ciborium/simple"
+require_relative "ciborium/encoded"
+require_relative "ciborium/native"
+require_relative "ciborium/extensions"
+require_relative "ciborium/decode_options"
+require_relative "ciborium/encode_options"
+require_relative "ciborium/encoder"
+require_relative "ciborium/decoder"
+
+# A CBOR (RFC 8949) encoder and decoder. Tags carry no meaning unless an extension for them is
+# allowlisted.
+module Ciborium
+  # Encodes object into a binary String.
+  #
+  # Options are those of EncodeOptions.build.
+  #
+  #: (untyped object, **untyped options) -> String
+  def self.encode(object, **options)
+    opts = EncodeOptions.build(**options)
+    Native.encode(object, opts.max_depth, opts.flags, opts.fallback, opts.class_handlers)
+  end
+
+  # Decodes a single data item. Raises MalformedError when bytes follow it.
+  #
+  # Options are those of DecodeOptions.build.
+  #
+  #: (String bytes, **untyped options) -> untyped
+  def self.decode(bytes, **options)
+    value, pos = decode_prefix(bytes, **options)
+    unless pos == bytes.bytesize
+      raise MalformedError, "#{bytes.bytesize - pos} bytes follow the decoded item"
+    end
+
+    value
+  end
+
+  # Decodes the data item at the start of bytes and returns it with the number of bytes it took,
+  # leaving whatever follows unread.
+  #
+  #: (String bytes, **untyped options) -> [untyped, Integer]
+  def self.decode_prefix(bytes, **options)
+    opts = DecodeOptions.build(**options)
+    Native.decode(bytes, 0, opts.max_depth, opts.flags, opts.handlers)
+  end
+
+  # Decodes a CBOR sequence (RFC 8742), a concatenation of zero or more data items.
+  #
+  #: (String bytes, **untyped options) -> Array[untyped]
+  def self.decode_sequence(bytes, **options)
+    opts = DecodeOptions.build(**options)
+    items = [] #: Array[untyped]
+    pos = 0
+    while pos < bytes.bytesize
+      item, pos = Native.decode(bytes, pos, opts.max_depth, opts.flags, opts.handlers)
+      items << item
+    end
+    items
+  end
+end

data/sig/generated/ciborium/compat/buffer.rbs

@@ -0,0 +1,95 @@
+# Generated from lib/ciborium/compat/buffer.rb with RBS::Inline
+
+module Ciborium
+  module Compat
+    # A byte queue in front of an optional IO, as CBOR::Buffer of the cbor gem: reads refill from
+    # the IO when the queue runs dry, and writes go out to it once the queue fills.
+    class Buffer
+      DEFAULT_IO_BUFFER_SIZE: Integer
+
+      @pos: Integer
+
+      @data: String
+
+      @io_buffer_size: Integer
+
+      @io: untyped
+
+      attr_reader io: untyped
+
+      # The cbor gem's read_reference_threshold and write_reference_threshold tune its chunk
+      # sharing, which this buffer does not do, so they are accepted and ignored.
+      #
+      # : (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+      def initialize: (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+
+      # : () -> nil
+      def clear: () -> nil
+
+      # : () -> Integer
+      def size: () -> Integer
+
+      # : () -> bool
+      def empty?: () -> bool
+
+      # : (String data) -> Integer
+      def write: (String data) -> Integer
+
+      # : (String data) -> self
+      def <<: (String data) -> self
+
+      # Consumes up to n bytes, or everything without n, refilling from the IO until it ends.
+      # Returns nil when n is positive and nothing is left.
+      #
+      # : (?Integer? n, ?String? out) -> String?
+      def read: (?Integer? n, ?String? out) -> String?
+
+      # Consumes exactly n bytes, or everything without n. Raises EOFError, consuming nothing,
+      # when fewer than n bytes are left.
+      #
+      # : (?Integer? n, ?String? out) -> String
+      def read_all: (?Integer? n, ?String? out) -> String
+
+      # Consumes up to n bytes and returns how many it consumed.
+      #
+      # : (Integer n) -> Integer
+      def skip: (Integer n) -> Integer
+
+      # Consumes exactly n bytes, or raises EOFError consuming nothing.
+      #
+      # : (Integer n) -> self
+      def skip_all: (Integer n) -> self
+
+      # : () -> String
+      def to_str: () -> String
+
+      # : () -> Array[String]
+      def to_a: () -> Array[String]
+
+      # Writes the queued bytes to the IO, if there is one.
+      #
+      # : () -> self
+      def flush: () -> self
+
+      # : () -> nil
+      def close: () -> nil
+
+      # Writes the queued bytes to io and consumes them.
+      #
+      # : (untyped io) -> Integer
+      def write_to: (untyped io) -> Integer
+
+      # : (Integer? n) -> void
+      private def fill: (Integer? n) -> void
+
+      # : () -> String?
+      private def read_io: () -> String?
+
+      # : (Integer n) -> String
+      private def take: (Integer n) -> String
+
+      # : (String? out, String data) -> String
+      private def replace: (String? out, String data) -> String
+    end
+  end
+end

data/sig/generated/ciborium/compat/errors.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/ciborium/compat/errors.rb with RBS::Inline
+
+module Ciborium
+  module Compat
+    class UnpackError < StandardError
+    end
+
+    class MalformedFormatError < UnpackError
+    end
+
+    class StackError < UnpackError
+    end
+
+    # Raised by Unpacker#read_array_header and #read_map_header on an item of another type.
+    class TypeError < StandardError
+    end
+
+    # Raises the cbor gem's exception for a Ciborium decoding failure, keeping it as the cause.
+    #
+    # : [T] () { () -> T } -> T
+    def self.translate_errors: [T] () { () -> T } -> T
+  end
+end

data/sig/generated/ciborium/compat/packer.rbs

@@ -0,0 +1,53 @@
+# Generated from lib/ciborium/compat/packer.rb with RBS::Inline
+
+module Ciborium
+  module Compat
+    # CBOR::Packer of the cbor gem, writing through Ciborium::Encoder.
+    class Packer
+      @buffer: Buffer
+
+      @encoder: Ciborium::Encoder
+
+      attr_reader buffer: Buffer
+
+      # : (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+      def initialize: (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+
+      # : (untyped object) -> self
+      def write: (untyped object) -> self
+
+      # : () -> self
+      def write_nil: () -> self
+
+      # : (Integer length) -> self
+      def write_array_header: (Integer length) -> self
+
+      # : (Integer length) -> self
+      def write_map_header: (Integer length) -> self
+
+      # : () -> self
+      def flush: () -> self
+
+      # : () -> nil
+      def clear: () -> nil
+
+      # : () -> Integer
+      def size: () -> Integer
+
+      # : () -> bool
+      def empty?: () -> bool
+
+      # : (untyped io) -> Integer
+      def write_to: (untyped io) -> Integer
+
+      # : () -> String
+      def to_str: () -> String
+
+      # : () -> Array[String]
+      def to_a: () -> Array[String]
+
+      # : () -> self
+      private def drain: () -> self
+    end
+  end
+end

data/sig/generated/ciborium/compat/unpacker.rbs

@@ -0,0 +1,59 @@
+# Generated from lib/ciborium/compat/unpacker.rb with RBS::Inline
+
+module Ciborium
+  module Compat
+    # CBOR::Unpacker of the cbor gem, reading through Ciborium::Decoder. Input passes through
+    # buffer, which also reads from io when more is needed.
+    class Unpacker
+      @buffer: Buffer
+
+      @decoder: Ciborium::Decoder
+
+      attr_reader buffer: Buffer
+
+      # options takes symbolize_keys, and the Buffer options.
+      #
+      # : (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+      def initialize: (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+
+      # : (String data) -> self
+      def feed: (String data) -> self
+
+      # : () -> untyped
+      def read: () -> untyped
+
+      # : () -> nil
+      def skip: () -> nil
+
+      # Whether the next item is null. Consumes nothing.
+      #
+      # : () -> bool
+      def skip_nil: () -> bool
+
+      # : () -> Integer
+      def read_array_header: () -> Integer
+
+      # : () -> Integer
+      def read_map_header: () -> Integer
+
+      # Yields each item until the input runs out, leaving a partial item buffered.
+      #
+      # : () { (untyped) -> void } -> nil
+      # : () -> Enumerator[untyped, nil]
+      def each: () { (untyped) -> void } -> nil
+              | () -> Enumerator[untyped, nil]
+
+      # : (String data) { (untyped) -> void } -> nil
+      def feed_each: (String data) { (untyped) -> void } -> nil
+
+      # : () -> nil
+      def reset: () -> nil
+
+      # Runs the block on the decoder, moving more input into it until the block stops raising
+      # IncompleteError or the input ends.
+      #
+      # : [T] () { () -> T } -> T
+      private def with_input: [T] () { () -> T } -> T
+    end
+  end
+end

data/sig/generated/ciborium/compat.rbs

@@ -0,0 +1,57 @@
+# Generated from lib/ciborium/compat.rb with RBS::Inline
+
+module Ciborium
+  # The interface of the cbor gem (CBOR), implemented on top of Ciborium. Tag extensions follow
+  # Compat.extensions, so a tag that is not allowlisted decodes to Tagged. require
+  # "ciborium/replace" to install it as CBOR.
+  module Compat
+    Tagged: untyped
+
+    Simple: untyped
+
+    # Nothing is allowlisted until the application opts in, as with Ciborium itself.
+    DEFAULT_EXTENSIONS: Array[extension]
+
+    self.@extensions: Array[extension]
+
+    # The extensions every Compat entry point uses, process-wide.
+    #
+    # : () -> Array[extension]
+    def self.extensions: () -> Array[extension]
+
+    # : (Array[extension] extensions) -> void
+    def self.extensions=: (Array[extension] extensions) -> void
+
+    # Options for Ciborium::Encoder that reproduce the cbor gem's encoding.
+    #
+    # : () -> Hash[Symbol, untyped]
+    def self.encode_options: () -> Hash[Symbol, untyped]
+
+    # Options for Ciborium::Decoder that reproduce the cbor gem's decoding.
+    #
+    # : () -> Hash[Symbol, untyped]
+    def self.decode_options: () -> Hash[Symbol, untyped]
+
+    # Encodes object, or writes it to io and returns nil when io is given.
+    #
+    # : (untyped object, ?untyped io) -> String?
+    def self.encode: (untyped object, ?untyped io) -> String?
+
+    # Decodes a single item from a String, or from all that an IO holds.
+    #
+    # options is {symbolize_keys: true}, or :keys_as_symbols.
+    #
+    # : (untyped source, ?(Hash[Symbol, untyped] | Symbol)? options) -> untyped
+    def self.decode: (untyped source, ?(Hash[Symbol, untyped] | Symbol)? options) -> untyped
+
+    # Encodes an object Ciborium cannot represent through its own to_cbor(packer), as the cbor
+    # gem does.
+    FALLBACK: ^(untyped) -> untyped
+
+    # to_cbor for the classes the cbor gem extends. Installed by ciborium/replace.
+    module CoreExt
+      # : (?untyped packer_or_io) -> untyped
+      def to_cbor: (?untyped packer_or_io) -> untyped
+    end
+  end
+end

data/sig/generated/ciborium/decode_options.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/ciborium/decode_options.rb with RBS::Inline
+
+module Ciborium
+  DEFAULT_MAX_DEPTH: Integer
+
+  MAX_DEPTH_LIMIT: Integer
+
+  # Encoding rules a profile enforces beyond well-formedness. :ctap2 is the CTAP2 canonical CBOR
+  # encoding form that WebAuthn requires: no tags, no indefinite lengths, arguments in their
+  # shortest form, and map keys ordered without duplicates.
+  PROFILES: Array[Symbol]
+
+  # Decoding options, validated and packed into the arguments the native decoder takes.
+  class DecodeOptions < Data
+    attr_reader max_depth(): Integer
+
+    attr_reader flags(): Integer
+
+    attr_reader handlers(): Hash[Integer, ^(Integer, untyped) -> untyped]?
+
+    def self.new: (Integer max_depth, Integer flags, Hash[Integer, ^(Integer, untyped) -> untyped]? handlers) -> instance
+                | (max_depth: Integer, flags: Integer, handlers: Hash[Integer, ^(Integer, untyped) -> untyped]?) -> instance
+
+    def self.members: () -> [ :max_depth, :flags, :handlers ]
+
+    def members: () -> [ :max_depth, :flags, :handlers ]
+  end
+
+  class DecodeOptions
+    # extensions lists the allowlisted extensions (see Extensions); every other tag decodes to
+    # Tagged. profile rejects input that breaks one of PROFILES.
+    #
+    # : (?extensions: Array[extension], ?symbolize_keys: bool, ?max_depth: Integer, ?duplicate_keys: Symbol, ?profile: Symbol?) -> DecodeOptions
+    def self.build: (?extensions: Array[extension], ?symbolize_keys: bool, ?max_depth: Integer, ?duplicate_keys: Symbol, ?profile: Symbol?) -> DecodeOptions
+
+    # Returns whether profile is :ctap2.
+    #
+    # : (Symbol? profile, untyped extensions) -> bool
+    def self.check_profile: (Symbol? profile, untyped extensions) -> bool
+  end
+end