riffer 0.43.0 → 0.44.0

data/lib/riffer/files/resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require "base64"
+
+class Riffer::Files::Resolver
+  # @rbs @provider: Riffer::Providers::Base
+  # @rbs @config: Riffer::Config::Files
+
+  #: (provider: Riffer::Providers::Base) -> void
+  def initialize(provider:)
+    @provider = provider
+    @config = Riffer.config.files
+  end
+
+  # Resolves every file in every User message in place - downloading,
+  # verifying, and caching as the provider's capability and each file's
+  # sha256 require.  Raises Riffer::FileError on any file that can't be
+  # resolved
+  #: (Array[Riffer::Messages::Base]) -> void
+  def resolve!(messages)
+    files = messages.flat_map do |message|
+      next [] unless message.is_a?(Riffer::Messages::User)
+
+      check_file_count!(message)
+      message.files
+    end
+
+    @config.runner.map(files, context: nil) { |file| resolve_file!(file) }
+  end
+
+  private
+
+  #: (Riffer::Messages::User) -> void
+  def check_file_count!(message)
+    max = @config.max_per_message
+    return if max.nil? || message.files.size <= max
+
+    raise Riffer::TooManyFilesError, "Too many files specified in user message"
+  end
+
+  #: (Riffer::Messages::FilePart) -> void
+  def resolve_file!(file)
+    delivery = @provider.file_delivery(file)
+    if delivery == :unsupported
+      raise Riffer::FileUnsupportedError,
+            "Provider does not support user message file attachments"
+    end
+    return verify_inline!(file) if file.inline_data?
+
+    case delivery
+    when :url
+      download!(file, cache: false) if file.sha256
+    when :base64
+      file.data ? verify_inline!(file) : download!(file, cache: :base64)
+    when :bytes
+      file.data_bytes ? verify_inline!(file) : download!(file, cache: :bytes)
+    else
+      raise Riffer::ArgumentError,
+            "Unknown file_delivery result #{delivery.inspect} from #{@provider.class}"
+    end
+  end
+
+  #: (Riffer::Messages::FilePart) -> void
+  def verify_inline!(file)
+    return unless file.sha256
+
+    verify_bytes!(file.data_bytes, file.sha256)
+  end
+
+  # +cache:+ is false for a :url-delivery provider verifying a sha256 — the
+  # request still sends the URL, never the downloaded bytes, so caching them
+  # would hold memory nothing reads and let later turns skip re-verifying.
+  #: (Riffer::Messages::FilePart, cache: (false | Symbol)) -> void
+  def download!(file, cache:)
+    raise Riffer::FileDownloadsDisabledError, "File attachments are disabled" unless @config.allow_downloads
+
+    raw = @config.downloader.call(file.url, max_bytes: @config.max_bytes, timeout: @config.timeout)
+    verify_bytes!(raw, file.sha256) if file.sha256
+
+    case cache
+    when :base64
+      file.cache_downloaded_data(Base64.strict_encode64(raw))
+    when :bytes
+      file.cache_data_bytes(raw)
+    when false
+      nil
+    end
+  end
+
+  def verify_bytes!(bytes, sha256)
+    return if Digest::SHA256.hexdigest(bytes) == sha256
+
+    raise Riffer::FileChecksumMismatchError, "File checksum mismatch"
+  end
+end

data/lib/riffer/files.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Riffer::Files
+end

data/lib/riffer/helpers/identifier.rb

@@ -29,13 +29,21 @@ module Riffer::Helpers::Identifier
     cached = klass.instance_variable_get(:@derived_identifier) #: String?
     return cached if cached
 
-    # Tool classes shadow Module#name with the identifier DSL, so the real
-    # class-path name must come from Module's own implementation.
-    real_name = Module.instance_method(:name).bind_call(klass) #: String?
+    real_name = real_name(klass)
     return "" if real_name.nil?
 
     derived = derive(real_name)
     klass.instance_variable_set(:@derived_identifier, derived)
     derived
   end
+
+  # Returns the class-path name of a class or module, or +nil+ when anonymous.
+  # Tool classes shadow Module#name with the identifier DSL, so the real name
+  # must come from Module's own implementation.
+  #
+  #--
+  #: (Module) -> String?
+  def real_name(klass)
+    Module.instance_method(:name).bind_call(klass) #: String?
+  end
 end

data/lib/riffer/messages/file_part.rb

@@ -8,6 +8,9 @@ require "uri"
 # raw base64 data (+new+).
 class Riffer::Messages::FilePart
   # @rbs @url_string: String?
