uploadcare-ruby 4.4.3 → 5.0.0.rc1

data/lib/uploadcare/internal/upload_io.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+# Wraps upload inputs so multipart and direct uploads can treat files and streams uniformly.
+class Uploadcare::Internal::UploadIo
+  # Fallback filename used when the source object does not expose one.
+  DEFAULT_FILENAME = 'upload.bin'
+
+  attr_reader :io, :original_filename
+
+  # Wrap a readable source into a unified upload object.
+  #
+  # @param source [IO]
+  # @param filename [String, nil]
+  # @return [Uploadcare::Internal::UploadIo]
+  def self.wrap(source, filename: nil)
+    raise ArgumentError, 'file must be a readable IO object' unless source.respond_to?(:read)
+
+    if path_backed?(source)
+      new(source, original_filename: filename || extract_filename(source), cleanup: false)
+    else
+      wrap_stream(source, filename: filename || extract_filename(source))
+    end
+  end
+
+  # @param source [IO]
+  # @return [Boolean]
+  def self.path_backed?(source)
+    source.respond_to?(:path) &&
+      source.path &&
+      ::File.file?(source.path) &&
+      ::File.readable?(source.path)
+  end
+
+  # @param source [IO]
+  # @return [String]
+  def self.extract_filename(source)
+    if source.respond_to?(:original_filename) && source.original_filename && !source.original_filename.empty?
+      source.original_filename
+    elsif path_backed?(source)
+      ::File.basename(source.path)
+    else
+      DEFAULT_FILENAME
+    end
+  end
+
+  # Materialize a non-path-backed stream into a tempfile.
+  #
+  # @param source [IO]
+  # @param filename [String]
+  # @return [Uploadcare::Internal::UploadIo]
+  def self.wrap_stream(source, filename:)
+    extension = ::File.extname(filename.to_s)
+    tempfile = Tempfile.new(['uploadcare-upload', extension.empty? ? '.bin' : extension])
+    tempfile.binmode
+
+    source.rewind if source.respond_to?(:rewind)
+    IO.copy_stream(source, tempfile)
+    tempfile.rewind
+    source.rewind if source.respond_to?(:rewind)
+
+    new(tempfile, original_filename: filename, cleanup: true)
+  end
+
+  # @param io [IO]
+  # @param original_filename [String]
+  # @param cleanup [Boolean]
+  def initialize(io, original_filename:, cleanup:)
+    @io = io
+    @original_filename = original_filename
+    @cleanup = cleanup
+  end
+
+  # @return [String]
+  def path
+    io.path
+  end
+
+  # @return [Integer]
+  def size
+    return io.size if io.respond_to?(:size)
+
+    ::File.size(path)
+  end
+
+  # @return [String, nil]
+  def read(*args)
+    io.read(*args)
+  end
+
+  # @return [Integer]
+  def seek(*args)
+    io.seek(*args)
+  end
+
+  # @return [void]
+  def rewind
+    io.rewind
+  end
+
+  # Close and unlink the wrapped tempfile when cleanup is enabled.
+  #
+  # @return [void]
+  def close!
+    return unless @cleanup
+
+    io.close!
+  end
+end

