logquill 3.0.0.rc5-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f87d16ab87b9a69d4d3a5228430dac3e84d2b2b22770ef623706e299858be54
+  data.tar.gz: 54bbdc85a3a0d86dbf6774b9b089db5098ad9f86811edbb96c36e197b2741f8e
+SHA512:
+  metadata.gz: 0325a0085657e5551e574dd3a8d6234311197153af8d884c96053a399738e04bf73ddf54374bfaf486a8553da09b8373c382487f1091af0a70e0311020dbb114
+  data.tar.gz: c247abadc81067960c2a3f54b15663698028889fad959fcd1e1b86e07ebe976401f07e5f6aeff59ec209e55f1e489556445cdc211f926e677bd8b7d2f2c53a76

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Arora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# logquill (Ruby)
+
+Structured logging for Ruby on LogQuill's Rust core, through its C ABI (`crates/logquill-ffi`). The same record shape,
+the same redaction and the same tamper-evident hash chain as the Python, Node, browser and other bindings: redaction and
+the level filter run in Rust before anything is written.
+
+> **Not published yet.** The gem is unreleased: the 3.0 line is MIT licensed and a release candidate (3.0.0-rc.5) is prepared but not published
+> (`docs/stages/stage-9.md`). See [Build and test](#build-and-test) to use it from this repository.
+
+## Use it
+
+```ruby
+require "logquill"
+
+log = Logquill::Logger.new(
+  name: "web",
+  plugins: [{ type: "redact" }, { type: "pii" }],
+  transports: [{ type: "file", path: "web.log" }]
+)
+
+log.info("signed in", user: "alice@example.com", password: "hunter2")
+log.child("db", component: "pg").warn("slow query", ms: 840)
+log.close
+```
+
+`web.log` now has two JSON lines. In the first, `password` is `"***"` and the address in `user` is `***`; the second has
+`"logger": "web.db"` and `component` and `ms` in `meta`. Call `close` (or `flush`) before the process ends: records are
+written on a background thread.
+
+### The logger
+
+- `Logquill::Logger.new(name:, level:, plugins:, transports:, content_policy:, tamper_evident:, queue:, return_record:)`.
+  `level` is `:trace :debug :info :warn :error :fatal` (default `:info`). A wrong option raises `Logquill::ConfigError`
+  saying which one and what is allowed; an unknown option is an error, not ignored, so a typo cannot quietly leave a
+  secret in the log.
+- `log.info(message, key: value, ..., llm: { model:, tokens_in:, ... })`, and the same for `trace debug warn error fatal`.
+  Returns `true` when the record was kept and `false` when it was filtered (or could not be logged). With
+  `return_record: true` it returns the finished record as a Hash instead. **A log call never raises**: a value JSON cannot
+  carry (NaN, a cycle, an object whose `to_s` raises, bytes that are not UTF-8) is turned into text, and a failure is
+  reported with `Kernel#warn`.
+- `log.child("db", component: "pg")` is a logger named `web.db` with that meta on every record, sharing the level and
+  transports. `log.set_level(:error)` changes the level for the logger, its parent and its children.
+- `plugins:` are `{ type: "redact", keys:, classes:, replacement: }`, `{ type: "pii", replacement: }`, `{ type: "sampling", rate: }`,
+  `{ type: "rate_limit", max_records:, per_seconds:, key: }` and `{ type: "adaptive_sampling", ... }` (or build them with
+  `Logquill::Plugins.redact`, `.pii`, `.sampling(rate:)`, `.rate_limit(...)`, `.adaptive_sampling(...)`), run in order in
+  Rust. `content_policy:` is `off` (the default: prompt, completion and tool content is withheld), `hash`, `truncate` or
+  `full`. `tamper_evident: true` chains each record as it is written; check a log file with `Logquill.verify_chain`.
+- `transports:` takes Hashes for Rust transports (`{ type: "console", format: "json", colour: false }` or
+  `{ type: "file", path:, format:, max_bytes:, backup_count:, compression: "gz" }`) and also any object that responds to
+  `write(line, record)`: a Ruby transport, called on your thread with the finished, already-redacted record. It may also
+  define `flush` and `close`.
+
+### Context
+
+```ruby
+Logquill.with_context(request_id: "r-1") { log.info("handling") }   # request_id is in meta
+```
+
+The context is fiber-local: other threads do not see it, and a thread started inside the block does not inherit it. The
+call's own fields win over the context.
+
+### Helpers and the hash chain
+
+Every stateless helper of the core is a method: `Logquill.canonical_json`, `pii_redact_text`, `redact_meta`,
+`verify_chain`, `verify_signed_chain`, `format_text`, `parse_record`, `build_trace`, ... (`Logquill::HELPERS` lists them by
+their Node-addon names; `Logquill.call("canonicalJson", ...)` runs one by that name). A record, `meta` or list of records
+may be a Hash or a String of JSON text; **pass text when a number's spelling matters**, since `1` and `1.0` hash
+differently in a chain. `Logquill::Chain` stamps records and signs its head:
+
+```ruby
+chain = Logquill::Chain.new
+records = [chain.stamp(record_one), chain.stamp(record_two)]
+Logquill.verify_chain(records)               # => { ok: true, records_checked: 2, head_hash: "..." }
+Logquill.verify_signed_chain(records, "key", chain.sign_head("key"))   # also catches a deleted last line
+```
+
+## Not in this gem (yet)
+
+The medium-tier bindings ship the facade, context, console / file transports and Ruby transports. Not here: HTTP, cloud and
+database transports (write a Ruby transport), framework adapters and SDK patching, the standard-library `Logger` bridge,
+and tail sampling, the flight recorder and the run summary (the C ABI does not carry them yet). Host-language *plugins* that change a record are not possible either: the Rust
+transports have written it by the time Ruby sees it; use a Ruby transport to act on a record.
+
+## Build and test
+
+You need Ruby 3.1 or newer and a Rust toolchain. From the repository root:
+
+```sh
+cargo build -p logquill-ffi --release      # the shared library
+cd bindings/ruby
+gem install ffi minitest
+ruby -Ilib test/test_logquill.rb           # 21 tests
+ruby -Ilib test/test_readme.rb             # the example above is a file that is run, and this README must contain it
+ruby scripts/pack_smoke.rb                 # build a platform gem, install it into an empty gem home, use it by name
+```
+
+The gem looks for the library in `LOGQUILL_LIB` (a path to the file), then inside the gem (`lib/logquill/native/`, how a
+platform gem ships it), then in `target/release` and `target/debug` of this repository. The C ABI version is checked at
+load: a library with a different one is refused.

data/lib/logquill/chain.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Logquill
+  # A hash chain: each record stamped through it carries `meta.prev_hash` and `meta.hash`, so a log can be checked later
+  # for an edited or removed line (Logquill.verify_chain). Safe to share between threads.
+  class Chain
+    # `genesis` is the hash the chain starts from; nil is the standard one.
+    def initialize(genesis = nil)
+      error = Native.error_slot
+      handle = Native.lq_chain_new(Native.c_text(genesis), error)
+      raise Error, Native.error_from(error) if handle.null?
+
+      @handle = FFI::AutoPointer.new(handle, Native.method(:lq_chain_free))
+    end
+
+    # Chains `record` (a Hash, or a String of JSON text) and returns it as a Hash with the hashes set.
+    def stamp(record)
+      text = record.is_a?(String) ? record : JsonSafe.dump(record)
+      error = Native.error_slot
+      out = Native.lq_chain_stamp(@handle, Native.c_text(text), error)
+      raise Error, Native.error_from(error) if out.null?
+
+      JSON.parse(Native.take(out))
+    end
+
+    # The hash of the last record chained.
+    def head
+      error = Native.error_slot
+      out = Native.lq_chain_head(@handle, error)
+      raise Error, Native.error_from(error) if out.null?
+
+      Native.take(out)
+    end
+
+    # HMAC-SHA256 of the head under `key` (a String of bytes), hex-encoded: a signature that a deleted last line breaks.
+    def sign_head(key)
+      bytes = key.to_s.b
+      buffer = FFI::MemoryPointer.new(:uint8, [bytes.bytesize, 1].max)
+      buffer.put_bytes(0, bytes)
+      error = Native.error_slot
+      out = Native.lq_chain_sign_head(@handle, buffer, bytes.bytesize, error)
+      raise Error, Native.error_from(error) if out.null?
+
+      Native.take(out)
+    end
+  end
+end

data/lib/logquill/helpers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Logquill
+  class Error < StandardError; end
+
+  # Raised by Logger.new for a config the core rejects; the message says which option and what is allowed.
+  class ConfigError < Error; end
+
+  # The stateless helpers of the C ABI, named as the Node addon names them. Each is also a snake_case method on Logquill
+  # (`Logquill.canonical_json`, `Logquill.verify_chain`, ...). `Logquill.call` runs one by its original name.
+  HELPERS = %w[
+    canonicalJson formatJson formatText formatLogfmt parseLogfmt parseRecord genesisHash verifyChain signHead
+    verifyHeadSignature verifySignedChain redactMeta redactLocal piiRedactMeta piiRedactText applyPolicyValue
+    applyContentPolicy contentFields fieldClasses keysInClass toEcsDocument sqlRow createTableSql graphRow cypher
+    leafPlaceholder levelFromJson utcTimestamp formatTimestamp buildLlmBlock parseTraceHeader spanIdFor traceIdFor
+    traceIdFromParent captureEnv captureContentEnabled semconvResolve epochNs classifyRecord logAttributes exportSpec
+    buildTrace
+  ].freeze
+
+  # Arguments that are binary keys cross as base64, for these helpers, at these positions.
+  KEY_ARGUMENTS = { "signHead" => 1, "verifyHeadSignature" => 1, "verifySignedChain" => 1 }.freeze
+
+  class << self
+    # Runs the helper `name` (e.g. "canonicalJson") with `args` and returns the parsed result. A record, `meta` or list of
+    # records may be a Hash / Array, or a String holding its JSON text (pass text when a number's spelling matters: `1`
+    # and `1.0` hash differently in a tamper-evident chain). Raises Logquill::Error with the core's message.
+    def call(name, *args)
+      key_at = KEY_ARGUMENTS[name.to_s]
+      wire = args.each_with_index.map do |arg, i|
+        i == key_at ? [arg.to_s.b].pack("m0") : JsonSafe.call(arg)
+      end
+      error = Native.error_slot
+      out = Native.lq_call(Native.c_text(name), JSON.generate(wire), error)
+      raise Error, Native.error_from(error) if out.null?
+
+      JSON.parse(Native.take(out))
+    end
+
+    HELPERS.each do |helper|
+      snake = helper.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }
+      define_method(snake) { |*args| call(helper, *args) }
+    end
+
+    # The verification results use Ruby's naming.
+    %i[verify_chain verify_signed_chain].each do |method|
+      original = instance_method(method)
+      define_method(method) do |*args|
+        original.bind_call(self, *args).transform_keys { |k| k.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }.to_sym }
+      end
+    end
+
+    # The library's version, e.g. "3.0.0-dev.0".
+    def core_version
+      Native.lq_version
+    end
+  end
+end

