asherah 0.9.1 → 0.10.0

data/lib/asherah/session.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "native"
+
+module Asherah
+  class Session
+    # Maximum wall time the async API will wait for the FFI callback to
+    # deliver a result before giving up. Without this bound, a hung tokio
+    # worker (or any callback-delivery race) would block the calling Ruby
+    # thread until the process exits — observed as 6-hour CI hangs on the
+    # round-trip tests. Override via ASHERAH_RUBY_ASYNC_TIMEOUT (seconds).
+    DEFAULT_ASYNC_TIMEOUT_SECONDS = 30
+
+    # Maximum time {#close} will wait for in-flight async operations to
+    # drain before forcibly freeing the session. Independent of the
+    # per-call async timeout above.
+    DEFAULT_CLOSE_DRAIN_SECONDS = 5
+
+    def self.async_timeout_seconds
+      val = ENV["ASHERAH_RUBY_ASYNC_TIMEOUT"]
+      return DEFAULT_ASYNC_TIMEOUT_SECONDS if val.nil? || val.empty?
+      Float(val)
+    rescue ArgumentError, TypeError
+      DEFAULT_ASYNC_TIMEOUT_SECONDS
+    end
+
+    def initialize(pointer)
+      raise Asherah::Error::GetSessionFailed, Native.last_error if pointer.null?
+      @pointer = pointer
+      @close_mu = Mutex.new
+      @pending_ops = 0
+    end
+
+    def encrypt_bytes(data)
+      raise ArgumentError, "data cannot be nil" if data.nil?
+      raise Asherah::Error::EncryptFailed, "session closed" if @pointer.null?
+      buf = thread_local_buffer
+      status = Native.asherah_encrypt_to_json(@pointer, data, data.bytesize, buf.pointer)
+      raise Asherah::Error::EncryptFailed, Native.last_error unless status.zero?
+      # `begin/ensure` so the FFI buffer is always freed (and its
+      # plaintext bytes wiped via `asherah_buffer_free`'s zeroize) even
+      # if `read_bytes` throws — without this the thread-local buffer
+      # would leak the previous call's plaintext until the next
+      # successful encrypt/decrypt on the same thread.
+      begin
+        buf[:data].read_bytes(buf[:len])
+      ensure
+        Native.asherah_buffer_free(buf.pointer)
+      end
+    end
+
+    def decrypt_bytes(json)
+      raise ArgumentError, "json cannot be nil" if json.nil?
+      raise Asherah::Error::DecryptFailed, "session closed" if @pointer.null?
+      buf = thread_local_buffer
+      status = Native.asherah_decrypt_from_json(@pointer, json, json.bytesize, buf.pointer)
+      raise Asherah::Error::DecryptFailed, Native.last_error unless status.zero?
+      # See encrypt_bytes — `ensure` guarantees the wipe runs even if
+      # the read_bytes call somehow raises.
+      begin
+        buf[:data].read_bytes(buf[:len])
+      ensure
+        Native.asherah_buffer_free(buf.pointer)
+      end
+    end
+
+    # True async encrypt — runs on Rust's tokio runtime, does not block the Ruby thread.
+    # Returns the result; internally uses a Queue to wait for the tokio callback.
+    def encrypt_bytes_async(data)
+      raise ArgumentError, "data cannot be nil" if data.nil?
+      raise Asherah::Error::EncryptFailed, "session closed" if @pointer.null?
+      @close_mu.synchronize { @pending_ops += 1 }
+      queue = Queue.new
+      session = self
+      callback = FFI::Function.new(:void, [:pointer, :pointer, :size_t, :string]) do |_ud, result_ptr, result_len, error|
+        begin
+          if error
+            queue.push(Asherah::Error::EncryptFailed.new(error))
+          else
+            queue.push(result_ptr.read_bytes(result_len))
+          end
+        ensure
+          session.send(:decrement_pending_ops)
+        end
+      end
+      status = Native.asherah_encrypt_to_json_async(@pointer, data, data.bytesize, callback, nil)
+      unless status.zero?
+        @close_mu.synchronize { @pending_ops -= 1 }
+        raise Asherah::Error::EncryptFailed, Native.last_error
+      end
+      # Bound the wait so a wedged callback can't block the calling
+      # thread forever. We use Timeout.timeout (not Queue#pop(timeout:),
+      # which only landed in Ruby 3.2) so the lib remains usable on the
+      # 3.0/3.1 Ruby builds still in some CI/test images.
+      result = await_async_result(queue, "encrypt_bytes_async")
+      raise result if result.is_a?(Exception)
+      result
+    end
+
+    # True async decrypt — runs on Rust's tokio runtime, does not block the Ruby thread.
+    def decrypt_bytes_async(json)
+      raise ArgumentError, "json cannot be nil" if json.nil?
+      raise Asherah::Error::DecryptFailed, "session closed" if @pointer.null?
+      @close_mu.synchronize { @pending_ops += 1 }
+      queue = Queue.new
+      session = self
+      callback = FFI::Function.new(:void, [:pointer, :pointer, :size_t, :string]) do |_ud, result_ptr, result_len, error|
+        begin
+          if error
+            queue.push(Asherah::Error::DecryptFailed.new(error))
+          else
+            queue.push(result_ptr.read_bytes(result_len))
+          end
+        ensure
+          session.send(:decrement_pending_ops)
+        end
+      end
+      status = Native.asherah_decrypt_from_json_async(@pointer, json, json.bytesize, callback, nil)
+      unless status.zero?
+        @close_mu.synchronize { @pending_ops -= 1 }
+        raise Asherah::Error::DecryptFailed, Native.last_error
+      end
+      result = await_async_result(queue, "decrypt_bytes_async")
+      raise result if result.is_a?(Exception)
+      result
+    end
+
+    def close
+      ptr = @close_mu.synchronize do
+        return if @pointer.null?
+        # Wait for in-flight async operations before freeing, but bound
+        # the wait — a wedged callback used to make this spin forever
+        # (and silently wedge any process trying to shut down cleanly).
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + DEFAULT_CLOSE_DRAIN_SECONDS
+        while @pending_ops > 0 && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          sleep 0.001
+        end
+        if @pending_ops > 0
+          warn "asherah: closing session with #{@pending_ops} async operation(s) " \
+               "still in flight after #{DEFAULT_CLOSE_DRAIN_SECONDS}s drain"
+        end
+        p = @pointer
+        @pointer = FFI::Pointer::NULL
+        p
+      end
+      Native.asherah_session_free(ptr)
+    end
+
+    def closed?
+      @pointer.null?
+    end
+
+    private
+
+    # Wait up to {Session.async_timeout_seconds} for the FFI callback
+    # to push a result onto +queue+. On expiry, raise
+    # {Asherah::Error::Timeout}; the late callback (if it eventually
+    # fires) still decrements the pending-op counter via its `ensure`
+    # block, so close() can drain cleanly.
+    def await_async_result(queue, label)
+      ::Timeout.timeout(Session.async_timeout_seconds) { queue.pop }
+    rescue ::Timeout::Error
+      raise Asherah::Error::Timeout,
+            "#{label} timed out after #{Session.async_timeout_seconds}s"
+    end
+
+    def decrement_pending_ops
+      @close_mu.synchronize { @pending_ops -= 1 }
+    end
+
+    def thread_local_buffer
+      Thread.current[:asherah_buffer] ||= Native::AsherahBuffer.new
+    end
+  end
+end