data/lib/uploadcare/internal/upload_params_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Generates upload parameters for Upload API requests.
+#
+# Builds the parameter hash needed for file uploads, including public key,
+# store preferences, metadata, and optional signature params.
+class Uploadcare::Internal::UploadParamsGenerator
+  class << self
+    # Build upload parameters.
+    #
+    # @param options [Hash] Upload options (:store, :metadata, :signature, :expire)
+    # @param config [Uploadcare::Configuration] Configuration with public key and signing settings
+    # @return [Hash] Upload parameters hash
+    def call(options: {}, config: Uploadcare.configuration)
+      params = {
+        'UPLOADCARE_PUB_KEY' => config.public_key
+      }
+
+      store = store_value(options[:store])
+      params['UPLOADCARE_STORE'] = store unless store.nil?
+
+      params.merge!(metadata(options: options))
+      params.merge!(signature_params(options: options, config: config))
+
+      params.compact
+    end
+
+    private
+
+    # Convert store option to API format.
+    #
+    # @param store [Boolean, String, Integer, nil] Store option value
+    # @return [String, nil] Formatted store value ('0', '1', or nil)
+    def store_value(store)
+      return nil if store.nil?
+
+      case store
+      when true, '1', 1 then '1'
+      when false, '0', 0 then '0'
+      else store.to_s
+      end
+    end
+
+    # Generate metadata parameters from options hash.
+    #
+    # @param options [Hash] Options containing :metadata key
+    # @return [Hash] Metadata params formatted as "metadata[key]" => "value"
+    def metadata(options:)
+      return {} if options[:metadata].nil?
+      raise ArgumentError, 'metadata must be a hash' unless options[:metadata].is_a?(Hash)
+
+      options[:metadata].each_with_object({}) do |(k, v), res|
+        res["metadata[#{k}]"] = v.to_s
+      end
+    end
+
+    # Generate signature parameters for signed uploads.
+    #
+    # @param options [Hash] Options with optional :signature and :expire keys
+    # @param config [Uploadcare::Configuration] Configuration with signing settings
+    # @return [Hash] Signature parameters
+    def signature_params(options:, config:)
+      return explicit_signature_params(options) if options.key?(:signature)
+      return {} unless config.sign_uploads
+
+      signature_data = Uploadcare::Internal::SignatureGenerator.call(config: config)
+      return { 'signature' => signature_data } unless signature_data.is_a?(Hash)
+
+      params = {}
+      params['signature'] = signature_data[:signature] || signature_data['signature']
+      params['expire'] = signature_data[:expire] || signature_data['expire']
+      params.compact
+    end
+
+    # Extract explicit signature params from options.
+    #
+    # @param options [Hash] Options with :signature and optional :expire
+    # @return [Hash] Signature parameters
+    def explicit_signature_params(options)
+      params = {}
+      params['signature'] = options[:signature]
+      params['expire'] = options[:expire] if options.key?(:expire)
+      params.compact
+    end
+  end
+end

data/lib/uploadcare/internal/user_agent.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# User-Agent string builder for Uploadcare API requests.
+#
+# Generates a standardized User-Agent header that identifies the Ruby gem version,
+# public key, Ruby version, and optional framework information.
+#
+# @example
+#   Uploadcare::Internal::UserAgent.call(config: config)
+#   # => "UploadcareRuby/5.0.0.rc1/demopublickey (Ruby/3.3.0)"
+class Uploadcare::Internal::UserAgent
+  # Build a User-Agent string.
+  #
+  # @param config [Uploadcare::Configuration] Configuration with public key and framework data
+  # @return [String] Formatted User-Agent string
+  def self.call(config: Uploadcare.configuration)
+    framework_data = config.framework_data.to_s
+    framework_suffix = framework_data.empty? ? '' : "; #{framework_data}"
+    public_key = config.public_key
+    "UploadcareRuby/#{Uploadcare::VERSION}/#{public_key} (Ruby/#{RUBY_VERSION}#{framework_suffix})"
+  end
+end

