asherah 0.9.1 → 0.10.0

data/lib/asherah/config.rb

@@ -1,28 +1,19 @@
 # frozen_string_literal: true
 
-require 'json'
+require "json"
 
 module Asherah
-  # @attr [String] service_name, The name of this service
-  # @attr [String] product_id, The name of the product that owns this service
-  # @attr [String] kms, The master key management service (static or aws)
-  # @attr [String] metastore, The type of metastore for persisting keys (rdbms, dynamodb, memory)
-  # @attr [String] connection_string, The database connection string (required when metastore is rdbms)
-  # @attr [String] replica_read_consistency, For Aurora sessions using write forwarding (eventual, global, session)
-  # @attr [String] sql_metastore_db_type, Which SQL driver to use (mysql, postgres, oracle), defaults to mysql
-  # @attr [String] dynamo_db_endpoint, An optional endpoint URL (for dynamodb metastore)
-  # @attr [String] dynamo_db_region, The AWS region for DynamoDB requests (for dynamodb metastore)
-  # @attr [String] dynamo_db_table_name, The table name for DynamoDB (for dynamodb metastore)
-  # @attr [Boolean] enable_region_suffix, Configure the metastore to use regional suffixes (for dynamodb metastore)
-  # @attr [String] region_map, List of key-value pairs in the form of REGION1=ARN1[,REGION2=ARN2] (required for aws kms)
-  # @attr [String] preferred_region, The preferred AWS region (required for aws kms)
-  # @attr [Integer] session_cache_max_size, The maximum number of sessions to cache
-  # @attr [Integer] session_cache_duration, The amount of time in seconds a session will remain cached
-  # @attr [Integer] expire_after, The amount of time in seconds a key is considered valid
-  # @attr [Integer] check_interval, The amount of time in seconds before cached keys are considered stale
-  # @attr [Boolean] enable_session_caching, Enable shared session caching
-  # @attr [Boolean] disable_zero_copy, Disable zero-copy FFI input buffers to prevent use-after-free from caller runtime
-  # @attr [Boolean] verbose, Enable verbose logging output
+  # Configuration class compatible with the canonical godaddy/asherah-ruby gem.
+  # Provides snake_case attr_accessors that map to PascalCase config keys
+  # expected by the Rust FFI layer.
+  #
+  # Usage:
+  #   Asherah.configure do |config|
+  #     config.service_name = "MyService"
+  #     config.product_id = "MyProduct"
+  #     config.kms = "static"
+  #     config.metastore = "memory"
+  #   end
   class Config
     MAPPING = {
       service_name: :ServiceName,
@@ -34,83 +25,82 @@ module Asherah
       sql_metastore_db_type: :SQLMetastoreDBType,
       dynamo_db_endpoint: :DynamoDBEndpoint,
       dynamo_db_region: :DynamoDBRegion,
+      dynamo_db_signing_region: :DynamoDBSigningRegion,
       dynamo_db_table_name: :DynamoDBTableName,
       enable_region_suffix: :EnableRegionSuffix,
       region_map: :RegionMap,
       preferred_region: :PreferredRegion,
+      aws_profile_name: :AwsProfileName,
       session_cache_max_size: :SessionCacheMaxSize,
       session_cache_duration: :SessionCacheDuration,
       enable_session_caching: :EnableSessionCaching,
       disable_zero_copy: :DisableZeroCopy,
       expire_after: :ExpireAfter,
       check_interval: :CheckInterval,
-      verbose: :Verbose
+      verbose: :Verbose,
+      # Connection pool
+      pool_max_open: :PoolMaxOpen,
+      pool_max_idle: :PoolMaxIdle,
+      pool_max_lifetime: :PoolMaxLifetime,
+      pool_max_idle_time: :PoolMaxIdleTime,
+      # KMS: AWS
+      kms_key_id: :KmsKeyId,
+      # KMS: AWS Secrets Manager
+      secrets_manager_secret_id: :SecretsManagerSecretId,
+      # KMS: HashiCorp Vault Transit
+      vault_addr: :VaultAddr,
+      vault_token: :VaultToken,
+      vault_auth_method: :VaultAuthMethod,
+      vault_auth_role: :VaultAuthRole,
+      vault_auth_mount: :VaultAuthMount,
+      vault_approle_role_id: :VaultApproleRoleId,
+      vault_approle_secret_id: :VaultApproleSecretId,
+      vault_client_cert: :VaultClientCert,
+      vault_client_key: :VaultClientKey,
+      vault_k8s_token_path: :VaultK8sTokenPath,
+      vault_transit_key: :VaultTransitKey,
+      vault_transit_mount: :VaultTransitMount,
     }.freeze
 