+  # @rbs @data: String?
+  # @rbs @downloaded_data: String?
+  # @rbs @data_bytes: String?
 
   MEDIA_TYPES = {
     ".jpg" => "image/jpeg",
@@ -23,6 +26,7 @@ class Riffer::Messages::FilePart
   }.freeze #: Hash[String, String]
 
   SUPPORTED_MEDIA_TYPES = MEDIA_TYPES.values.uniq.freeze #: Array[String]
+  SHA256_PATTERN = /\A[0-9a-f]{64}\z/i #: Regexp
 
   # The MIME type of the file.
   attr_reader :media_type #: String
@@ -30,17 +34,25 @@ class Riffer::Messages::FilePart
   # The filename, if available.
   attr_reader :filename #: String?
 
+  # The expected SHA-256 of the file contents, if the caller supplied one.
+  attr_reader :sha256 #: String?
+
   # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
   # +media_type+ is supported.
   #--
-  #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?) -> void
-  def initialize(media_type:, data: nil, filename: nil, url: nil)
+  #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
+  def initialize(media_type:, data: nil, filename: nil, url: nil, sha256: nil)
     raise Riffer::ArgumentError, "Either data or url must be provided" if data.nil? && url.nil?
     unless SUPPORTED_MEDIA_TYPES.include?(media_type)
       raise Riffer::ArgumentError,
             "Unsupported media type: #{media_type}"
     end
+    unless sha256.nil? || (sha256.is_a?(String) && sha256.match?(SHA256_PATTERN))
+      raise Riffer::ArgumentError,
+            "Invalid sha256: #{sha256}"
+    end
 
+    @sha256 = sha256&.downcase
     @data = data
     @media_type = media_type
     @filename = filename
@@ -50,15 +62,15 @@ class Riffer::Messages::FilePart
   # Creates a FilePart from a URL, detecting +media_type+ from the path
   # extension when omitted. Raises Riffer::ArgumentError if it can't be detected.
   #--
-  #: (String, ?media_type: String?) -> Riffer::Messages::FilePart
-  def self.from_url(url, media_type: nil)
+  #: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
     unless media_type
       ext = ::File.extname(URI.parse(url).path.to_s).downcase
       media_type = MEDIA_TYPES[ext]
       raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" unless media_type
     end
 
-    new(url: url, media_type: media_type)
+    new(url: url, media_type: media_type, filename: filename, sha256: sha256)
   end
 
   # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
@@ -75,18 +87,57 @@ class Riffer::Messages::FilePart
     data = file[:data]
     media_type = file[:media_type]
     filename = file[:filename]
+    sha256 = file[:sha256]
 
     if url
-      from_url(url, media_type: media_type)
+      from_url(url, media_type: media_type, filename: filename, sha256: sha256)
     elsif data && media_type
-      new(data: data, media_type: media_type, filename: filename)
+      new(data: data, media_type: media_type, filename: filename, sha256: sha256)
     else
       raise Riffer::ArgumentError, "File hash must include :url or :data with :media_type"
     end
   end
 
-  # Returns the base64-encoded data, or nil for URL-only sources.
-  attr_reader :data #: String?
+  # The base64-encoded contents - caller-supplied, or filled in by the file
+  # resolver after a download.  Nil for a URL source riffer hasn't fetched.
+  #--
+  #: () -> String?
+  def data
+    @data || @downloaded_data
+  end
+
+  #: () -> String?
+  def data_bytes
+    return @data_bytes if @data_bytes
+
+    encoded = data
+    return nil unless encoded
+
+    @data_bytes = Base64.strict_decode64(encoded.gsub(/\s/, ""))
+  rescue ArgumentError
+    raise Riffer::FileEncodingError, "Invalid base64 data"
+  end
+
+  #: (String) -> void
+  def cache_data_bytes(bytes)
+    @data_bytes = bytes
+  end
+
+  # Whether data was supplied directly, as opposed to filled in later by the
+  # file resolver after a download
+  #: () -> bool
+  def inline_data?
+    !@data.nil?
+  end
+
+  # Caches bytes fetched for a URL source.  Deliberately absent from +to_h+:
+  # the agent loop re-sends history on every turn, so the cache saves refreshing
+  # the same file, while persisted history stays free of megabytes of base64
+  #--
+  #: (String) -> void
+  def cache_downloaded_data(data)
+    @downloaded_data = data
+  end
 
   # Returns the URL if the source was a URL, nil otherwise.
   #
@@ -129,6 +180,7 @@ class Riffer::Messages::FilePart
     hash[:data] = @data if @data
     hash[:url] = @url_string if @url_string
     hash[:filename] = filename if filename
+    hash[:sha256] = sha256 if sha256
     hash
   end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -43,6 +43,12 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     depends_on "aws-sdk-bedrockruntime"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.url&.start_with?("s3://") ? :url : :bytes
+  end
+
   private
 
   #--