data/lib/uploadcare/operations/multipart_upload.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'mime/types'
+
+# Handles the complete multipart upload workflow.
+#
+# Multipart upload is used for files larger than the multipart threshold (default: 100MB).
+# The process:
+# 1. Start upload → get UUID and presigned URLs
+# 2. Upload file parts to presigned URLs (optionally in parallel)
+# 3. Complete upload → finalize and get file info
+#
+# @example
+#   mp = Uploadcare::Operations::MultipartUpload.new(upload_client: upload, config: config)
+#   result = mp.upload(file: large_file, store: true, threads: 4)
+class Uploadcare::Operations::MultipartUpload
+  CHUNK_SIZE = 5_242_880 # 5MB default chunk size
+
+  # @return [Uploadcare::Api::Upload] Upload API client
+  attr_reader :upload_client
+
+  # @return [Uploadcare::Configuration] Configuration
+  attr_reader :config
+
+  # @param upload_client [Uploadcare::Api::Upload] Upload API client
+  # @param config [Uploadcare::Configuration] Configuration
+  def initialize(upload_client:, config:)
+    @upload_client = upload_client
+    @config = config
+  end
+
+  # Execute the full multipart upload flow.
+  #
+  # @param file [File, IO] File to upload
+  # @param options [Hash] Upload options (:store, :metadata, :threads, :part_size)
+  # @param request_options [Hash] Request options
+  # @yield [Hash] Progress callback with :uploaded, :total, :part, :total_parts
+  # @return [Uploadcare::Result] Result containing { 'uuid' => '...' }
+  def upload(file:, request_options: {}, **options, &block)
+    Uploadcare::Result.capture do
+      prepared_file = Uploadcare::Internal::UploadIo.wrap(file)
+      file_size = prepared_file.size
+      filename = prepared_file.original_filename
+      content_type = MIME::Types.type_for(prepared_file.path).first&.content_type || 'application/octet-stream'
+      part_size, threads = normalize_upload_options(options)
+
+      start_response = Uploadcare::Result.unwrap(
+        upload_client.files.multipart_start(
+          filename: filename,
+          size: file_size,
+          content_type: content_type,
+          request_options: request_options,
+          **options
+        )
+      )
+
+      uuid = start_response['uuid']
+      presigned_urls = start_response['parts']
+
+      if threads > 1
+        upload_parts_parallel(prepared_file, presigned_urls, part_size, threads, &block)
+      else
+        upload_parts_sequential(prepared_file, presigned_urls, part_size, &block)
+      end
+
+      Uploadcare::Result.unwrap(
+        upload_client.files.multipart_complete(uuid: uuid, request_options: request_options)
+      )
+
+      { 'uuid' => uuid }
+    ensure
+      prepared_file&.close!
+    end
+  end
+
+  private
+
+  def normalize_upload_options(options)
+    part_size = Integer(options.fetch(:part_size, config.multipart_chunk_size || CHUNK_SIZE))
+    max_threads = Integer(config.upload_threads || 1)
+    threads = Integer(options.fetch(:threads, max_threads))
+
+    raise ArgumentError, 'part_size must be > 0' if part_size <= 0
+    raise ArgumentError, 'upload_threads must be >= 1' if max_threads < 1
+    raise ArgumentError, 'threads must be >= 1' if threads < 1
+    raise ArgumentError, "threads must be <= #{max_threads}" if threads > max_threads
+
+    [part_size, threads]
+  end
+
+  def upload_parts_sequential(file, presigned_urls, part_size, &block)
+    total_size = file.respond_to?(:size) ? file.size : ::File.size(file.path)
+    uploaded = 0
+
+    presigned_urls.each_with_index do |presigned_url, index|
+      file.seek(index * part_size)
+      part_data = file.read(part_size)
+      break if part_data.nil? || part_data.empty?
+
+      upload_part(presigned_url, part_data)
+      uploaded += part_data.bytesize
+
+      block&.call(uploaded: uploaded, total: total_size, part: index + 1, total_parts: presigned_urls.length)
+    end
+  end
+
+  def upload_parts_parallel(file, presigned_urls, part_size, threads, &)
+    total_size = file.respond_to?(:size) ? file.size : ::File.size(file.path)
+    uploaded = { value: 0 }
+    mutex = Mutex.new
+    queue = Queue.new
+    errors = []
+    cancel = { value: false }
+    file_path = file.path
+    total_parts = presigned_urls.length
+
+    presigned_urls.each_with_index { |url, index| queue << [url, index] }
+    threads.times { queue << nil }
+
+    worker_context = {
+      queue: queue,
+      file_path: file_path,
+      part_size: part_size,
+      total_size: total_size,
+      total_parts: total_parts,
+      mutex: mutex,
+      uploaded: uploaded,
+      errors: errors,
+      cancel: cancel
+    }
+
+    workers = threads.times.map do
+      Thread.new do
+        run_parallel_worker(worker_context, &)
+      end
+    end
+
+    workers.each(&:join)
+    raise errors.first if errors.any?
+  end
+
+  def run_parallel_worker(context, &)
+    ::File.open(context[:file_path], 'rb') do |worker_file|
+      process_parallel_jobs(worker_file, context, &)
+    rescue StandardError => e
+      record_parallel_error(context, e)
+    end
+  end
+
+  def process_parallel_jobs(worker_file, context, &)
+    loop do
+      job = context[:queue].pop
+      break unless process_parallel_job?(worker_file, context, job, &)
+    end
+  end
+
+  def process_parallel_job?(worker_file, context, job)
+    return false if job.nil? || context[:cancel][:value]
+
+    presigned_url, index = job
+    offset = index * context[:part_size]
+    return false if offset >= context[:total_size]
+
+    worker_file.seek(offset)
+    part_data = worker_file.read(context[:part_size])
+    return false if part_data.nil? || part_data.empty?
+
+    upload_part(presigned_url, part_data)
+    update_parallel_progress(context, index, part_data.bytesize) { |progress| yield(progress) if block_given? }
+    true
+  end
+
+  def update_parallel_progress(context, index, bytesize)
+    context[:mutex].synchronize do
+      context[:uploaded][:value] += bytesize
+      progress = {
+        uploaded: context[:uploaded][:value],
+        total: context[:total_size],
+        part: index + 1,
+        total_parts: context[:total_parts]
+      }
+      yield(progress)
+    end
+  end
+
+  def record_parallel_error(context, error)
+    context[:mutex].synchronize do
+      context[:cancel][:value] = true
+      context[:errors] << error
+    end
+  end
+
+  def upload_part(presigned_url, part_data)
+    upload_client.upload_part_to_url(
+      presigned_url,
+      part_data,
+      max_retries: configured_max_upload_retries,
+      timeout: configured_upload_timeout
+    )
+  end
+
+  def configured_max_upload_retries
+    value = config.max_upload_retries
+    value.nil? ? 3 : Integer(value)
+  end
+
+  def configured_upload_timeout
+    value = config.upload_timeout
+    return nil if value.nil?
+
+    Integer(value)
+  end
+end