data/lib/logquill/json_safe.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Logquill
+  # Turns any Ruby value into one the JSON encoder accepts, without raising: logging must never crash the app over what it
+  # was asked to log. The rules are Python's `default=str` and the other bindings':
+  #
+  # - Hash keys become strings, Symbols become strings, Times become ISO 8601 (UTC);
+  # - NaN and the infinities (which JSON cannot carry) become the strings "NaN", "Infinity", "-Infinity";
+  # - an object that is not plain JSON becomes its `to_s`, or "<unprintable Klass>" if that raises;
+  # - a String that is not valid UTF-8 (or is binary) keeps its valid characters and shows U+FFFD for the bad bytes;
+  # - a cycle, or nesting deeper than DEPTH, becomes "<circular>" / "<too deep>" instead of recursing forever.
+  module JsonSafe
+    DEPTH = 50
+
+    def self.call(value, depth = 0, seen = {})
+      return "<too deep>" if depth > DEPTH
+
+      case value
+      when nil, true, false, Integer then value
+      when String then utf8(value)
+      when Float then finite(value)
+      when Symbol then value.to_s
+      when Time then value.getutc.iso8601(3)
+      when Hash then container(value, seen) { value.each_with_object({}) { |(k, v), out| out[text(k)] = call(v, depth + 1, seen) } }
+      when Array then container(value, seen) { value.map { |item| call(item, depth + 1, seen) } }
+      else printable(value)
+      end
+    end
+
+    def self.container(value, seen)
+      return "<circular>" if seen[value.object_id]
+
+      seen[value.object_id] = true
+      begin
+        yield
+      ensure
+        seen.delete(value.object_id)
+      end
+    end
+
+    def self.utf8(string)
+      return string if string.encoding == Encoding::UTF_8 && string.valid_encoding?
+
+      raw = string.encoding == Encoding::BINARY ? string.dup.force_encoding(Encoding::UTF_8) : string
+      raw.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\u{FFFD}")
+    rescue EncodingError
+      string.b.force_encoding(Encoding::UTF_8).scrub("\u{FFFD}")
+    end
+
+    def self.finite(float)
+      return float if float.finite?
+
+      float.nan? ? "NaN" : (float.positive? ? "Infinity" : "-Infinity")
+    end
+
+    def self.text(key)
+      key.is_a?(String) ? key : printable(key).to_s
+    end
+
+    def self.printable(value)
+      value.to_s
+    rescue StandardError, NotImplementedError
+      "<unprintable #{value.class}>"
+    end
+
+    # JSON text for any value.
+    def self.dump(value)
+      JSON.generate(call(value))
+    end
+  end
+end