data/lib/asherah/session_factory.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "native"
+require_relative "session"
+
+module Asherah
+  class SessionFactory
+    def initialize(pointer)
+      raise Asherah::Error::BadConfig, Native.last_error if pointer.null?
+      @pointer = pointer
+      @close_mu = Mutex.new
+    end
+
+    def get_session(partition_id)
+      raise Asherah::Error::NotInitialized, "factory closed" if @pointer.null?
+      id = String(partition_id)
+      raise ArgumentError, "partition_id cannot be empty" if id.empty?
+      Session.new(Native.asherah_factory_get_session(@pointer, id))
+    end
+
+    def close
+      ptr = @close_mu.synchronize do
+        return if @pointer.null?
+        p = @pointer
+        @pointer = FFI::Pointer::NULL
+        p
+      end
+      Native.asherah_factory_free(ptr)
+    end
+
+    def closed?
+      @pointer.null?
+    end
+  end
+end

data/lib/asherah/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asherah
-  VERSION = '0.9.1'
+  VERSION = "0.10.0"
 end

data/lib/asherah.rb

@@ -1,135 +1,321 @@
 # frozen_string_literal: true
 
-require_relative 'asherah/version'
-require 'asherah/config'
-require 'asherah/error'
-require 'cobhan'
+require "json"
 
-# Asherah is a Ruby wrapper around Asherah Go application-layer encryption SDK.
-module Asherah
-  extend Cobhan
+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"
 
-  LIB_ROOT_PATH = File.expand_path('asherah/native', __dir__)
-  load_library(LIB_ROOT_PATH, 'libasherah', [
-    [:SetEnv, [:pointer], :int32],
-    [:SetupJson, [:pointer], :int32],
-    [:EncryptToJson, [:pointer, :pointer, :pointer], :int32],
-    [:DecryptFromJson, [:pointer, :pointer, :pointer], :int32],
-    [:Shutdown, [], :void]
-  ].freeze)
+module Asherah
+  DEFAULT_SESSION_CACHE_MAX_SIZE = 1000
 
-  ESTIMATED_ENCRYPTION_OVERHEAD = 48
-  ESTIMATED_ENVELOPE_OVERHEAD = 185
-  BASE64_OVERHEAD = 1.34
+  @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
-    # Set environment variables needed by Asherah dependencies for when
-    # Go os.Getenv() doesn't see variables set by C.setenv().
-    # References:
-    #   https://github.com/golang/go/wiki/cgo#environmental-variables
-    #   https://github.com/golang/go/issues/44108
+    # Configure Asherah using a block with snake_case accessors.
+    # Compatible with the canonical godaddy/asherah-ruby gem API.
     #