-    KMS_TYPES = ['static', 'aws', 'test-debug-static'].freeze
-    METASTORE_TYPES = ['rdbms', 'dynamodb', 'memory', 'test-debug-memory'].freeze
-    SQL_METASTORE_DB_TYPES = ['mysql', 'postgres', 'oracle'].freeze
+    KMS_TYPES = ["static", "aws", "vault", "vault-transit", "secrets-manager", "test-debug-static"].freeze
+    METASTORE_TYPES = ["rdbms", "dynamodb", "memory", "test-debug-memory"].freeze
+    SQL_METASTORE_DB_TYPES = ["mysql", "postgres", "oracle"].freeze
 
     attr_accessor(*MAPPING.keys)
 
     def validate!
-      validate_service_name
-      validate_product_id
-      validate_kms
-      validate_metastore
-      validate_sql_metastore_db_type
-      validate_kms_attributes
-    end
-
-    def to_json(*args)
-      config = {}.tap do |c|
-        MAPPING.each_pair do |our_key, their_key|
-          value = public_send(our_key)
-          c[their_key] = value unless value.nil?
-        end
-      end
-
-      JSON.generate(config, *args)
-    end
-
-    private
-
-    def validate_service_name
-      raise Error::ConfigError, 'config.service_name not set' if service_name.nil?
-    end
-
-    def validate_product_id
-      raise Error::ConfigError, 'config.product_id not set' if product_id.nil?
-    end
-
-    def validate_kms
-      raise Error::ConfigError, 'config.kms not set' if kms.nil?
+      raise Error::ConfigError, "config.service_name not set" if service_name.nil?
+      raise Error::ConfigError, "config.product_id not set" if product_id.nil?
+      raise Error::ConfigError, "config.kms not set" if kms.nil?
       unless KMS_TYPES.include?(kms)
-        raise Error::ConfigError, "config.kms must be one of these: #{KMS_TYPES.join(', ')}"
+        raise Error::ConfigError, "config.kms must be one of these: #{KMS_TYPES.join(", ")}"
       end
-    end
-
-    def validate_metastore
-      raise Error::ConfigError, 'config.metastore not set' if metastore.nil?
+      raise Error::ConfigError, "config.metastore not set" if metastore.nil?
       unless METASTORE_TYPES.include?(metastore)
-        raise Error::ConfigError, "config.metastore must be one of these: #{METASTORE_TYPES.join(', ')}"
+        raise Error::ConfigError, "config.metastore must be one of these: #{METASTORE_TYPES.join(", ")}"
+      end
+      if sql_metastore_db_type && !SQL_METASTORE_DB_TYPES.include?(sql_metastore_db_type)
+        raise Error::ConfigError, "config.sql_metastore_db_type must be one of these: #{SQL_METASTORE_DB_TYPES.join(", ")}"
+      end
+      if kms == "aws"
+        raise Error::ConfigError, "config.region_map not set" if region_map.nil?
+        raise Error::ConfigError, "config.region_map must be a Hash" unless region_map.is_a?(Hash)
+        raise Error::ConfigError, "config.preferred_region not set" if preferred_region.nil?
       end
     end
 
-    def validate_sql_metastore_db_type
-      return if sql_metastore_db_type.nil?
-
-      unless SQL_METASTORE_DB_TYPES.include?(sql_metastore_db_type)
-        raise Error::ConfigError,
-              "config.sql_metastore_db_type must be one of these: #{SQL_METASTORE_DB_TYPES.join(', ')}"
-      end
+    def to_json(*args)
+      JSON.generate(to_h, *args)
     end
 
-    def validate_kms_attributes
-      return unless kms == 'aws'
-      raise Error::ConfigError, 'config.region_map not set' if region_map.nil?
-      raise Error::ConfigError, 'config.region_map must be a Hash' unless region_map.is_a?(Hash)
-      raise Error::ConfigError, 'config.preferred_region not set' if preferred_region.nil?
+    # Convert to the PascalCase Hash expected by Asherah.setup
+    def to_h
+      hash = {}
+      MAPPING.each_pair do |attr, key|
+        value = public_send(attr)
+        hash[key] = value unless value.nil?
+      end
+      hash
     end
   end
 end