data/lib/logquill/logger.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Logquill
+  LEVELS = %i[trace debug info warn error fatal].freeze
+
+  # The context bound by Logquill.with_context, merged into every record logged inside the block. Fiber-local: another
+  # thread or fiber does not see it, and a thread started inside the block does not inherit it.
+  def self.current_context
+    (Thread.current[:logquill_context] || []).reduce({}) { |merged, fields| merged.merge(fields) }
+  end
+
+  # Binds `fields` to every record logged inside the block, by any logger. The call's own fields win over the context.
+  def self.with_context(**fields)
+    stack = (Thread.current[:logquill_context] ||= [])
+    stack.push(fields.transform_keys(&:to_s))
+    yield
+  ensure
+    stack.pop
+  end
+
+  # A logger on the Rust core: level filter, redaction and the hash chain run in Rust before anything is written.
+  #
+  #   log = Logquill::Logger.new(name: "web", level: :info,
+  #                              plugins: [{ type: "redact" }, { type: "pii" }],
+  #                              transports: [{ type: "file", path: "web.log" }])
+  #   log.info("signed in", user: "alice", password: "hunter2")   # => true; the file has password "***"
+  #
+  # `transports` takes two kinds of entry. A Hash is a Rust transport (`{type: "console"}` or `{type: "file", path:}`,
+  # written on a background thread). An object that responds to `write(line, record)` is a Ruby transport: it is called
+  # on the caller's thread with the finished, already-redacted record. The constructor raises ConfigError for a config the
+  # core rejects; a log call never raises.
+  class Logger
+    attr_reader :name
+
+    def initialize(name: "app", level: :info, plugins: [], transports: [], content_policy: nil, tamper_evident: false,
+                   queue: nil, return_record: false)
+      rust, host = transports.partition { |transport| transport.is_a?(Hash) }
+      config = {
+        name: name, level: level.to_s, plugins: plugins, transports: rust, tamper_evident: tamper_evident,
+        queue: queue, content_policy: content_policy&.to_s
+      }.compact
+      error = Native.error_slot
+      handle = Native.lq_logger_new(JsonSafe.dump(config), error)
+      raise ConfigError, Native.error_from(error, "the logger could not be created") if handle.null?
+
+      adopt(handle, name, host, return_record)
+    end
+
+    # A logger named "<name>.<suffix>" with `fixed_meta` added to every record. It shares this logger's level and transports.
+    def child(suffix, **fixed_meta)
+      error = Native.error_slot
+      meta = fixed_meta.empty? ? nil : JsonSafe.dump(fixed_meta)
+      handle = Native.lq_logger_child(@handle, Native.c_text(suffix), meta, error)
+      raise Error, Native.error_from(error) if handle.null?
+
+      other = Logger.allocate
+      other.send(:adopt, handle, "#{@name}.#{suffix}", @host, @return_record)
+      other
+    end
+
+    LEVELS.each do |level|
+      # log.info("message", key: value, llm: { model: "..." })  => true when kept, false when filtered; the record when
+      # the logger was built with return_record: true.
+      define_method(level) { |message = "", llm: nil, **meta| log(level, message, meta, llm) }
+    end
+
+    # The method behind the level methods, for a level chosen at run time.
+    def log(level, message, meta = {}, llm = nil)
+      context = Logquill.current_context
+      merged = context.empty? ? meta : context.merge(meta.transform_keys(&:to_s))
+      want_record = @return_record || !@host.empty?
+      slot = want_record ? FFI::MemoryPointer.new(:pointer) : nil
+      error = Native.error_slot
+      code = Native.lq_log(
+        @handle, level.to_s, nil, Native.c_text(message), merged.empty? ? nil : Native.c_text(JsonSafe.dump(merged)),
+        llm.nil? ? nil : Native.c_text(JsonSafe.dump(llm)), slot, error
+      )
+      return false if code.zero?
+      return failed(Native.error_from(error)) if code.negative?
+
+      return true unless want_record
+
+      record = JSON.parse(Native.take(slot.read_pointer))
+      deliver(record)
+      @return_record ? record : true
+    rescue StandardError => e
+      failed(e.message)
+    end
+
+    # Changes the level for this logger, its parent and its children. Raises ArgumentError for a level that does not exist.
+    def set_level(level)
+      error = Native.error_slot
+      return self unless Native.lq_logger_set_level(@handle, level.to_s, error).negative?
+
+      raise ArgumentError, Native.error_from(error)
+    end
+    alias level= set_level
+
+    # Waits up to `timeout` seconds for queued records to be written (Rust transports), and flushes Ruby transports that
+    # can. true when everything was written in time.
+    def flush(timeout: 5.0)
+      @host.each { |transport| transport.flush if transport.respond_to?(:flush) }
+      Native.lq_logger_flush(@handle, (timeout * 1000).to_i) == 1
+    end
+
+    # Flushes, stops the background thread, and closes Ruby transports that respond to `close`. Call once, on shutdown.
+    def close(timeout: 5.0)
+      done = Native.lq_logger_close(@handle, (timeout * 1000).to_i) == 1
+      @host.each { |transport| transport.close if transport.respond_to?(:close) }
+      done
+    end
+
+    private
+
+    def adopt(handle, name, host, return_record)
+      @handle = FFI::AutoPointer.new(handle, Native.method(:lq_logger_free))
+      @name = name
+      @host = host
+      @return_record = return_record
+    end
+
+    def deliver(record)
+      return if @host.empty?
+
+      line = JSON.generate(record)
+      @host.each do |transport|
+        transport.write(line, record)
+      rescue StandardError => e
+        Kernel.warn("logquill: #{transport.class} failed to write a record: #{e.message}")
+      end
+    end
+
+    def failed(message)
+      Kernel.warn("logquill: #{message}")
+      false
+    end
+  end
+end

