oxygene 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16f8b923311bdcd734666a03e4beff53a786b13a131a29e2ae834996d6c8545e
+  data.tar.gz: c3c3ebc73bc19bdc937425757a1563c181e2790d6e3a87a76d086675540ed68c
+SHA512:
+  metadata.gz: 30e917d087c398a27af26984842f5a71901093599310244f12794614ec1f5326614a2465021d6d2936c633ca9429246be493fa21e13ef4464054e5b02f7096af
+  data.tar.gz: 58c550605cdaf83a38aeb0a49c67fa4badafeed1ac5f2991b969179e609db485e05f17aa21cc4c42e092a06ec44f791c7fa02e3bcd6225602d7b7fbf69086941

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.0.1] - 2026-08-05
+
+- initial release - extracted `CID` and `CARArchive` from Skyfall

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The zlib License
+
+Copyright (c) 2026 Jakub Suder
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.md

@@ -0,0 +1,15 @@
+# Oxygène
+
+*(n) Gaz incolore, inodore et sans saveur qui compose 1/5ème de l'air atmosphérique.*
+
+Various data decoding primitives for working with AT Protocol and the Atmosphere (including CAR, CID, CBOR). (Extracted from [Skyfall](https://tangled.org/mackuba.eu/skyfall), work in progress.)
+
+> [!NOTE]
+> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
+
+
+## Credits
+
+Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
+
+The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).

data/lib/oxygene/car_archive.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative 'cid'
+require_relative 'errors'
+require_relative 'extensions'
+
+require 'base64'
+require 'cbor'
+require 'stringio'
+
+# CAR v1: https://ipld.io/specs/transport/car/carv1/
+# multicodec codes: https://github.com/multiformats/multicodec/blob/master/table.csv
+
+module Oxygene
+  class CARSection
+    attr_reader :cid
+
+    def initialize(cid, body_data)
+      @cid = cid
+      @body_data = body_data
+    end
+
+    def body
+      @body ||= CARArchive.convert_data(CBOR.decode(@body_data))
+    end
+  end
+
+  class CARArchive
+    using Oxygene::Extensions
+
+    attr_reader :roots, :sections
+
+    def initialize(data)
+      @sections = []
+      @buffer = StringIO.new(data)
+
+      read_header(@buffer)
+    end
+
+    def section_with_cid(cid)
+      if section = @sections.detect { |s| s.cid == cid }
+        return section.body
+      end
+
+      if @buffer
+        while !@buffer.eof?
+          section = read_section(@buffer)
+          return section.body if section.cid == cid
+        end
+      end
+
+      @buffer = nil
+      nil
+    end
+
+    def sections
+      if @buffer
+        read_section(@buffer) while !@buffer.eof?
+        @buffer = nil
+      end
+
+      @sections
+    end
+
+    def self.convert_data(object)
+      if object.is_a?(Hash)
+        object.each do |k, v|
+          if v.is_a?(Hash) || v.is_a?(Array)
+            convert_data(v)
+          elsif v.is_a?(CBOR::Tagged)
+            object[k] = make_cid_link(v)
+          elsif v.is_a?(String) && v.encoding == Encoding::ASCII_8BIT
+            object[k] = make_bytes(v)
+          end
+        end
+      elsif object.is_a?(Array)
+        object.each_with_index do |v, i|
+          if v.is_a?(Hash) || v.is_a?(Array)
+            convert_data(v)
+          elsif v.is_a?(CBOR::Tagged)
+            object[i] = make_cid_link(v)
+          elsif v.is_a?(String) && v.encoding == Encoding::ASCII_8BIT
+            object[i] = make_bytes(v)
+          end
+        end
+      else
+        raise DecodeError, "Unexpected value type in record: #{object}"
+      end
+    end
+
+    def self.make_cid_link(cid)
+      { '$link' => CID.from_cbor_tag(cid) }
+    end
+
+    def self.make_bytes(data)
+      { '$bytes' => Base64.encode64(data).chomp.gsub(/=+$/, '') }
+    end
+
+    def inspect
+      vars = instance_variables.map { |v|
+        if v == :@sections && @buffer
+          "#{v}=[...]"
+        else
+          "#{v}=#{instance_variable_get(v).inspect}"
+        end
+      }
+
+      "#<#{self.class}:0x#{object_id} #{vars.join(", ")}>"
+    end
+
+    private
+
+    def read_header(buffer)
+      len = buffer.read_varint
+
+      header_data = buffer.read(len)
+      raise DecodeError.new("Header too short: #{header_data}") unless header_data.length == len
+
+      header = CBOR.decode(header_data)
+      raise UnsupportedError.new("Unexpected CAR version: #{header['version']}") unless header['version'] == 1
+      @roots = header['roots'].map { |x| CID.from_cbor_tag(x) }
+    end
+
+    def read_section(buffer)
+      len = buffer.read_varint
+
+      section_data = buffer.read(len)
+      raise DecodeError.new("Section too short: #{section_data}") unless section_data.length == len
+
+      sbuffer = StringIO.new(section_data)
+
+      version = sbuffer.read_varint
+      raise UnsupportedError.new("Unexpected CID version: #{version}") unless version == 1
+
+      codec = sbuffer.read_varint
+      raise UnsupportedError.new("Unexpected CID codec: #{codec}") unless codec == 0x71  # dag-cbor
+
+      hash = sbuffer.read_varint
+      raise UnsupportedError.new("Unexpected CID hash: #{hash}") unless hash == 0x12  # sha2-256
+
+      clen = sbuffer.read_varint
+      raise UnsupportedError.new("Unexpected CID length: #{clen}") unless clen == 32
+
+      prefix = section_data[0...sbuffer.pos]
+
+      cid_data = sbuffer.read(clen)
+      raise DecodeError.new("CID too short: #{cid_data}") unless cid_data.length == clen
+
+      cid = CID.new(prefix + cid_data)
+
+      body_data = sbuffer.read
+      new_section = CARSection.new(cid, body_data)
+
+      @sections << new_section
+      new_section
+    end
+  end
+end

data/lib/oxygene/cid.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+require 'base32'
+
+# CIDs in DAG-CBOR: https://ipld.io/specs/codecs/dag-cbor/spec/
+# CIDs in JSON: https://ipld.io/specs/codecs/dag-json/spec/
+# multibase: https://github.com/multiformats/multibase
+
+module Oxygene
+  class CID
+    attr_reader :data
+
+    def self.from_cbor_tag(tag)
+      data = tag.value
+      raise DecodeError.new("Unexpected first byte of CID: #{data[0]}") unless data[0] == "\x00"
+      CID.new(data[1..-1])
+    end
+
+    def self.from_json(string)
+      raise DecodeError.new("Unexpected CID length") unless string.length == 59
+      raise DecodeError.new("Unexpected CID prefix") unless string[0] == 'b'
+
+      data = Base32.decode(string[1..-1].upcase)
+      CID.new(data)
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def to_s
+      'b' + Base32.encode(@data).downcase.gsub(/=+$/, '')
+    end
+
+    def inspect
+      "CID(\"#{to_s}\")"
+    end
+
+    def ==(other)
+      other.is_a?(CID) && @data == other.data
+    end
+  end
+end

data/lib/oxygene/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Oxygene
+  #
+  # Wrapper base class for Oxygene error classes.
+  #
+  class Error < StandardError
+  end
+
+  #
+  # Raised when some part of the data being decoded has invalid format.
+  #
+  class DecodeError < Error
+  end
+
+  #
+  # Raised when a piece of data is technically formatted correctly, but not in a version
+  # that this library currently supports (or that is used in ATProto).
+  #
+  class UnsupportedError < Error
+  end
+end

data/lib/oxygene/extensions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'cbor'
+require 'stringio'
+
+module Oxygene
+
+  # @private
+  module Extensions
+
+    refine StringIO do
+      # https://en.wikipedia.org/wiki/LEB128
+      def read_varint
+        shift = 1
+        value = 0
+
+        loop do
+          byte = self.readbyte
+          value += byte % 128 * shift
+          break if byte < 128
+          shift *= 128
+        end
+
+        value
+      end
+    end
+
+    refine CBOR.singleton_class do
+      def decode_sequence(data)
+        unpacker = CBOR::Unpacker.new(StringIO.new(data))
+        unpacker.each.to_a
+      end
+    end
+
+  end
+end

data/lib/oxygene/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Oxygene
+  VERSION = '0.0.1'
+end

data/lib/oxygene.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'oxygene/car_archive'
+require_relative 'oxygene/cid'
+require_relative 'oxygene/version'
+
+module Oxygene
+end

data/sig/oxygene.rbs

@@ -0,0 +1,4 @@
+module Oxygene
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: oxygene
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kuba Suder
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base32
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: cbor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.9
+email:
+- jakub.suder@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/oxygene.rb
+- lib/oxygene/car_archive.rb
+- lib/oxygene/cid.rb
+- lib/oxygene/errors.rb
+- lib/oxygene/extensions.rb
+- lib/oxygene/version.rb
+- sig/oxygene.rbs
+homepage: https://ruby.sdk.blue
+licenses:
+- Zlib
+metadata:
+  bug_tracker_uri: https://tangled.org/mackuba.eu/oxygene/issues
+  changelog_uri: https://tangled.org/mackuba.eu/oxygene/blob/master/CHANGELOG.md
+  source_code_uri: https://tangled.org/mackuba.eu/oxygene
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Various data decoding primitives for ATProto (CAR, CID, CBOR)
+test_files: []