data/lib/asherah/error.rb

@@ -1,30 +1,16 @@
 # frozen_string_literal: true
 
 module Asherah
-  # Asherah Error converts the error code to error message
-  module Error
-    ConfigError = Class.new(StandardError)
-    NotInitialized = Class.new(StandardError)
-    AlreadyInitialized = Class.new(StandardError)
-    GetSessionFailed = Class.new(StandardError)
-    EncryptFailed = Class.new(StandardError)
-    DecryptFailed = Class.new(StandardError)
-    BadConfig = Class.new(StandardError)
-
-    CODES = {
-      -100 => NotInitialized,
-      -101 => AlreadyInitialized,
-      -102 => GetSessionFailed,
-      -103 => EncryptFailed,
-      -104 => DecryptFailed,
-      -105 => BadConfig
-    }.freeze
-
-    def self.check_result!(result, message)
-      return unless result.negative?
-
-      error_class = Error::CODES.fetch(result, StandardError)
-      raise error_class, "#{message} (#{result})"
-    end
+  # Base error class. Also serves as a namespace for specific error types
+  # compatible with the canonical godaddy/asherah-ruby gem.
+  class Error < StandardError
+    ConfigError = Class.new(self)
+    NotInitialized = Class.new(self)
+    AlreadyInitialized = Class.new(self)
+    GetSessionFailed = Class.new(self)
+    EncryptFailed = Class.new(self)
+    DecryptFailed = Class.new(self)
+    BadConfig = Class.new(self)
+    Timeout = Class.new(self)
   end
 end