@@ -413,13 +419,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def convert_file_part_to_bedrock_format(file)
     format = bedrock_format(file.media_type)
 
-    source = if file.data
-               { bytes: Base64.decode64(file.data) }
-             elsif file.url&.start_with?("s3://")
-               { s3_location: { uri: file.url } }
-             else
-               raise Riffer::ArgumentError, "Amazon Bedrock only supports S3 URI or base64 data file sources"
-             end
+    source = file.data_bytes ? { bytes: file.data_bytes } : { s3_location: { uri: file.url } }
 
     if file.image?
       { image: { format: format, source: source } }

data/lib/riffer/providers/base.rb

@@ -48,6 +48,7 @@ class Riffer::Providers::Base
     @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
+    Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
 
@@ -84,6 +85,7 @@ class Riffer::Providers::Base
     @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
+    Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
 
@@ -102,6 +104,12 @@ class Riffer::Providers::Base
     end
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(_file)
+    :url
+  end
+
   private
 
   #: (String) -> true

data/lib/riffer/providers/gemini.rb

@@ -27,6 +27,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "gcp.gemini"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(_file)
+    :base64
+  end
+
   private
 
   #--
@@ -274,11 +280,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
-    if file.url?
-      raise Riffer::ArgumentError,
-            "Gemini provider does not support URL-based file references. Provide base64-encoded data instead."
-    end
-
     { inlineData: { mimeType: file.media_type, data: file.data } }
   end
 

data/lib/riffer/providers/open_ai.rb

@@ -19,6 +19,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     depends_on "openai"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.image? ? :url : :base64
+  end
+
   private
 
   #--

data/lib/riffer/providers/open_router.rb

@@ -33,6 +33,12 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     depends_on "openai"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.image? ? :url : :base64
+  end
+
   private
 
   #--

data/lib/riffer/registrable.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Registry of a class's named direct subclasses, keyed by identifier. Extend it
+# Registry of a class's direct subclasses, keyed by identifier. Extend it
 # onto a base class to look up subclasses in constant time via +find+ and +all+.
+# Subclasses join implicitly by inheriting; +register+ adds one explicitly, for
+# ephemeral classes a test suite builds and tears down. Registration is not
+# synchronized — register during boot or from a single-threaded test, before
+# concurrent lookups begin.
 #
 #   class Riffer::Tool
 #     extend Riffer::Registrable
@@ -13,12 +17,15 @@
 # @rbs module-self Class
 module Riffer::Registrable
   # @rbs @identifier_registry: Hash[String, Class]?
+  # @rbs @explicit_registrations: Hash[String, Class]?
 
   # Finds a registered subclass by identifier, or +nil+ when none matches.
-  # Only *named direct* subclasses are registered: grandchildren are not
-  # visible to a grandparent's +find+ (call +find+ on their direct parent
-  # instead), anonymous classes are never registered, and duplicate identifiers
-  # raise Riffer::DuplicateIdentifierError at first lookup.
+  # Implicit registration covers only *named direct* subclasses: grandchildren
+  # are not visible to a grandparent's +find+ (call +find+ on their direct
+  # parent instead), anonymous classes are never registered implicitly, and a
+  # subclass whose name no longer resolves back to it is dropped at the next
+  # registry rebuild. Duplicate identifiers raise
+  # Riffer::DuplicateIdentifierError at first lookup.
   #
   #--
   #: (String | Symbol) -> Class?
@@ -26,10 +33,8 @@ module Riffer::Registrable
     identifier_registry[identifier.to_s]
   end
 
-  # Returns all registered subclasses. Only *named direct* subclasses are
-  # registered: grandchildren are not included (call +all+ on their direct
-  # parent instead), anonymous classes are never registered, and duplicate
-  # identifiers raise Riffer::DuplicateIdentifierError at first lookup.
+  # Returns all registered subclasses, implicit and explicit. Carries the same
+  # registration rules as +find+.
   #
   #--
   #: () -> Array[Class]
@@ -37,6 +42,45 @@ module Riffer::Registrable
     identifier_registry.values
   end
 
