gmeow-gts 1.0.0.rc.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2e169a98f542d68a7bf37cae39f22769ee76e54c5950fcfe93e5507d3bc5bb5
+  data.tar.gz: 6691d4c9a30319c16ce9c6430b06fef67dc9b7af81a813cbff909c1df4b5b180
+SHA512:
+  metadata.gz: dc1c389118859615b4f72f60f6da0def15b3a31e994ed3f94238eda9508105c93d68e7daab30acc7f1602a11d8194dcbb875dbf23eb646477f2b8c8fc3cfde20
+  data.tar.gz: 5a647fabae6d3a5dac905454d241634d6c40296b318708ddc9c14ab664c8d50b491d8b9645d24242049a39e33af563cd33218842dbccf044458f100c55095602

data/README.md

@@ -0,0 +1,125 @@
+# GTS Ruby C ABI Wrapper
+
+<!-- SPDX-FileCopyrightText: 2026 Blackcat Informatics Inc. <paudley@blackcatinformatics.ca> -->
+<!-- SPDX-License-Identifier: MIT OR Apache-2.0 -->
+
+`gmeow-gts` is a thin Ruby FFI wrapper over the Rust-backed `libgts` C ABI. It
+does not parse, fold, write, or verify GTS archives in Ruby; all GTS semantics
+come from the checked-in C ABI in `rust/capi/include/gts.h`.
+
+## Requirements
+
+- Ruby 3.1 or newer.
+- The `ffi` gem.
+- A built `libgts` shared library from `rust/capi`.
+
+Build the shared library from the repository root:
+
+```sh
+cargo build --manifest-path rust/capi/Cargo.toml
+```
+
+Point the wrapper at the library with `GTS_LIBGTS`:
+
+```sh
+export GTS_LIBGTS="$PWD/rust/capi/target/debug/libgts.so"
+ruby -I ruby/lib ruby/tests/smoke.rb \
+  vectors/01-minimal.gts vectors/04-damaged-frame.gts vectors/28-empty-file.gts
+```
+
+On macOS use `libgts.dylib`; on Windows use `gts.dll`. If `GTS_LIBGTS` is not
+set, the wrapper asks the platform dynamic loader for the default library name.
+
+## RubyGems Installation
+
+The published `gmeow-gts` gem is source-only. It ships the Ruby FFI wrapper and
+declares the `ffi` dependency, but it does not vendor `libgts`.
+
+```sh
+gem install gmeow-gts
+export GTS_LIBGTS=/path/to/libgts.so
+ruby -rgmeow/gts -e 'puts Gmeow::Gts.load.version'
+```
+
+On macOS set `GTS_LIBGTS` to the `.dylib`; on Windows set it to `gts.dll`.
+
+## API Shape
+
+```ruby
+require "gmeow/gts"
+
+gts = Gmeow::Gts.load
+input = File.binread("vectors/01-minimal.gts")
+
+metadata = gts.build_metadata_json
+capabilities = gts.capabilities_json
+folded = gts.read_json(input)
+verified = gts.verify_json(input)
+nquads = gts.to_nquads(input)
+round_trip = gts.from_nquads(nquads)
+```
+
+Files-profile helpers use Ruby strings for binary GTS payloads and ordinary path
+strings for directories:
+
+```ruby
+packed = gts.files_pack(["/path/to/tree"])
+diff = gts.files_diff_json(packed, "/path/to/tree")
+report = gts.files_unpack(packed, "/tmp/unpacked")
+```
+
+These path strings are forwarded to `libgts` as NUL-terminated UTF-8 C strings.
+On Windows this covers only paths representable by that contract, not every
+native wide-character filesystem path. Future wide-character C ABI entry points
+would be additive symbols under the compatibility policy.
+
+## Ownership And Errors
+
+The wrapper copies every returned `gts_buffer` into a Ruby string and then calls
+`gts_buffer_free`. If a C ABI call returns an error handle, the wrapper copies
+the stable error code and message, releases the handle with `gts_error_free`,
+and raises `Gmeow::Gts::Error`.
+
+Callers never receive raw FFI pointers, buffer capacities, or Rust-owned memory.
+Ruby strings are binary-safe and are used for both GTS byte streams and UTF-8
+JSON/N-Quads text.
+
+Raised errors expose:
+
+- `operation`: C ABI operation name.
+- `status`: integer C ABI status code.
+- `status_name`: symbolic C ABI status name.
+- `code`: stable C ABI error code.
+- `detail`: human-readable diagnostic detail.
+
+```ruby
+begin
+  gts.from_nquads("<https://example/s> <https://example/p> .\n")
+rescue Gmeow::Gts::Error => error
+  warn "#{error.status_name} #{error.code}: #{error.detail}"
+end
+```
+
+## Threading And ABI Stability
+
+`libgts` operations are reentrant. Each call owns its output buffer and error
+handle independently, and the Ruby wrapper frees them before returning or
+throwing. Do not share raw FFI values between Ruby runtimes.
+
+The wrapper targets `GTS_ABI_VERSION` 1. Check `gts.abi_version` and
+`gts.capabilities_json` when loading a system-provided `libgts`.
+
+## Validation
+
+Run the smoke test from the repository root:
+
+```sh
+bash ruby/scripts/smoke.sh
+```
+
+The script builds `libgts`, validates the gemspec, and exercises ABI metadata,
+capabilities, read/fold, verify, N-Quads export/import, structured errors, and
+files-profile pack/diff/unpack. It runs the smoke once from the checkout and
+once through an installed local gem with the checkout removed from Ruby's load
+path. If local Ruby with the `ffi` gem is missing, it uses the pinned fallback
+image defined in `ruby/Dockerfile`.