-    # @yield [Config]
-    # @param env [Hash], Key-value pairs to set Asherah ENV
-    # @return [void]
-    def set_env(env = {})
-      env_buffer = string_to_cbuffer(env.to_json)
+    #   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
 
-      result = SetEnv(env_buffer)
-      Error.check_result!(result, 'SetEnv failed')
-    ensure
-      env_buffer&.free
+        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
 
-    # Configures Asherah
-    #
-    # @yield [Config]
-    # @return [void]
-    def configure
-      raise Asherah::Error::AlreadyInitialized if @initialized
+    # 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)
 
-      config = Config.new
-      yield config
-      config.validate!
-      @intermediated_key_overhead_bytesize = config.product_id.bytesize + config.service_name.bytesize
+      pointer = Native.asherah_factory_new_with_config(json)
+      factory = SessionFactory.new(pointer)
 
-      config_buffer = string_to_cbuffer(config.to_json)
+      @mutex.synchronize do
+        raise Error::AlreadyInitialized if @initialized
 
-      result = SetupJson(config_buffer)
-      Error.check_result!(result, 'SetupJson failed')
-      @initialized = true
-    ensure
-      config_buffer&.free
+        @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
 
-    # Encrypts data for a given partition_id and returns DataRowRecord in JSON format.
-    #
-    # DataRowRecord contains the encrypted key and data, as well as the information
-    # required to decrypt the key encryption key. This object data should be stored
-    # in your data persistence as it's required to decrypt data.
-    #
-    # EnvelopeKeyRecord represents an encrypted key and is the data structure used
-    # to persist the key in the key table. It also contains the meta data
-    # of the key used to encrypt it.
-    #
-    # KeyMeta contains the `id` and `created` timestamp for an encryption key.
-    #
-    # @param partition_id [String]
-    # @param data [String]
-    # @return [String], DataRowRecord in JSON format
-    def encrypt(partition_id, data)
-      raise Asherah::Error::NotInitialized unless @initialized
+    # 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
 
-      partition_id_buffer = string_to_cbuffer(partition_id)
-      data_buffer = string_to_cbuffer(data)
-      estimated_buffer_bytesize = estimate_buffer(data.bytesize, partition_id.bytesize)
-      output_buffer = allocate_cbuffer(estimated_buffer_bytesize)
+    def shutdown
+      factory = nil
+      sessions = nil
+      @mutex.synchronize do
+        raise Error::NotInitialized unless @initialized
 
-      result = EncryptToJson(partition_id_buffer, data_buffer, output_buffer)
-      Error.check_result!(result, 'EncryptToJson failed')
+        factory = @factory
+        sessions = @sessions.values
+        @factory = nil
+        @sessions = {}
+        @initialized = false
+      end
 
-      cbuffer_to_string(output_buffer)
-    ensure
-      [partition_id_buffer, data_buffer, output_buffer].compact.each(&:free)
+      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
 
-    # Decrypts a DataRowRecord in JSON format for a partition_id and returns decrypted data.
-    #
-    # @param partition_id [String]
-    # @param json [String], DataRowRecord in JSON format
-    # @return [String], Decrypted data
-    def decrypt(partition_id, json)
-      raise Asherah::Error::NotInitialized unless @initialized
+    # 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
 
-      partition_id_buffer = string_to_cbuffer(partition_id)
-      data_buffer = string_to_cbuffer(json)
-      output_buffer = allocate_cbuffer(json.bytesize)
+    def get_setup_status
+      @mutex.synchronize { @initialized }
+    end
 
-      result = DecryptFromJson(partition_id_buffer, data_buffer, output_buffer)
-      Error.check_result!(result, 'DecryptFromJson failed')
+    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
 
-      cbuffer_to_string(output_buffer)
-    ensure
-      [partition_id_buffer, data_buffer, output_buffer].compact.each(&:free)
+    def encrypt(partition_id, payload)
+      raise ArgumentError, "payload cannot be nil" if payload.nil?
+      session = resolve_session(partition_id)
+      session.encrypt_bytes(payload)
     end
 
-    # Stop the Asherah instance
-    def shutdown
-      raise Asherah::Error::NotInitialized unless @initialized
+    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
 
-      Shutdown()
-      @initialized = false
+    # 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
 
-    def estimate_buffer(data_bytesize, partition_bytesize)
-      est_data_len = (((data_bytesize + ESTIMATED_ENCRYPTION_OVERHEAD) * BASE64_OVERHEAD).to_i + 1)
+    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
 
-      ESTIMATED_ENVELOPE_OVERHEAD +
-        @intermediated_key_overhead_bytesize +
-        partition_bytesize +
-        est_data_len
+    def positive_int(value)
+      return nil if value.nil?
+      n = Integer(value)
+      n.positive? ? n : nil
+    rescue ArgumentError, TypeError
+      nil
     end
   end
 end