+  # Registers a direct subclass under its +identifier+, whether or not it is
+  # named — unlike implicit registration, it survives a name that no longer
+  # resolves, so an ephemeral class stays findable until +unregister+. Prefer
+  # Riffer::Testing for ordinary test setup, which stubs and cleans up
+  # automatically.
+  #
+  # Raises Riffer::ArgumentError when the identifier is blank or the class is
+  # not a direct subclass, and Riffer::DuplicateIdentifierError when the
+  # identifier is already taken — including by this same class.
+  #
+  #--
+  #: (Class) -> void
+  def register(klass)
+    unless klass.superclass.equal?(self)
+      raise Riffer::ArgumentError, "#{klass} must be a direct subclass of #{self} to register"
+    end
+
+    key = identifier_key(klass)
+    raise Riffer::ArgumentError, "#{klass} must declare a non-blank identifier to register" if key.strip.empty?
+
+    existing = identifier_registry[key]
+    raise_duplicate_identifier!(key, existing, klass) if existing
+
+    explicit_registrations[key] = klass
+    @identifier_registry = nil
+  end
+
+  # Removes an explicit registration of +klass+, leaving implicit registrations
+  # untouched.
+  #--
+  #: (Class) -> void
+  def unregister(klass)
+    key, = explicit_registrations.find { |_key, registered| registered.equal?(klass) }
+    return if key.nil?
+
+    explicit_registrations.delete(key)
+    @identifier_registry = nil
+  end
+
   private
 
   # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
@@ -55,27 +99,66 @@ module Riffer::Registrable
     @identifier_registry ||= build_identifier_registry
   end
 
+  #--
+  #: () -> Hash[String, Class]
+  def explicit_registrations
+    @explicit_registrations ||= {}
+  end
+
   #--
   #: () -> Hash[String, Class]
   def build_identifier_registry
-    registry = {} #: Hash[String, Class]
-    subclasses.each_with_object(registry) do |subclass, acc|
-      # Anonymous classes are skipped even with an explicit identifier — the
-      # MCP factory and serializer shells synthesize short-lived anonymous
-      # classes whose registration would flake with GC timing.
-      next if Riffer::Helpers::Identifier.for(subclass).empty?
-
-      candidate = subclass #: untyped
-      key = candidate.identifier.to_s
+    subclasses.each_with_object(explicit_registrations.dup) do |subclass, acc|
+      next unless live?(subclass)
+
+      key = identifier_key(subclass)
       next if key.strip.empty?
 
       existing = acc[key]
-      if existing
-        raise Riffer::DuplicateIdentifierError,
-              "Duplicate identifier #{key.inspect} for #{existing} and #{subclass}"
-      end
+      raise_duplicate_identifier!(key, existing, subclass) if existing && !existing.equal?(subclass)
 
       acc[key] = subclass
     end.freeze
   end
+
+  # Class#subclasses keeps returning superseded generations of a reloaded or
+  # stubbed class, so a subclass counts only while its own name still resolves
+  # back to it. An anonymous class has no name to resolve and is skipped even
+  # with an explicit identifier — the MCP factory and serializer shells
+  # synthesize short-lived anonymous classes whose registration would flake
+  # with GC timing.
+  #--
+  #: (Class) -> bool
+  def live?(subclass)
+    real_name = Riffer::Helpers::Identifier.real_name(subclass)
+    return false if real_name.nil?
+
+    # Module#autoload? does not traverse a qualified path, so each segment is
+    # resolved against its own owner: probing a pending autoload would trigger
+    # the load, whose +inherited+ hook busts the memo this build is populating.
+    root = Object #: Module
+    resolved = real_name.split("::").reduce(root) do |owner, segment|
+      return false if owner.autoload?(segment, false)
+
+      owner.const_get(segment, false) #: Module
+    end
+
+    resolved.equal?(subclass)
+  rescue NameError
+    false
+  end
+
+  #--
+  #: (Class) -> String
+  def identifier_key(klass)
+    candidate = klass #: untyped
+    candidate.identifier.to_s
+  end
+
+  #--
+  #: (String, Class, Class) -> void
+  def raise_duplicate_identifier!(key, existing, klass)
+    raise Riffer::DuplicateIdentifierError,
+          "Duplicate identifier #{key.inspect} for #{existing} and #{klass}"
+  end
 end

data/lib/riffer/testing/minitest.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# rbs-inline stays disabled here: the generated signature would name Minitest,
+# which a shipped signature must never reference. The hand-written stub lives in
+# sig/_private/riffer/testing/minitest.rbs.
+
+require "riffer"
+
+# Wiring only — minitest is never a riffer dependency; a consumer requires this
+# file from a test_helper that has already loaded the framework.
+module Riffer::Testing::MinitestCleanup
+  # Minitest reserves +after_teardown+ for library extensions; +teardown+
+  # belongs to the test author.
+  def after_teardown
+    Riffer::Testing.reset!
+    super
+  end
+end
+
+Minitest::Test.include(Riffer::Testing)
+Minitest::Test.include(Riffer::Testing::MinitestCleanup)

data/lib/riffer/testing/rspec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "riffer"
+
+# Wiring only — RSpec is never a riffer dependency; a consumer requires this
+# file from a spec_helper that has already loaded the framework.
+RSpec.configure do |config|
+  config.include Riffer::Testing
+  config.after { Riffer::Testing.reset! }
+end