data/lib/asherah/hooks.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "native"
+
+module Asherah
+  # Log + metrics observability hooks.
+  #
+  # The C ABI accepts a single function pointer per hook. We marshal each
+  # invocation into a Ruby Hash with symbol keys and yield it to the
+  # user-provided +Proc+. Exceptions raised by the user's callback are caught
+  # and silently swallowed — propagating an exception across the FFI boundary
+  # would be undefined behavior (and since Rust 1.81 aborts the process).
+  #
+  # The user's callback may fire from any thread (Rust tokio worker threads,
+  # database driver threads). Implementations must be thread-safe and should
+  # not block; expensive forwarding (e.g. to a logging framework) should be
+  # done by enqueueing work onto a background thread you own.
+  module Hooks
+    # Map C ABI integer log level → +Logger::Severity+ constant. The Rust
+    # +log+ crate has a TRACE level that stdlib +Logger+ does not; it is
+    # surfaced as +Logger::DEBUG+ so the value is still meaningful when the
+    # caller dispatches via +Logger#add+.
+    LOG_LEVEL_TO_SEVERITY = {
+      Native::LOG_TRACE => Logger::DEBUG,
+      Native::LOG_DEBUG => Logger::DEBUG,
+      Native::LOG_INFO  => Logger::INFO,
+      Native::LOG_WARN  => Logger::WARN,
+      Native::LOG_ERROR => Logger::ERROR
+    }.freeze
+    private_constant :LOG_LEVEL_TO_SEVERITY
+
+    # Map +Logger::Severity+ → lowercase symbol for ergonomic dispatch on
+    # the raw block API.
+    SEVERITY_TO_SYMBOL = {
+      Logger::DEBUG => :debug,
+      Logger::INFO  => :info,
+      Logger::WARN  => :warn,
+      Logger::ERROR => :error,
+      Logger::FATAL => :fatal,
+      Logger::UNKNOWN => :unknown
+    }.freeze
+    private_constant :SEVERITY_TO_SYMBOL
+
+    METRIC_TYPE_NAMES = {
+      Native::METRIC_ENCRYPT     => :encrypt,
+      Native::METRIC_DECRYPT     => :decrypt,
+      Native::METRIC_STORE       => :store,
+      Native::METRIC_LOAD        => :load,
+      Native::METRIC_CACHE_HIT   => :cache_hit,
+      Native::METRIC_CACHE_MISS  => :cache_miss,
+      Native::METRIC_CACHE_STALE => :cache_stale
+    }.freeze
+    private_constant :METRIC_TYPE_NAMES
+
+    # Module state: pinning the active FFI::Function trampolines is required
+    # so the GC does not free them while the C ABI still holds the pointer.
+    @mutex = Mutex.new
+    @log_trampoline  = nil
+    @metrics_trampoline = nil
+    @log_callback    = nil
+    @metrics_callback = nil
+    # Re-entrancy guard. The +ffi+ gem itself can log via its own internal
+    # paths during marshalling, and the Rust crates we bridge to log freely.
+    # Without this guard a user callback that itself produces log output
+    # would re-enter the trampoline and recurse.
+    @log_in_callback = {}
+    @metrics_in_callback = {}
+
+    class << self
+      # Install a log hook. Three forms are supported:
+      #
+      # 1. A stdlib +Logger+ instance (or any Logger-compatible object that
+      #    responds to +#add+, +#debug+, +#info+, +#warn+, +#error+):
+      #
+      #      Asherah.set_log_hook(Logger.new($stdout))
+      #
+      #    Each Asherah record is forwarded via
+      #    +Logger#add(severity, message, target)+ so the logger's own filter
+      #    rules and formatters apply. The +target+ argument is passed as
+      #    +progname+ for routing.
+      #
+      # 2. A +Proc+ or block, yielded a Hash:
+      #
+      #      Asherah.set_log_hook do |event|
+      #        # event[:level]    => :debug | :info | :warn | :error  (symbol)
+      #        # event[:severity] => Logger::DEBUG ...  (Logger::Severity int)
+      #        # event[:target]   => "asherah::session"
+      #        # event[:message]  => "..."
+      #      end
+      #
+      # 3. +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)
+        callback ||= block
+        if callback.nil?
+          clear_log_hook
+          return
+        end
+        callback = logger_to_callback(callback) if logger_like?(callback)
+        unless callback.respond_to?(:call)
+          raise ArgumentError, "log hook must be a Logger, Proc, or block"
+        end
+
+        @mutex.synchronize do
+          @log_callback = callback
+          # Allocate the trampoline OUTSIDE the user block so a slow user
+          # callback can't hold the mutex.
+          @log_trampoline = FFI::Function.new(
+            :void,
+            [:pointer, :int, :string, :string]
+          ) do |_user_data, level, target, message|
+            dispatch_log(level, target, message)
+          end
+          rc = Native.asherah_set_log_hook(@log_trampoline, FFI::Pointer::NULL)
+          raise Error, "asherah_set_log_hook failed: rc=#{rc}" if rc != 0
+        end
+        nil
+      end
+
+      # Remove the active log hook. Idempotent.
+      def clear_log_hook
+        @mutex.synchronize do
+          Native.asherah_clear_log_hook
+          @log_callback = nil
+          @log_trampoline = nil
+        end
+        nil
+      end
+
+      # Install a metrics hook. +block+ receives a Hash:
+      #
+      #   # Timing event:
+      #   { type: :encrypt|:decrypt|:store|:load, duration_ns: Integer, name: nil }
+      #   # Cache event:
+      #   { type: :cache_hit|:cache_miss|:cache_stale, duration_ns: 0, name: String }
+      #
+      # Installing a hook implicitly enables the global metrics gate; clearing
+      # it disables the gate. Replaces any previously installed metrics hook.
+      # Pass +nil+ to clear.
+      def set_metrics_hook(callback = nil, &block)
+        callback ||= block
+        if callback.nil?
+          clear_metrics_hook
+          return
+        end
+        unless callback.respond_to?(:call)
+          raise ArgumentError, "metrics hook must be callable (Proc or block)"
+        end
+
+        @mutex.synchronize do
+          @metrics_callback = callback
+          @metrics_trampoline = FFI::Function.new(
+            :void,
+            [:pointer, :int, :uint64, :string]
+          ) do |_user_data, type, duration_ns, name|
+            dispatch_metric(type, duration_ns, name)
+          end
+          rc = Native.asherah_set_metrics_hook(@metrics_trampoline, FFI::Pointer::NULL)
+          raise Error, "asherah_set_metrics_hook failed: rc=#{rc}" if rc != 0
+        end
+        nil
+      end
+
+      # Remove the active metrics hook and disable the metrics gate. Idempotent.
+      def clear_metrics_hook
+        @mutex.synchronize do
+          Native.asherah_clear_metrics_hook
+          @metrics_callback = nil
+          @metrics_trampoline = nil
+        end
+        nil
+      end
+
+      private
+
+      # Duck-typed Logger detection: anything that is NOT a +Proc+/+Method+
+      # and responds to the core stdlib +Logger+ API is treated as a Logger
+      # instance. This catches stdlib +Logger+, +ActiveSupport::Logger+,
+      # +SemanticLogger+, +Ougai+, etc.
+      def logger_like?(obj)
+        return false if obj.is_a?(Proc) || obj.is_a?(Method)
+        %i[debug info warn error add].all? { |m| obj.respond_to?(m) }
+      end
+
+      def logger_to_callback(logger)
+        lambda do |event|
+          severity = event[:severity] || Logger::ERROR
+          # Logger#add(severity, msg, progname) — progname carries target so
+          # custom formatters can route on it.
+          logger.add(severity, event[:message], event[:target])
+        end
+      end
+
+      def dispatch_log(level, target, message)
+        tid = Thread.current.object_id
+        return if @log_in_callback[tid]
+        @log_in_callback[tid] = true
+        cb = @log_callback
+        return if cb.nil?
+        begin
+          severity = LOG_LEVEL_TO_SEVERITY[level] || Logger::ERROR
+          cb.call(
+            level: SEVERITY_TO_SYMBOL[severity] || :error,
+            severity: severity,
+            target: target.to_s,
+            message: message.to_s
+          )
+        rescue StandardError, ScriptError
+          # swallow — exceptions across FFI are undefined behavior
+        ensure
+          @log_in_callback.delete(tid)
+        end
+      end
+
+      def dispatch_metric(type, duration_ns, name)
+        tid = Thread.current.object_id
+        return if @metrics_in_callback[tid]
+        @metrics_in_callback[tid] = true
+        cb = @metrics_callback
+        return if cb.nil?
+        begin
+          cb.call(
+            type: METRIC_TYPE_NAMES[type] || :encrypt,
+            duration_ns: duration_ns,
+            name: name
+          )
+        rescue StandardError, ScriptError
+          # swallow
+        ensure
+          @metrics_in_callback.delete(tid)
+        end
+      end
+    end
+  end
+end

