class Riffer::Messages::FilePart

Represents a file attachment (image or document) — from a URL (from_url) or raw base64 data (new).

Constants

MEDIA_TYPES: @rbs @url_string: String? @rbs @data: String? @rbs @downloaded_data: String? @rbs @data_bytes: String?
SHA256_PATTERN
SUPPORTED_MEDIA_TYPES

Attributes

filename [R]

The filename, if available.

media_type [R]

The MIME type of the file.

sha256 [R]

The expected SHA-256 of the file contents, if the caller supplied one.

Public Class Methods

from_hash (file)

Source

# File lib/riffer/messages/file_part.rb, line 81
def self.from_hash(file)
  return file if file.is_a?(Riffer::Messages::FilePart)

  raise Riffer::ArgumentError, "File must be a Hash or FilePart object, got #{file.class}" unless file.is_a?(Hash)

  url = file[:url]
  data = file[:data]
  media_type = file[:media_type]
  filename = file[:filename]
  sha256 = file[:sha256]

  if url
    from_url(url, media_type: media_type, filename: filename, sha256: sha256)
  elsif data && media_type
    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

Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash, or returns file unchanged when it is already a FilePart. Raises Riffer::ArgumentError on an invalid hash.

from_url (url, media_type: nil, filename: nil, sha256: nil)

Source

# File lib/riffer/messages/file_part.rb, line 66
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, filename: filename, sha256: sha256)
end

Creates a FilePart from a URL, detecting media_type from the path extension when omitted. Raises Riffer::ArgumentError if it can’t be detected.

new (media_type:, data: nil, filename: nil, url: nil, sha256: nil)

Source

# File lib/riffer/messages/file_part.rb, line 44
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
  @url_string = url
end

Raises Riffer::ArgumentError unless data or url is given and media_type is supported.

Public Instance Methods

cache_data_bytes (bytes)

Source

# File lib/riffer/messages/file_part.rb, line 122
def cache_data_bytes(bytes)
  @data_bytes = bytes
end

: (String) -> void

cache_downloaded_data (data)

Source

# File lib/riffer/messages/file_part.rb, line 138
def cache_downloaded_data(data)
  @downloaded_data = data
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

data ()

Source

# File lib/riffer/messages/file_part.rb, line 105
def data
  @data || @downloaded_data
end

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.

data_bytes ()

Source

# File lib/riffer/messages/file_part.rb, line 110
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?

document? ()

Source

# File lib/riffer/messages/file_part.rb, line 170
def document?
  !image?
end

Returns true if the file is a document (not an image).

image? ()

Source

# File lib/riffer/messages/file_part.rb, line 162
def image?
  media_type.start_with?("image/")
end

Returns true if the file is an image.

inline_data? ()

Source

# File lib/riffer/messages/file_part.rb, line 129
def inline_data?
  !@data.nil?
end

Whether data was supplied directly, as opposed to filled in later by the
file resolver after a download

: () -> bool

to_h ()

Source

# File lib/riffer/messages/file_part.rb, line 178
def to_h
  hash = { media_type: media_type } #: Hash[Symbol, untyped]
  hash[:data] = @data if @data
  hash[:url] = @url_string if @url_string
  hash[:filename] = filename if filename
  hash[:sha256] = sha256 if sha256
  hash
end

Serializes the FilePart to a hash.

url ()

Source

# File lib/riffer/messages/file_part.rb, line 146
def url
  @url_string
end

Returns the URL if the source was a URL, nil otherwise.

url? ()

Source

# File lib/riffer/messages/file_part.rb, line 154
def url?
  !@url_string.nil?
end

Returns true if the source was a URL.