asherah 0.10.0-aarch64-linux-musl

data/lib/asherah.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "asherah/version"
+require_relative "asherah/error"
+require_relative "asherah/config"
+require_relative "asherah/native"
+require_relative "asherah/session_factory"
+require_relative "asherah/session"
+require_relative "asherah/hooks"
+
+module Asherah
+  DEFAULT_SESSION_CACHE_MAX_SIZE = 1000
+
+  @mutex = Mutex.new
+  @factory = nil
+  # @sessions is an LRU cache. Ruby Hash preserves insertion order, so we
+  # implement LRU by delete-and-reinsert on hit (moves the entry to the
+  # end), and `shift` on overflow (removes the oldest, i.e. least-recently
+  # used). Bounded by @session_cache_max_size, which honors the
+  # SessionCacheMaxSize config field — same default (1000) as the Rust
+  # core and the other bindings.
+  @sessions = {}
+  @initialized = false
+  @session_cache_enabled = true
+  @session_cache_max_size = DEFAULT_SESSION_CACHE_MAX_SIZE
+  @verbose = false
+
+  class << self
+    # Configure Asherah using a block with snake_case accessors.
+    # Compatible with the canonical godaddy/asherah-ruby gem API.
+    #
+    #   Asherah.configure do |config|
+    #     config.service_name = "MyService"
+    #     config.product_id = "MyProduct"
+    #     config.kms = "static"
+    #     config.metastore = "memory"
+    #   end
+    def configure
+      @mutex.synchronize do
+        raise Error::AlreadyInitialized if @initialized
+
+        config = Config.new
+        yield config
+        config.validate!
+
+        json = config.to_json
+        pointer = Native.asherah_factory_new_with_config(json)
+        @factory = SessionFactory.new(pointer)
+        @sessions = {}
+        @initialized = true
+        @session_cache_enabled = config.enable_session_caching != false
+        @session_cache_max_size = positive_int(config.session_cache_max_size) || DEFAULT_SESSION_CACHE_MAX_SIZE
+        @verbose = config.verbose == true
+      end
+    end
+
+    # Initialize Asherah with a PascalCase config hash.
+    # Also accepts snake_case string/symbol keys (auto-normalized).
+    def setup(config)
+      normalized = normalize_config(config)
+      json = JSON.generate(normalized)
+
+      pointer = Native.asherah_factory_new_with_config(json)
+      factory = SessionFactory.new(pointer)
+
+      @mutex.synchronize do
+        raise Error::AlreadyInitialized if @initialized
+
+        @factory = factory
+        @sessions = {}
+        @initialized = true
+        @session_cache_enabled = truthy(normalized["EnableSessionCaching"], default: true)
+        @session_cache_max_size = positive_int(normalized["SessionCacheMaxSize"]) || DEFAULT_SESSION_CACHE_MAX_SIZE
+        @verbose = truthy(normalized["Verbose"], default: false)
+      end
+
+      nil
+    rescue StandardError
+      factory&.close if defined?(factory) && factory
+      raise
+    end
+
+    # Run setup in a background Thread. Yields the result to +block+ on
+    # success. Exceptions raised by setup propagate via the Thread's
+    # joined error — the previous implementation called the block with
+    # the result on success but silently dropped the Thread's error
+    # state on failure, leaving callers unable to distinguish completion
+    # from an unsetup factory. The Thread aborts on exception
+    # (`Thread.report_on_exception = true`), so a stack trace lands on
+    # stderr; callers that need programmatic access should
+    # `thread.join` to re-raise. T-finding "setup_async/shutdown_async/
+    # encrypt_async/decrypt_async swallow Thread exceptions" in
+    # `docs/review-2026-05-05-findings.md`.
+    def setup_async(config, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = setup(config)
+        block&.call(result)
+        result
+      end
+    end
+
+    def shutdown
+      factory = nil
+      sessions = nil
+      @mutex.synchronize do
+        raise Error::NotInitialized unless @initialized
+
+        factory = @factory
+        sessions = @sessions.values
+        @factory = nil
+        @sessions = {}
+        @initialized = false
+      end
+
+      Array(sessions).each do |session|
+        begin
+          session.close unless session.closed?
+        rescue StandardError => e
+          warn "asherah: error closing session during shutdown: #{e.message}"
+        end
+      end
+      factory&.close unless factory&.closed?
+      nil
+    end
+
+    # Run shutdown in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def shutdown_async(&block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = shutdown
+        block&.call(result)
+        result
+      end
+    end
+
+    def get_setup_status
+      @mutex.synchronize { @initialized }
+    end
+
+    def setenv(env = {})
+      data = case env
+             when String
+               JSON.parse(env)
+             else
+               env
+             end
+      unless data.respond_to?(:each_pair)
+        raise ArgumentError, "environment payload must be a Hash or JSON object"
+      end
+      data.each_pair do |k, v|
+        if v.nil?
+          ENV.delete(String(k))
+        else
+          ENV[String(k)] = v.to_s
+        end
+      end
+      nil
+    end
+    alias_method :set_env, :setenv
+
+    def encrypt(partition_id, payload)
+      raise ArgumentError, "payload cannot be nil" if payload.nil?
+      session = resolve_session(partition_id)
+      session.encrypt_bytes(payload)
+    end
+
+    def encrypt_string(partition_id, text)
+      raise ArgumentError, "text cannot be nil" if text.nil?
+      encrypt(partition_id, text)
+    end
+
+    def decrypt(partition_id, data_row_record)
+      raise ArgumentError, "data_row_record cannot be nil" if data_row_record.nil?
+      session = resolve_session(partition_id)
+      session.decrypt_bytes(data_row_record).force_encoding(Encoding::UTF_8)
+    end
+
+    def decrypt_string(partition_id, data_row_record)
+      raise ArgumentError, "data_row_record cannot be nil" if data_row_record.nil?
+      decrypt(partition_id, data_row_record).force_encoding(Encoding::UTF_8)
+    end
+
+    # Run encrypt in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def encrypt_async(partition_id, payload, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = encrypt(partition_id, payload)
+        block&.call(result)
+        result
+      end
+    end
+
+    # Run decrypt in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def decrypt_async(partition_id, data_row_record, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = decrypt(partition_id, data_row_record)
+        block&.call(result)
+        result
+      end
+    end
+
+    # Install a log hook. Yields a +Hash+ +{level:, target:, message:}+ for
+    # every log record emitted by the underlying Rust crates. The block may
+    # fire from any thread; implementations must be thread-safe and
+    # non-blocking. Pass +nil+ to clear (equivalent to {clear_log_hook}).
+    #
+    # Replaces any previously installed log hook. Exceptions raised from the
+    # callback are caught and silently swallowed.
+    def set_log_hook(callback = nil, &block)
+      Hooks.set_log_hook(callback, &block)
+    end
+
+    # Remove the active log hook, if any. Idempotent.
+    def clear_log_hook
+      Hooks.clear_log_hook
+    end
+
+    # Install a metrics hook. Yields a +Hash+ +{type:, duration_ns:, name:}+
+    # for every metrics event. Timing events ({:encrypt, :decrypt, :store,
+    # :load}) carry a positive +duration_ns+ and a +nil+ +name+; cache events
+    # ({:cache_hit, :cache_miss, :cache_stale}) carry +duration_ns+ == 0 and
+    # the cache identifier in +name+.
+    #
+    # Installing a hook implicitly enables the global metrics gate; clearing
+    # it disables the gate. Replaces any previously installed metrics hook.
+    # Pass +nil+ to clear (equivalent to {clear_metrics_hook}).
+    def set_metrics_hook(callback = nil, &block)
+      Hooks.set_metrics_hook(callback, &block)
+    end
+
+    # Remove the active metrics hook and disable metrics. Idempotent.
+    def clear_metrics_hook
+      Hooks.clear_metrics_hook
+    end
+
+    private
+
+    REQUIRED_KEYS = %w[ServiceName ProductID Metastore].freeze
+
+    def normalize_config(config)
+      unless config.respond_to?(:each_pair)
+        raise ArgumentError, "config must be a Hash-like object"
+      end
+      normalized = {}
+      config.each_pair do |key, value|
+        normalized[String(key)] = value
+      end
+      REQUIRED_KEYS.each do |key|
+        raise ArgumentError, "#{key} is required" if normalized[key].nil? || normalized[key].to_s.strip.empty?
+      end
+      normalized
+    end
+
+    def truthy(value, default: false)
+      return default if value.nil?
+
+      case value
+      when true, "1", "true", "TRUE", "yes", "on" then true
+      when false, "0", "false", "FALSE", "no", "off" then false
+      else
+        default
+      end
+    end
+
+    def resolve_session(partition_id)
+      raise ArgumentError, "partition_id cannot be empty" if String(partition_id).empty?
+
+      evicted = nil
+      session = @mutex.synchronize do
+        raise Error::NotInitialized unless @initialized
+
+        unless @session_cache_enabled
+          break @factory.get_session(partition_id)
+        end
+
+        # LRU: on hit, delete + reinsert to move the entry to the
+        # most-recently-used end of the Hash (Ruby Hash is insertion-
+        # ordered). On miss + overflow, `shift` removes the oldest entry,
+        # which is the least-recently-used.
+        if (existing = @sessions.delete(partition_id))
+          @sessions[partition_id] = existing
+          break existing
+        end
+
+        fresh = @factory.get_session(partition_id)
+        @sessions[partition_id] = fresh
+        if @sessions.size > @session_cache_max_size
+          _, evicted = @sessions.shift
+        end
+        fresh
+      end
+
+      # Close evicted session outside the lock — close hits the FFI and
+      # we don't want to serialize all encrypts behind one eviction.
+      if evicted
+        begin
+          evicted.close unless evicted.closed?
+        rescue StandardError => e
+          warn "asherah: error closing evicted session: #{e.message}"
+        end
+      end
+
+      session
+    end
+
+    def positive_int(value)
+      return nil if value.nil?
+      n = Integer(value)
+      n.positive? ? n : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: asherah
+version: !ruby/object:Gem::Version
+  version: 0.10.0
+platform: aarch64-linux-musl
+authors:
+- Jay Gowdy
+- Bo Thompson
+- Michael Micco
+- Dalibor Nasevic
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-05 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'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Asherah application-layer encryption for Ruby with automatic key rotation,
+  powered by the native Rust implementation.
+email: oss@godaddy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/asherah.rb
+- lib/asherah/config.rb
+- lib/asherah/error.rb
+- lib/asherah/hooks.rb
+- lib/asherah/native.rb
+- lib/asherah/native/libasherah_ffi.so
+- lib/asherah/session.rb
+- lib/asherah/session_factory.rb
+- lib/asherah/version.rb
+homepage: https://github.com/godaddy/asherah-ffi
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/godaddy/asherah-ffi
+  source_code_uri: https://github.com/godaddy/asherah-ffi
+  github_repo: https://github.com/godaddy/asherah-ffi
+  changelog_uri: https://github.com/godaddy/asherah-ffi/releases
+  bug_tracker_uri: https://github.com/godaddy/asherah-ffi/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Asherah application-layer encryption for Ruby with automatic key rotation.
+test_files: []