data/lib/uploadcare/operations/upload_router.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# Routes upload requests to the appropriate Upload API endpoint.
+#
+# Handles the decision logic for choosing between:
+# - Direct upload (small files < multipart threshold)
+# - Multipart upload (large files >= multipart threshold)
+# - URL upload (string URLs)
+# - Batch upload (arrays of files)
+#
+# @example
+#   router = Uploadcare::Operations::UploadRouter.new(client: client)
+#   file = router.upload(File.open("image.jpg"))
+#   file = router.upload("https://example.com/image.jpg")
+#   files = router.upload([file1, file2])
+class Uploadcare::Operations::UploadRouter
+  # @return [Uploadcare::Client] Client instance
+  attr_reader :client
+
+  # @param client [Uploadcare::Client] Client instance
+  def initialize(client:)
+    @client = client
+  end
+
+  # Upload a file, URL, or array of files.
+  #
+  # Automatically routes to the appropriate upload method based on the source type:
+  # - File/IO objects >= multipart threshold → multipart upload
+  # - File/IO objects < multipart threshold → direct upload
+  # - Arrays → batch direct upload
+  # - Strings → URL upload
+  #
+  # @param source [File, IO, String, Array] Upload source
+  # @param options [Hash] Upload options (:store, :metadata, etc.)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File, Array<Uploadcare::Resources::File>, Hash]
+  # @raise [ArgumentError] if source type is not recognized
+  def upload(source, request_options: {}, **options, &block)
+    if big_file?(source)
+      multipart_upload(file: source, request_options: request_options, **options, &block)
+    elsif file?(source)
+      upload_file(file: source, request_options: request_options, **options)
+    elsif source.is_a?(Array)
+      upload_files(files: source, request_options: request_options, **options)
+    elsif source.is_a?(String)
+      upload_from_url(url: source, request_options: request_options, **options)
+    else
+      raise ArgumentError, "Expected input to be a File/Array/URL, given: `#{source}`"
+    end
+  end
+
+  # Upload a single file directly.
+  #
+  # @param file [File, IO] File to upload
+  # @param options [Hash] Upload options
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File]
+  def upload_file(file:, request_options: {}, **options)
+    response = Uploadcare::Result.unwrap(
+      client.api.upload.files.direct_many(files: [file], request_options: request_options, **options)
+    )
+    file_name, uuid = response.first
+    Uploadcare::Resources::File.new({ uuid: uuid, original_filename: decode_uploaded_filename(file_name) }, client)
+  end
+
+  # Upload multiple files directly.
+  #
+  # @param files [Array<File, IO>] Files to upload
+  # @param options [Hash] Upload options
+  # @param request_options [Hash] Request options
+  # @return [Array<Uploadcare::Resources::File>]
+  def upload_files(files:, request_options: {}, **options)
+    response = Uploadcare::Result.unwrap(
+      client.api.upload.files.direct_many(files: files, request_options: request_options, **options)
+    )
+    response.map do |file_name, uuid|
+      Uploadcare::Resources::File.new({ uuid: uuid, original_filename: decode_uploaded_filename(file_name) }, client)
+    end
+  end
+
+  # Upload a file from URL.
+  #
+  # @param url [String] Source URL
+  # @param options [Hash] Upload options (:async, :store, :metadata)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File, Hash] File resource (sync) or token hash (async)
+  def upload_from_url(url:, request_options: {}, **options)
+    response = Uploadcare::Result.unwrap(
+      client.api.upload.files.from_url(source_url: url, request_options: request_options, **options)
+    )
+    return response if options[:async]
+
+    Uploadcare::Resources::File.new(response, client)
+  end
+
+  # Upload a large file using multipart upload.
+  #
+  # @param file [File, IO] Large file to upload
+  # @param options [Hash] Upload options
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File]
+  def multipart_upload(file:, request_options: {}, **options, &block)
+    response = Uploadcare::Result.unwrap(
+      Uploadcare::Operations::MultipartUpload.new(
+        upload_client: client.api.upload,
+        config: client.config
+      ).upload(file: file, request_options: request_options, **options, &block)
+    )
+    return response unless response.is_a?(Hash) && response['uuid']
+
+    Uploadcare::Resources::File.new(response, client)
+  end
+
+  # Get upload-from-URL status.
+  #
+  # @param token [String] Upload token
+  # @param request_options [Hash] Request options
+  # @return [Hash] Status response
+  def upload_from_url_status(token:, request_options: {})
+    Uploadcare::Result.unwrap(
+      client.api.upload.files.from_url_status(token: token, request_options: request_options)
+    )
+  end
+
+  # Get file info from Upload API (without secret key).
+  #
+  # @param file_id [String] File UUID
+  # @param request_options [Hash] Request options
+  # @return [Hash] File information
+  def file_info(file_id:, request_options: {})
+    Uploadcare::Result.unwrap(
+      client.api.upload.files.info(file_id: file_id, request_options: request_options)
+    )
+  end
+
+  private
+
+  def file?(object)
+    !object.is_a?(String) && object.respond_to?(:read)
+  end
+
+  def big_file?(object)
+    return false unless file?(object)
+
+    upload_size(object) >= client.config.multipart_size_threshold
+  rescue StandardError
+    false
+  end
+
+  def upload_size(object)
+    return object.size if object.respond_to?(:size)
+    return ::File.size(object.path) if object.respond_to?(:path) && object.path && ::File.exist?(object.path)
+
+    0
+  end
+
+  def decode_uploaded_filename(file_name)
+    encoded_prefix = /\A__uploadcare_form_\d+(?:_\d+)?__(.+)\z/
+    match = encoded_prefix.match(file_name.to_s)
+    match ? match[1] : file_name
+  end
+end