data/lib/asherah/native.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "rbconfig"
+require_relative "error"
+
+module Asherah
+  module Native
+    extend FFI::Library
+
+    class AsherahBuffer < FFI::Struct
+      layout :data, :pointer, :len, :size_t, :capacity, :size_t
+    end
+
+    class << self
+      def library_basenames
+        host = RbConfig::CONFIG["host_os"]
+        if host =~ /mswin|mingw|cygwin/
+          ["asherah_ffi.dll"]
+        elsif host =~ /darwin/
+          ["libasherah_ffi.dylib"]
+        else
+          ["libasherah_ffi.so"]
+        end
+      end
+
+      def candidate_paths
+        names = library_basenames
+        paths = []
+
+        # 1. Explicit override via environment variable
+        env = ENV.fetch("ASHERAH_RUBY_NATIVE", "").strip
+        unless env.empty?
+          if File.directory?(env)
+            names.each { |name| paths << File.join(env, name) }
+          else
+            paths << env
+          end
+        end
+
+        # 2. Bundled in gem (platform-specific gem ships it here)
+        native_dir = File.expand_path("native", __dir__)
+        names.each { |name| paths << File.join(native_dir, name) }
+
+        # 3. CARGO_TARGET_DIR (development)
+        cargo_target = ENV.fetch("CARGO_TARGET_DIR", "").strip
+        unless cargo_target.empty?
+          %w[debug release].each do |profile|
+            names.each { |name| paths << File.join(cargo_target, profile, name) }
+          end
+        end
+
+        # 4. Workspace target directory (development)
+        root = File.expand_path("../../..", __dir__)
+        %w[target/release target/debug].each do |sub|
+          names.each { |name| paths << File.join(root, sub, name) }
+        end
+
+        # 5. System library path fallback
+        names.each { |name| paths << name }
+        paths.uniq
+      end
+
+      def resolve_library
+        candidate_paths.find { |path| File.exist?(path) } || candidate_paths.first
+      end
+    end
+
+    LIBRARY_PATH = resolve_library
+    ffi_lib LIBRARY_PATH
+
+    attach_function :asherah_last_error_message, [], :pointer
+    # Factory creation can hit AWS KMS / DynamoDB / TLS handshakes, so it
+    # must release the GVL — otherwise every other Ruby thread blocks for
+    # the duration of the SDK init. T5 in
+    # docs/review-2026-05-05-findings.md.
+    attach_function :asherah_factory_new_from_env, [], :pointer, blocking: true
+    attach_function :asherah_factory_new_with_config, [:string], :pointer, blocking: true
+    attach_function :asherah_apply_config_json, [:string], :int, blocking: true
+    attach_function :asherah_factory_free, [:pointer], :void
+    attach_function :asherah_factory_get_session, [:pointer, :string], :pointer
+    attach_function :asherah_session_free, [:pointer], :void
+    # encrypt/decrypt block on the metastore (MySQL/Postgres/DynamoDB) and
+    # KMS during cache misses. blocking: true frees the GVL so other Ruby
+    # threads stay schedulable while the native call is in-flight.
+    attach_function :asherah_encrypt_to_json,
+                    [:pointer, :buffer_in, :size_t, :pointer], :int, blocking: true
+    attach_function :asherah_decrypt_from_json,
+                    [:pointer, :buffer_in, :size_t, :pointer], :int, blocking: true
+    attach_function :asherah_buffer_free, [:pointer], :void
+
+    # Async callback type: void(user_data, result_data, result_len, error_message)
+    callback :asherah_completion_fn, [:pointer, :pointer, :size_t, :string], :void
+    # The async entry points only enqueue work onto the Rust tokio runtime
+    # before returning, so they're brief — but mark them blocking anyway so
+    # a queue-full backpressure stall doesn't pin the GVL.
+    attach_function :asherah_encrypt_to_json_async,
+                    [:pointer, :buffer_in, :size_t, :asherah_completion_fn, :pointer], :int,
+                    blocking: true
+    attach_function :asherah_decrypt_from_json_async,
+                    [:pointer, :buffer_in, :size_t, :asherah_completion_fn, :pointer], :int,
+                    blocking: true
+
+    # Log + metrics hooks. The C ABI does not own the callback closure — Ruby
+    # must keep a reference to the FFI::Function it passes here for as long as
+    # the hook is registered, otherwise the GC will collect it and the next
+    # invocation segfaults. The Asherah module pins the active hooks in module
+    # state.
+    callback :asherah_log_callback, [:pointer, :int, :string, :string], :void
+    callback :asherah_metrics_callback, [:pointer, :int, :uint64, :string], :void
+
+    # Hook set/clear functions must release the GVL (blocking: true) because
+    # they may join the async dispatcher worker thread (via Drop on the old
+    # AsyncLogSink/AsyncMetricsSink). That worker thread needs the GVL to
+    # execute FFI callbacks into Ruby — holding the GVL here deadlocks.
+    attach_function :asherah_set_log_hook, [:asherah_log_callback, :pointer], :int, blocking: true
+    attach_function :asherah_clear_log_hook, [], :int, blocking: true
+    attach_function :asherah_set_metrics_hook, [:asherah_metrics_callback, :pointer], :int, blocking: true
+    attach_function :asherah_clear_metrics_hook, [], :int, blocking: true
+
+    # Internal: integer constants that mirror the C ABI severity/event
+    # codes in hooks.rs. The public Ruby API exposes them as
+    # +Logger::Severity+ values and +Symbol+ types respectively, so
+    # callers should never need to reference these directly.
+    LOG_TRACE = 0
+    LOG_DEBUG = 1
+    LOG_INFO  = 2
+    LOG_WARN  = 3
+    LOG_ERROR = 4
+
+    METRIC_ENCRYPT     = 0
+    METRIC_DECRYPT     = 1
+    METRIC_STORE       = 2
+    METRIC_LOAD        = 3
+    METRIC_CACHE_HIT   = 4
+    METRIC_CACHE_MISS  = 5
+    METRIC_CACHE_STALE = 6
+
+    def self.last_error
+      ptr = asherah_last_error_message
+      ptr.null? ? "unknown error" : ptr.read_string
+    end
+
+    private_class_method :library_basenames, :candidate_paths, :resolve_library
+  end
+end