identifold 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f99add5498f8f16b2d918e04eca8814b5193909b1e7151874ececd4556f23c65
+  data.tar.gz: e6a40150899cad674ac403bf60dc0bc1b786e52728d7768f5143e4d8bf11ad7b
+SHA512:
+  metadata.gz: b01e97aef84dade2e6f8d4c91fb5790563285d2639250cdd23ab31cc4dc9d0a750940e07e1b23b2e787cb34c89613199f99f91131d9dbc9b3b867828978f245a
+  data.tar.gz: 6027d7c7e7ea6b847764e75f88118149eb80cadc4c4b80ed3571eec914d6f7c247cb0f5f41b0792a2d9ca8f08f83d63d6b9633df6760f1ebc6bc9edcd955fbd6

data/README.md

@@ -0,0 +1,10 @@
+# Identifold for Ruby
+
+The Ruby gem implements the stable Identifold 1.0 MID, PID, and REF wire contract for Ruby 3.2 and later.
+
+```ruby
+pid = Identifold.public_id_from_machine_id(mid, "order")
+parsed = Identifold.parse_public_id(pid)
+```
+
+The dependency-free core and JSON adapter are exercised by the language-neutral conformance runner.

data/lib/identifold.rb

@@ -0,0 +1,165 @@
+module Identifold
+  DATA = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+  CHECK = DATA + "*~$=U"
+  TYPE_ID = "0123456789abcdefghjkmnpqrstvwxyz"
+
+  class Error < ArgumentError
+    attr_reader :code
+
+    def initialize(code)
+      super(code)
+      @code = code
+    end
+  end
+
+  module_function
+
+  def parse_machine_id(input)
+    value = input.to_s.downcase
+    raise Error, "invalid_mid" unless value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/)
+    raise Error, "invalid_uuid_version" unless value[14] == "7"
+    raise Error, "invalid_mid" unless "89ab".include?(value[19])
+
+    value
+  end
+
+  def public_id_from_machine_id(machine_id, namespace)
+    raise Error, "invalid_public_prefix" unless namespace.match?(/\A[a-z](?:[a-z_]{0,61}[a-z])?\z/)
+
+    number = parse_machine_id(machine_id).delete("-").to_i(16)
+    suffix = Array.new(26, "0")
+    25.downto(0) do |index|
+      suffix[index] = TYPE_ID[number & 31]
+      number >>= 5
+    end
+    "#{namespace}_#{suffix.join}"
+  end
+
+  def parse_public_id(value)
+    raise Error, "invalid_pid" unless value == value.downcase
+
+    separator = value.rindex("_")
+    raise Error, "invalid_public_prefix" unless separator
+
+    namespace = value[...separator]
+    suffix = value[(separator + 1)..]
+    raise Error, "invalid_public_prefix" unless namespace.match?(/\A[a-z](?:[a-z_]{0,61}[a-z])?\z/)
+    raise Error, "invalid_pid" unless suffix.length == 26 && suffix[0] <= "7"
+
+    number = 0
+    suffix.each_char do |symbol|
+      position = TYPE_ID.index(symbol)
+      raise Error, "invalid_pid" unless position
+
+      number = (number << 5) | position
+    end
+    hex = number.to_s(16).rjust(32, "0")
+    machine_id = [hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12]].join("-")
+    begin
+      machine_id = parse_machine_id(machine_id)
+    rescue Error
+      raise Error, "invalid_pid"
+    end
+    { value: value, namespace: namespace, machineId: machine_id }
+  end
+
+  def check_symbol(payload, sequential)
+    alphabet = sequential ? "0123456789" : DATA
+    base = sequential ? 10 : 32
+    remainder = 0
+    payload.each_char do |symbol|
+      position = alphabet.index(symbol)
+      raise Error, "invalid_ref_symbol" unless position
+
+      remainder = (remainder * base + position) % 37
+    end
+    CHECK[remainder]
+  end
+
+  def create_reference_candidate(registry, namespace, random_bytes)
+    reference = find_namespace(registry, namespace)["reference"]
+    raise Error, "unknown_namespace" unless reference && reference["strategy"] == "random"
+
+    length = profile_length(reference["profile"])
+    raise Error, "invalid_random_source" if random_bytes.length < length
+
+    payload = random_bytes.first(length).map do |value|
+      raise Error, "invalid_random_source" unless value.between?(0, 255)
+
+      DATA[value % 32]
+    end.join
+    "#{reference["prefix"]}-#{group(payload)}-#{check_symbol(payload, false)}"
+  end
+
+  def format_sequential_reference(registry, namespace, sequence, scope = "")
+    reference = find_namespace(registry, namespace)["reference"]
+    raise Error, "unknown_namespace" unless reference && reference["strategy"] == "sequence"
+
+    width = reference["width"]
+    raise Error, "sequence_overflow" unless sequence.match?(/\A\d+\z/) && sequence.length <= width
+
+    padded = sequence.rjust(width, "0")
+    payload = scope + padded
+    "#{reference["prefix"]}-#{scope.empty? ? "" : "#{scope}-"}#{padded}-#{check_symbol(payload, true)}"
+  end
+
+  def normalize(value, registry)
+    if value.include?("_")
+      parsed = parse_public_id(value)
+      find_namespace(registry, parsed[:namespace])
+      return parsed[:value]
+    end
+    return parse_machine_id(value) if value.length == 36
+
+    compact = value.upcase.delete("-")
+    definition = registry.find do |candidate|
+      reference = candidate["reference"]
+      reference && compact.start_with?(reference["prefix"])
+    end
+    unless definition
+      raise Error, value.match?(/\A[A-Za-z]{2,8}/) ? "unknown_namespace" : "invalid_kind"
+    end
+
+    reference = definition["reference"]
+    body = compact[reference["prefix"].length..]
+    raise Error, "invalid_ref" if body.include?("?") || body.include?("_")
+
+    if reference["strategy"] == "sequence"
+      scope_length = reference["scope"] == "calendar-year" ? 4 : 0
+      raise Error, "invalid_ref_length" unless body.length == scope_length + reference["width"] + 1
+
+      payload = body[...-1]
+      raise Error, "invalid_checksum" unless check_symbol(payload, true) == body[-1]
+
+      return format_sequential_reference(
+        registry,
+        definition["publicPrefix"],
+        payload[scope_length..],
+        payload[0, scope_length]
+      )
+    end
+
+    length = profile_length(reference["profile"])
+    raise Error, "invalid_ref_length" unless body.length == length + 1
+
+    payload = body[0, length].tr("OIL", "011")
+    raise Error, "invalid_checksum" unless check_symbol(payload, false) == body[-1]
+
+    "#{reference["prefix"]}-#{group(payload)}-#{body[-1]}"
+  end
+
+  def find_namespace(registry, namespace)
+    registry.find { |definition| definition["publicPrefix"] == namespace } || raise(Error, "unknown_namespace")
+  end
+  private_class_method :find_namespace
+
+  def profile_length(profile)
+    { "compact" => 8, "high" => 12 }.fetch(profile, 10)
+  end
+  private_class_method :profile_length
+
+  def group(value)
+    value.scan(/.{1,4}/).join("-")
+  end
+  private_class_method :group
+end

metadata

@@ -0,0 +1,40 @@
+--- !ruby/object:Gem::Specification
+name: identifold
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Greyfoundry
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: UUIDv7 MIDs, TypeID-compatible PIDs, and checksummed human references.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/identifold.rb
+homepage: https://github.com/greyfoundry/identifold
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Identifold 1.0 identifiers for Ruby
+test_files: []