data/lib/uploadcare/resources/addon_execution.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Add-on execution resource.
+#
+# Provides a unified interface for executing and checking status of
+# AWS Rekognition, ClamAV, and Remove.bg add-ons.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons
+class Uploadcare::Resources::AddonExecution < Uploadcare::Resources::BaseResource
+  attr_accessor :request_id, :status, :result
+
+  class << self
+    # Execute AWS Rekognition label detection.
+    def aws_rekognition_detect_labels(uuid:, client: nil, config: Uploadcare.configuration, request_options: {})
+      execute_addon(:aws_rekognition_detect_labels, client: client, config: config,
+                                                    request_options: request_options, uuid: uuid)
+    end
+
+    # Check AWS Rekognition label detection status.
+    def aws_rekognition_detect_labels_status(request_id:, client: nil, config: Uploadcare.configuration,
+                                             request_options: {})
+      check_addon_status(:aws_rekognition_detect_labels_status, client: client, config: config,
+                                                                request_options: request_options,
+                                                                request_id: request_id)
+    end
+
+    # Execute AWS Rekognition moderation label detection.
+    def aws_rekognition_detect_moderation_labels(uuid:, client: nil, config: Uploadcare.configuration,
+                                                 request_options: {})
+      execute_addon(:aws_rekognition_detect_moderation_labels, client: client, config: config,
+                                                               request_options: request_options, uuid: uuid)
+    end
+
+    # Check AWS Rekognition moderation label detection status.
+    def aws_rekognition_detect_moderation_labels_status(request_id:, client: nil,
+                                                        config: Uploadcare.configuration, request_options: {})
+      check_addon_status(:aws_rekognition_detect_moderation_labels_status, client: client, config: config,
+                                                                           request_options: request_options,
+                                                                           request_id: request_id)
+    end
+
+    # Execute ClamAV virus scan.
+    def uc_clamav_virus_scan(uuid:, params: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+      resolved_client = resolve_client(client: client, config: config)
+      response = Uploadcare::Result.unwrap(
+        resolved_client.api.rest.addons.uc_clamav_virus_scan(
+          uuid: uuid, params: params, request_options: request_options
+        )
+      )
+      new(response, resolved_client)
+    end
+
+    # Check ClamAV virus scan status.
+    def uc_clamav_virus_scan_status(request_id:, client: nil, config: Uploadcare.configuration,
+                                    request_options: {})
+      check_addon_status(:uc_clamav_virus_scan_status, client: client, config: config,
+                                                       request_options: request_options, request_id: request_id)
+    end
+
+    # Execute Remove.bg background removal.
+    def remove_bg(uuid:, params: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+      resolved_client = resolve_client(client: client, config: config)
+      response = Uploadcare::Result.unwrap(
+        resolved_client.api.rest.addons.remove_bg(
+          uuid: uuid, params: params, request_options: request_options
+        )
+      )
+      new(response, resolved_client)
+    end
+
+    # Check Remove.bg execution status.
+    def remove_bg_status(request_id:, client: nil, config: Uploadcare.configuration, request_options: {})
+      check_addon_status(:remove_bg_status, client: client, config: config,
+                                            request_options: request_options, request_id: request_id)
+    end
+
+    private
+
+    def execute_addon(method_name, client:, config:, request_options:, uuid:)
+      resolved_client = resolve_client(client: client, config: config)
+      response = Uploadcare::Result.unwrap(
+        resolved_client.api.rest.addons.public_send(method_name, uuid: uuid, request_options: request_options)
+      )
+      new(response, resolved_client)
+    end
+
+    def check_addon_status(method_name, client:, config:, request_options:, request_id:)
+      resolved_client = resolve_client(client: client, config: config)
+      response = Uploadcare::Result.unwrap(
+        resolved_client.api.rest.addons.public_send(
+          method_name, request_id: request_id, request_options: request_options
+        )
+      )
+      new(response, resolved_client)
+    end
+  end
+end