data/lib/logquill/native.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Logquill
+  # The C ABI of the Rust core (crates/logquill-ffi, include/logquill.h), loaded with the `ffi` gem. Nothing outside this
+  # file touches a pointer: the rest of the gem sees Ruby strings and raises Logquill::Error.
+  module Native
+    extend FFI::Library
+
+    LIBRARY = case RbConfig::CONFIG["host_os"]
+              when /darwin/ then "liblogquill_ffi.dylib"
+              when /mswin|mingw|cygwin/ then "logquill_ffi.dll"
+              else "liblogquill_ffi.so"
+              end
+
+    # Where the shared library is looked for, first match wins: the LOGQUILL_LIB environment variable (a path to the
+    # file), a copy shipped inside the gem (precompiled platform gems), then a build in this repository's target/ directory
+    # (development). Returns the path, or raises with every place it looked.
+    def self.library_path
+      tried = []
+      from_env = ENV.fetch("LOGQUILL_LIB", nil)
+      candidates = []
+      candidates << from_env if from_env && !from_env.empty?
+      candidates << File.expand_path("native/#{LIBRARY}", __dir__)
+      root = File.expand_path("../../../..", __dir__)
+      %w[release debug].each { |profile| candidates << File.join(root, "target", profile, LIBRARY) }
+      candidates.each do |path|
+        return path if File.file?(path)
+
+        tried << path
+      end
+      raise LoadError,
+            "logquill: could not find #{LIBRARY}. Looked in:\n  #{tried.join("\n  ")}\n" \
+            "Set LOGQUILL_LIB to the library's path, install a platform build of the gem, or run " \
+            "`cargo build -p logquill-ffi --release` in the repository."
+    end
+
+    ffi_lib library_path
+
+    attach_function :lq_version, [], :string
+    attach_function :lq_abi_version, [], :uint32
+    attach_function :lq_string_free, [:pointer], :void
+    attach_function :lq_call, %i[string string pointer], :pointer
+
+    attach_function :lq_chain_new, %i[string pointer], :pointer
+    attach_function :lq_chain_stamp, %i[pointer string pointer], :pointer
+    attach_function :lq_chain_head, %i[pointer pointer], :pointer
+    attach_function :lq_chain_sign_head, %i[pointer pointer size_t pointer], :pointer
+    attach_function :lq_chain_free, [:pointer], :void
+
+    attach_function :lq_logger_new, %i[string pointer], :pointer
+    attach_function :lq_logger_child, %i[pointer string string pointer], :pointer
+    attach_function :lq_log, %i[pointer string string string string string pointer pointer], :int32
+    attach_function :lq_logger_name, %i[pointer pointer], :pointer
+    attach_function :lq_logger_set_level, %i[pointer string pointer], :int32
+    attach_function :lq_logger_flush, %i[pointer uint32], :int32
+    attach_function :lq_logger_close, %i[pointer uint32], :int32
+    attach_function :lq_logger_free, [:pointer], :void
+
+    # The ABI version this gem was written against. A library with a different one has changed a function's meaning.
+    ABI_VERSION = 1
+
+    if lq_abi_version != ABI_VERSION
+      raise LoadError, "logquill: #{library_path} speaks C ABI #{lq_abi_version}, this gem needs #{ABI_VERSION}"
+    end
+
+    # A fresh out-parameter for `char **error`.
+    def self.error_slot
+      FFI::MemoryPointer.new(:pointer)
+    end
+
+    # Reads and frees an owned C string.
+    def self.take(pointer)
+      text = pointer.read_string.force_encoding(Encoding::UTF_8)
+      lq_string_free(pointer)
+      text
+    end
+
+    # The message a call left in `slot`, freed; a generic one if it left none.
+    def self.error_from(slot, fallback = "the call failed")
+      pointer = slot.read_pointer
+      pointer.null? ? fallback : take(pointer)
+    end
+
+    # A Ruby string as the UTF-8, NUL-free text a C string needs. Invalid bytes become U+FFFD and NUL becomes U+2400 rather
+    # than raising: a log call must not crash the caller over what it was asked to log.
+    def self.c_text(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text = text.dup.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
+      text = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\u{FFFD}")
+      text.include?("\0") ? text.tr("\0", "\u{2400}") : text
+    end
+  end
+end

data/lib/logquill/plugins.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Logquill
+  # Builders for the +plugins:+ option of Logquill::Logger: plugins that run in Rust, in order. A plugin is a plain hash with a
+  # +type+, so a hash written by hand works too; these only spell the options out and leave unset ones to the core's defaults.
+  module Plugins
+    module_function
+
+    # Masks the values of keys (case-insensitively, at every depth); +nil+ keys means password, token, secret, api_key and authorization.
+    def redact(keys: nil, classes: nil, replacement: nil)
+      build("redact", keys: keys, classes: classes, replacement: replacement)
+    end
+
+    # Masks emails, card numbers, phone numbers, SSNs and API keys inside any string of the record's meta.
+    def pii(replacement: nil)
+      build("pii", replacement: replacement)
+    end
+
+    # Keeps about +rate+ (0 to 1) of the records, chosen at random.
+    def sampling(rate:)
+      build("sampling", rate: rate)
+    end
+
+    # Drops records once more than +max_records+ share a key inside +per_seconds+; +key+ is "logger_level" (the default),
+    # "logger" or "message".
+    def rate_limit(max_records:, per_seconds:, key: nil)
+      build("rate_limit", max_records: max_records, per_seconds: per_seconds, key: key)
+    end
+
+    # Keeps errors and slow spans, samples the rest at a rate that follows demand, and caps the bytes written per window.
+    # An option left +nil+ keeps the core's default.
+    def adaptive_sampling(base_rate: nil, min_rate: nil, max_rate: nil, keep_at: nil, slow_ms: nil,
+                          max_bytes_per_second: nil, window_seconds: nil)
+      build("adaptive_sampling", base_rate: base_rate, min_rate: min_rate, max_rate: max_rate, keep_at: keep_at,
+                                 slow_ms: slow_ms, max_bytes_per_second: max_bytes_per_second, window_seconds: window_seconds)
+    end
+
+    def build(type, **options)
+      { type: type }.merge(options.compact)
+    end
+    private_class_method :build
+  end
+end

data/lib/logquill/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Logquill
+  # The gem's version. Lockstep with the crates and the other bindings (docs/rust-core-plan.md, section 7); a RubyGems
+  # pre-release is spelled "3.0.0.dev0" where Cargo and npm spell it "3.0.0-dev.0".
+  VERSION = "3.0.0.rc5"
+end

data/lib/logquill.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "logquill/version"
+require_relative "logquill/native"
+require_relative "logquill/json_safe"
+require_relative "logquill/helpers"
+require_relative "logquill/chain"
+require_relative "logquill/plugins"
+require_relative "logquill/logger"
+
+# LogQuill for Ruby: structured logging on the Rust core, through its C ABI. See README.md.
+module Logquill
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: logquill
+version: !ruby/object:Gem::Version
+  version: 3.0.0.rc5
+platform: x86_64-linux
+authors:
+- Nikhil Arora
+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.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: 'LogQuill for Ruby: the same record shape, redaction, sampling and tamper-evident
+  hash chain as the Python, Node, browser and other bindings, through a C ABI. Redaction
+  runs before anything is written.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/logquill.rb
+- lib/logquill/chain.rb
+- lib/logquill/helpers.rb
+- lib/logquill/json_safe.rb
+- lib/logquill/logger.rb
+- lib/logquill/native.rb
+- lib/logquill/native/liblogquill_ffi.so
+- lib/logquill/plugins.rb
+- lib/logquill/version.rb
+homepage: https://github.com/nikhilvdev/logquill
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/nikhilvdev/logquill
+  rubygems_mfa_required: 'true'
+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: 4.0.23
+specification_version: 4
+summary: Structured, agent-aware logging for Ruby, on a Rust core
+test_files: []