data/lib/gmeow/gts.rb

@@ -0,0 +1,323 @@
+# SPDX-FileCopyrightText: 2026 Blackcat Informatics Inc. <paudley@blackcatinformatics.ca>
+# SPDX-License-Identifier: MIT OR Apache-2.0
+
+require "ffi"
+require "rbconfig"
+require "thread"
+
+module Gmeow
+  module Gts
+    VERSION = "1.0.0.rc.1"
+    ABI_VERSION = 1
+    UINT32_MAX = 0xffff_ffff
+
+    module Status
+      OK = 0
+      INVALID_ARGUMENT = 1
+      IO = 2
+      PARSE = 3
+      DIAGNOSTIC = 4
+      INTERNAL = 5
+      PANIC = 6
+    end
+
+    module UnpackFlags
+      NONE = 0
+      INCLUDE_SUPPRESSED = 1 << 0
+      ALLOW_SYMLINKS = 1 << 1
+      ALLOW_SPECIAL = 1 << 2
+      SAME_OWNER = 1 << 3
+      PRESERVE_SETID = 1 << 4
+    end
+
+    STATUS_NAMES = {
+      Status::OK => "OK",
+      Status::INVALID_ARGUMENT => "INVALID_ARGUMENT",
+      Status::IO => "IO",
+      Status::PARSE => "PARSE",
+      Status::DIAGNOSTIC => "DIAGNOSTIC",
+      Status::INTERNAL => "INTERNAL",
+      Status::PANIC => "PANIC"
+    }.freeze
+
+    class Error < StandardError
+      attr_reader :operation, :status, :status_name, :code, :detail
+
+      def initialize(operation:, status:, code:, detail:)
+        @operation = operation
+        @status = status
+        @status_name = Gts.status_name(status)
+        @code = code
+        @detail = detail
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        message = "#{operation} failed with #{status_name}"
+        message = "#{message} (#{code})" unless code.empty?
+        message = "#{message}: #{detail}" unless detail.empty?
+        message
+      end
+    end
+
+    class Buffer < FFI::Struct
+      layout :data, :pointer,
+             :len, :size_t,
+             :capacity, :size_t
+    end
+
+    module Native
+      @modules = {}
+      @mutex = Mutex.new
+
+      def self.bind(library)
+        key = library.to_s
+        @mutex.synchronize do
+          @modules[key] ||= build(key)
+        end
+      end
+
+      def self.build(library)
+        Module.new do
+          extend FFI::Library
+
+          ffi_lib library
+
+          attach_function :gts_abi_version, [], :uint32
+          attach_function :gts_version, [], :pointer
+
+          attach_function :gts_buffer_free, [:pointer], :void
+          attach_function :gts_error_free, [:pointer], :void
+          attach_function :gts_error_code, [:pointer], :pointer
+          attach_function :gts_error_message, [:pointer], :pointer
+
+          attach_function :gts_build_metadata_json, [:pointer, :pointer], :int
+          attach_function :gts_capabilities_json, [:pointer, :pointer], :int
+          attach_function :gts_read_json, [:pointer, :size_t, :pointer, :pointer], :int
+          attach_function :gts_verify_json, [:pointer, :size_t, :pointer, :pointer], :int
+          attach_function :gts_to_nquads, [:pointer, :size_t, :pointer, :pointer], :int
+          attach_function :gts_from_nquads, [:pointer, :size_t, :pointer, :pointer], :int
+          attach_function :gts_files_pack, [:pointer, :size_t, :pointer, :pointer], :int
+          attach_function :gts_files_unpack,
+                          [:pointer, :size_t, :pointer, :uint32, :pointer, :pointer],
+                          :int
+          attach_function :gts_files_diff_json,
+                          [:pointer, :size_t, :pointer, :pointer, :pointer],
+                          :int
+        end
+      end
+
+      private_class_method :build
+    end
+
+    class Library
+      def initialize(library = nil)
+        @native = Native.bind(library || Gts.default_library)
+      end
+
+      def abi_version
+        @native.gts_abi_version
+      end
+
+      def version
+        copy_c_string(@native.gts_version)
+      end
+
+      def build_metadata_json
+        call_buffer("gts_build_metadata_json") do |out, error|
+          @native.gts_build_metadata_json(out, error)
+        end
+      end
+
+      def capabilities_json
+        call_buffer("gts_capabilities_json") do |out, error|
+          @native.gts_capabilities_json(out, error)
+        end
+      end
+
+      def read_json(data)
+        with_bytes(data, "data") do |pointer, length|
+          call_buffer("gts_read_json") do |out, error|
+            @native.gts_read_json(pointer, length, out, error)
+          end
+        end
+      end
+
+      def verify_json(data)
+        with_bytes(data, "data") do |pointer, length|
+          call_buffer("gts_verify_json") do |out, error|
+            @native.gts_verify_json(pointer, length, out, error)
+          end
+        end
+      end
+
+      def to_nquads(data)
+        with_bytes(data, "data") do |pointer, length|
+          call_buffer("gts_to_nquads") do |out, error|
+            @native.gts_to_nquads(pointer, length, out, error)
+          end
+        end
+      end
+
+      def from_nquads(text)
+        with_bytes(text, "text") do |pointer, length|
+          call_buffer("gts_from_nquads") do |out, error|
+            @native.gts_from_nquads(pointer, length, out, error)
+          end
+        end
+      end
+
+      def files_pack(paths)
+        path_pointers, keepalive = native_path_list(paths)
+        call_buffer("gts_files_pack") do |out, error|
+          @native.gts_files_pack(path_pointers, keepalive.length, out, error)
+        end
+      end
+
+      def files_unpack(data, destination, flags = UnpackFlags::NONE)
+        destination_pointer = native_string(destination, "destination")
+        unpack_flags = checked_uint32(flags, "flags")
+
+        with_bytes(data, "data") do |pointer, length|
+          call_buffer("gts_files_unpack") do |out, error|
+            @native.gts_files_unpack(pointer, length, destination_pointer, unpack_flags, out, error)
+          end
+        end
+      end
+
+      def files_diff_json(data, directory)
+        directory_pointer = native_string(directory, "directory")
+
+        with_bytes(data, "data") do |pointer, length|
+          call_buffer("gts_files_diff_json") do |out, error|
+            @native.gts_files_diff_json(pointer, length, directory_pointer, out, error)
+          end
+        end
+      end
+
+      private
+
+      def call_buffer(operation)
+        out = new_buffer
+        error = FFI::MemoryPointer.new(:pointer)
+        error.write_pointer(FFI::Pointer::NULL)
+
+        begin
+          status = yield(out.to_ptr, error)
+          err_ptr = error.read_pointer
+          if status != Status::OK
+            raise build_error(operation, status, err_ptr)
+          end
+          unless err_ptr.null?
+            raise build_error(operation, Status::INTERNAL, err_ptr)
+          end
+          copy_buffer(out)
+        ensure
+          @native.gts_buffer_free(out.to_ptr)
+        end
+      end
+
+      def new_buffer
+        buffer = Buffer.new
+        buffer[:data] = FFI::Pointer::NULL
+        buffer[:len] = 0
+        buffer[:capacity] = 0
+        buffer
+      end
+
+      def build_error(operation, status, error)
+        code = ""
+        detail = ""
+
+        unless error.null?
+          begin
+            code = copy_c_string(@native.gts_error_code(error))
+            detail = copy_c_string(@native.gts_error_message(error))
+          ensure
+            @native.gts_error_free(error)
+          end
+        end
+
+        Error.new(operation: operation, status: status, code: code, detail: detail)
+      end
+
+      def copy_buffer(buffer)
+        length = buffer[:len]
+        return "" if length.zero?
+
+        data = buffer[:data]
+        raise RuntimeError, "C ABI returned a null data pointer with non-zero length." if data.null?
+
+        data.read_string_length(length)
+      end
+
+      def copy_c_string(pointer)
+        return "" if pointer.nil? || pointer.null?
+
+        pointer.read_string
+      end
+
+      def with_bytes(value, name)
+        raise TypeError, "#{name} must be a String" unless value.is_a?(String)
+
+        length = value.bytesize
+        pointer = FFI::MemoryPointer.new(:uint8, [length, 1].max)
+        pointer.put_bytes(0, value) unless length.zero?
+        yield(pointer, length)
+      end
+
+      def native_string(value, name)
+        raise TypeError, "#{name} must be a String" unless value.is_a?(String)
+        raise ArgumentError, "#{name} must not contain NUL bytes" if value.include?("\0")
+
+        FFI::MemoryPointer.from_string(value)
+      end
+
+      def native_path_list(paths)
+        raise TypeError, "paths must be an Array" unless paths.is_a?(Array)
+        raise ArgumentError, "paths must not be empty" if paths.empty?
+
+        pointer_array = FFI::MemoryPointer.new(:pointer, paths.length)
+        keepalive = paths.each_with_index.map do |path, index|
+          pointer = native_string(path, "paths[#{index}]")
+          pointer_array.put_pointer(index * FFI.type_size(:pointer), pointer)
+          pointer
+        end
+
+        [pointer_array, keepalive]
+      end
+
+      def checked_uint32(value, name)
+        raise TypeError, "#{name} must be an Integer" unless value.is_a?(Integer)
+        raise RangeError, "#{name} must be an unsigned 32-bit integer" if value.negative? || value > UINT32_MAX
+
+        value
+      end
+    end
+
+    def self.default_library
+      from_env = ENV.fetch("GTS_LIBGTS", nil)
+      return from_env unless from_env.nil? || from_env.empty?
+
+      host_os = RbConfig::CONFIG.fetch("host_os", "")
+      case host_os
+      when /darwin/i
+        "libgts.dylib"
+      when /mswin|mingw|cygwin/i
+        "gts.dll"
+      else
+        "libgts.so"
+      end
+    end
+
+    def self.load(library = nil)
+      Library.new(library)
+    end
+
+    def self.status_name(status)
+      STATUS_NAMES.fetch(status, "UNKNOWN")
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: gmeow-gts
+version: !ruby/object:Gem::Version
+  version: 1.0.0.rc.1
+platform: ruby
+authors:
+- Blackcat Informatics
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+description: A source-only Ruby FFI wrapper over the Rust-backed libgts C ABI. The
+  gem expects libgts to be provided by the host at runtime.
+email:
+- paudley@blackcatinformatics.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/gmeow/gts.rb
+homepage: https://blackcatinformatics.ca/projects/gts
+licenses:
+- MIT
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/Blackcat-Informatics/gmeow-gts/blob/main/CHANGELOG.md
+  homepage_uri: https://blackcatinformatics.ca/projects/gts
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/Blackcat-Informatics/gmeow-gts
+  bug_tracker_uri: https://github.com/Blackcat-Informatics/gmeow-gts/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby FFI wrapper for the source-only GTS C ABI.
+test_files: []