uploadcare-ruby 4.4.2 → 5.0.0.rc1

data/lib/uploadcare/api/upload/files.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+# Upload API endpoint for file upload operations.
+# rubocop:disable Metrics/ClassLength
+class Uploadcare::Api::Upload::Files
+  # @return [Uploadcare::Api::Upload] Parent Upload client
+  attr_reader :upload
+
+  # @param upload [Uploadcare::Api::Upload] Parent Upload client
+  def initialize(upload:)
+    @upload = upload
+  end
+
+  # Upload a file directly (POST /base/).
+  #
+  # @param file [File, IO] File object to upload
+  # @param options [Hash] Upload options (:store, :metadata, :signature, :expire)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Upload response with file UUID
+  # @raise [ArgumentError] if file is not a valid IO object
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/baseUpload
+  def direct(file:, request_options: {}, **options)
+    Uploadcare::Result.capture do
+      prepared_file = Uploadcare::Internal::UploadIo.wrap(file)
+      params = build_upload_params(prepared_file, options)
+      Uploadcare::Result.unwrap(upload.post(path: 'base/', params: params, request_options: request_options))
+    ensure
+      prepared_file&.close!
+    end
+  end
+
+  # Upload multiple files directly (POST /base/).
+  #
+  # @param files [Array<File, IO>] Files to upload
+  # @param options [Hash] Upload options (:store, :metadata)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Upload response hash mapping filenames to UUIDs
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/baseUpload
+  def direct_many(files:, request_options: {}, **options)
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'files must be an array' unless files.is_a?(Array)
+      raise ArgumentError, 'files cannot be empty' if files.empty?
+
+      prepared_files = []
+      params = Uploadcare::Internal::UploadParamsGenerator.call(
+        options: options, config: upload.config
+      )
+      files.each do |file|
+        prepared_file = Uploadcare::Internal::UploadIo.wrap(file)
+        prepared_files << prepared_file
+        form_data_for(prepared_file, params, field_index: prepared_files.length - 1)
+      end
+      Uploadcare::Result.unwrap(upload.post(path: '/base/', params: params, request_options: request_options))
+    ensure
+      prepared_files&.each(&:close!)
+    end
+  end
+
+  # Upload a file from URL (POST /from_url/).
+  #
+  # @param source_url [String] URL of the file to upload
+  # @param options [Hash] Upload options
+  # @option options [Boolean] :async Return immediately with token (default: false)
+  # @option options [String, Boolean] :store Whether to store the file
+  # @option options [Hash] :metadata Custom metadata
+  # @option options [Integer] :poll_interval Polling interval in seconds (default: 1)
+  # @option options [Integer] :poll_timeout Max polling time in seconds (default: 300)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Upload response (file info or token)
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/fromUrlUpload
+  def from_url(source_url:, request_options: {}, **options)
+    Uploadcare::Result.capture do
+      validate_url(source_url)
+      async_mode = options.fetch(:async, false)
+      params = build_from_url_params(source_url, options)
+      response = Uploadcare::Result.unwrap(
+        upload.post(path: 'from_url/', params: params, request_options: request_options)
+      )
+      if async_mode
+        response
+      else
+        poll_upload_status(token: response['token'], options: options, request_options: request_options)
+      end
+    end
+  end
+
+  # Get upload-from-URL status (GET /from_url/status/).
+  #
+  # @param token [String] Upload token from async upload
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Status response
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/fromUrlUploadStatus
+  def from_url_status(token:, request_options: {})
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'token cannot be empty' if token.to_s.strip.empty?
+
+      Uploadcare::Result.unwrap(
+        upload.get(path: 'from_url/status/', params: { token: token }, request_options: request_options)
+      )
+    end
+  end
+
+  # Start a multipart upload (POST /multipart/start/).
+  #
+  # @param filename [String] Original filename
+  # @param size [Integer] File size in bytes
+  # @param content_type [String] MIME type
+  # @param options [Hash] Upload options (:store, :metadata)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Response with UUID and presigned URLs
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/multipartUploadStart
+  def multipart_start(filename:, size:, content_type:, request_options: {}, **options)
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'filename cannot be empty' if filename.to_s.strip.empty?
+      raise ArgumentError, 'size must be a positive integer' unless size.is_a?(Integer) && size.positive?
+      raise ArgumentError, 'content_type cannot be empty' if content_type.to_s.strip.empty?
+
+      params = build_multipart_start_params(filename, size, content_type, options)
+      Uploadcare::Result.unwrap(
+        upload.post(path: 'multipart/start/', params: params, request_options: request_options)
+      )
+    end
+  end
+
+  # Complete a multipart upload (POST /multipart/complete/).
+  #
+  # @param uuid [String] Upload UUID from multipart_start
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Final file information
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/multipartUploadComplete
+  def multipart_complete(uuid:, request_options: {})
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'uuid cannot be empty' if uuid.to_s.strip.empty?
+
+      params = {
+        'UPLOADCARE_PUB_KEY' => upload.config.public_key,
+        'uuid' => uuid
+      }
+      Uploadcare::Result.unwrap(
+        upload.post(path: 'multipart/complete/', params: params, request_options: request_options)
+      )
+    end
+  end
+
+  # Get file info from Upload API (GET /info/).
+  #
+  # @param file_id [String] File UUID
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] File information
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/filesInfo
+  def info(file_id:, request_options: {})
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'file_id cannot be empty' if file_id.to_s.strip.empty?
+
+      Uploadcare::Result.unwrap(
+        upload.get(path: 'info/', params: { pub_key: upload.config.public_key, file_id: file_id },
+                   request_options: request_options)
+      )
+    end
+  end
+
+  private
+
+  def validate_url(url)
+    raise ArgumentError, 'URL cannot be empty' if url.to_s.strip.empty?
+
+    uri = URI.parse(url)
+    raise ArgumentError, 'URL must be HTTP or HTTPS' unless %w[http https].include?(uri.scheme)
+  rescue URI::InvalidURIError => e
+    raise ArgumentError, "Invalid URL: #{e.message}"
+  end
+
+  def build_upload_params(file, options)
+    params = Uploadcare::Internal::UploadParamsGenerator.call(
+      options: options, config: upload.config
+    )
+    form_data_for(file, params)
+  end
+
+  def form_data_for(file, params, field_index: nil)
+    file_path = file.path
+    filename = file.respond_to?(:original_filename) ? file.original_filename : ::File.basename(file_path)
+    mime = MIME::Types.type_for(file.path).first&.content_type || 'application/octet-stream'
+
+    field_name = unique_form_field_name(filename, params, field_index)
+    params[field_name] = Faraday::Multipart::FilePart.new(file_path, mime, filename)
+    params
+  end
+
+  def build_from_url_params(source_url, options)
+    params = {
+      'pub_key' => upload.config.public_key,
+      'source_url' => source_url
+    }
+    store = store_value(options[:store])
+    params['store'] = store unless store.nil?
+    params['check_URL_duplicates'] = options[:check_URL_duplicates].to_s if options.key?(:check_URL_duplicates)
+    params['save_URL_duplicates'] = options[:save_URL_duplicates].to_s if options.key?(:save_URL_duplicates)
+    metadata_params = generate_metadata_params(options[:metadata])
+    params.merge!(metadata_params) if metadata_params.any?
+    params.merge!(signature_params(options))
+    params
+  end
+
+  def build_multipart_start_params(filename, size, content_type, options)
+    params = {
+      'UPLOADCARE_PUB_KEY' => upload.config.public_key,
+      'filename' => filename,
+      'size' => size.to_s,
+      'content_type' => content_type
+    }
+    store = store_value(options[:store])
+    params['UPLOADCARE_STORE'] = store unless store.nil?
+    metadata_params = generate_metadata_params(options[:metadata])
+    params.merge!(metadata_params) if metadata_params.any?
+    params.merge!(signature_params(options))
+    params
+  end
+
+  def poll_upload_status(token:, options: {}, request_options: {})
+    initial_poll_interval = options.fetch(:poll_interval, 1).to_f
+    max_poll_interval = options.fetch(:poll_max_interval, 10).to_f
+    poll_timeout = options.fetch(:poll_timeout, 300)
+    poll_attempt = 0
+    start_time = Time.now
+
+    loop do
+      status = Uploadcare::Result.unwrap(from_url_status(token: token, request_options: request_options))
+
+      case status['status']
+      when 'success'
+        return status
+      when 'error'
+        raise Uploadcare::Exception::UploadError, "Upload from URL failed: #{status['error']}"
+      when 'waiting', 'progress'
+        elapsed = Time.now - start_time
+        if elapsed > poll_timeout
+          raise Uploadcare::Exception::UploadTimeoutError,
+                "Upload from URL polling timed out after #{poll_timeout} seconds"
+        end
+
+        sleep_duration = next_poll_sleep(
+          initial: initial_poll_interval,
+          max_interval: max_poll_interval,
+          attempt: poll_attempt
+        )
+        sleep(sleep_duration)
+        poll_attempt += 1
+      else
+        raise Uploadcare::Exception::UnknownStatusError, "Unknown upload status: #{status['status']}"
+      end
+    end
+  end
+
+  def store_value(store)
+    return nil if store.nil?
+
+    case store
+    when true then '1'
+    when false then '0'
+    else store.to_s
+    end
+  end
+
+  def generate_metadata_params(metadata = nil)
+    return {} if metadata.nil? || !metadata.is_a?(Hash)
+
+    metadata.each_with_object({}) do |(key, value), result|
+      result["metadata[#{key}]"] = value.to_s
+    end
+  end
+
+  def signature_params(options = {})
+    return {} if options.nil?
+
+    if options[:signature]
+      params = { 'signature' => options[:signature] }
+      params['expire'] = options[:expire].to_s if options[:expire]
+      return params
+    end
+
+    return {} unless upload.config.sign_uploads
+
+    result = Uploadcare::Internal::SignatureGenerator.call(config: upload.config)
+    if result.is_a?(Hash)
+      sig = result[:signature] || result['signature']
+      exp = result[:expire] || result['expire']
+      p = {}
+      p['signature'] = sig if sig
+      p['expire'] = exp if exp
+      p
+    else
+      { 'signature' => result }
+    end
+  end
+
+  def unique_form_field_name(filename, params, field_index)
+    return filename unless params.key?(filename)
+
+    candidate = "__uploadcare_form_#{field_index || 0}__#{filename}"
+    suffix = 0
+    while params.key?(candidate)
+      suffix += 1
+      candidate = "__uploadcare_form_#{field_index || 0}_#{suffix}__#{filename}"
+    end
+    candidate
+  end
+
+  def next_poll_sleep(initial:, max_interval:, attempt:)
+    [initial.to_f * (2**attempt), max_interval.to_f].min
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/uploadcare/api/upload/groups.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Upload API endpoint for group operations.
+#
+# @see https://uploadcare.com/api-refs/upload-api/#operation/createFilesGroup
+class Uploadcare::Api::Upload::Groups
+  # @return [Uploadcare::Api::Upload] Parent Upload client
+  attr_reader :upload
+
+  # @param upload [Uploadcare::Api::Upload] Parent Upload client
+  def initialize(upload:)
+    @upload = upload
+  end
+
+  # Create a file group from UUIDs (POST /group/).
+  #
+  # @param files [Array<String>] Array of file UUIDs or objects responding to #uuid
+  # @param options [Hash] Group creation options (:signature, :expire)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Group information
+  # @raise [ArgumentError] if files is empty or not an array
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/createFilesGroup
+  def create(files:, request_options: {}, **options)
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'files must be an array' unless files.is_a?(Array)
+      raise ArgumentError, 'files cannot be empty' if files.empty?
+
+      params = build_group_params(files, options)
+      Uploadcare::Result.unwrap(
+        upload.post(path: 'group/', params: params, headers: {}, request_options: request_options)
+      )
+    end
+  end
+
+  # Get group info (GET /group/info/).
+  #
+  # @param group_id [String] Group UUID
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Group information
+  # @raise [ArgumentError] if group_id is empty
+  # @see https://uploadcare.com/api-refs/upload-api/#operation/filesGroupInfo
+  def info(group_id:, request_options: {})
+    Uploadcare::Result.capture do
+      raise ArgumentError, 'group_id cannot be empty' if group_id.to_s.strip.empty?
+
+      Uploadcare::Result.unwrap(
+        upload.get(path: 'group/info/',
+                   params: { pub_key: upload.config.public_key, group_id: group_id },
+                   request_options: request_options)
+      )
+    end
+  end
+
+  private
+
+  def build_group_params(files, options)
+    params = { 'pub_key' => upload.config.public_key }
+
+    files.each_with_index do |file, index|
+      uuid = file.respond_to?(:uuid) ? file.uuid : file.to_s
+      params["files[#{index}]"] = uuid
+    end
+
+    if options[:signature] || options['signature']
+      params['signature'] =
+        (options[:signature] || options['signature']).to_s
+    end
+    params['expire'] = (options[:expire] || options['expire']).to_s if options[:expire] || options['expire']
+
+    params
+  end
+end

data/lib/uploadcare/api/upload.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'ipaddr'
+require 'mime/types'
+require 'resolv'
+require 'securerandom'
+require 'uri'
+require 'addressable/uri'
+
+# Base client for the Uploadcare Upload API.
+#
+# Provides HTTP methods for upload endpoints using multipart/form-data encoding.
+# Authentication is handled via public key in request parameters (no HMAC signing).
+#
+# Endpoint classes are accessed via lazy-loaded accessors:
+#   upload = Uploadcare::Api::Upload.new(config: config)
+#   upload.files.direct(file: file_obj)
+#   upload.groups.create(files: ["uuid1", "uuid2"])
+#
+# @see https://uploadcare.com/api-refs/upload-api/
+class Uploadcare::Api::Upload
+  include Uploadcare::Internal::ErrorHandler
+  include Uploadcare::Internal::ThrottleHandler
+
+  # @return [Uploadcare::Configuration]
+  attr_reader :config
+
+  # @return [Faraday::Connection]
+  attr_reader :connection
+
+  # Initialize a new Upload API client.
+  #
+  # @param config [Uploadcare::Configuration] Configuration object
+  def initialize(config: Uploadcare.configuration)
+    @config = config
+    @memo_mutex = Mutex.new
+    @connection = Faraday.new(url: config.upload_api_root) do |conn|
+      conn.request :multipart
+      conn.request :url_encoded
+      conn.response :json, content_type: /\bjson$/
+      conn.response :raise_error
+      conn.response :logger, config.logger, bodies: false, headers: false if ENV['DEBUG']
+      conn.adapter Faraday.default_adapter
+    end
+  end
+
+  # --- Endpoint accessors ---
+
+  # @return [Uploadcare::Api::Upload::Files] File upload operations
+  def files
+    memoized(:@files) { Uploadcare::Api::Upload::Files.new(upload: self) }
+  end
+
+  # @return [Uploadcare::Api::Upload::Groups] Group operations via Upload API
+  def groups
+    memoized(:@groups) { Uploadcare::Api::Upload::Groups.new(upload: self) }
+  end
+
+  # --- HTTP methods ---
+
+  # Make a GET request to the Upload API wrapped in a Result.
+  #
+  # @param path [String] API endpoint path
+  # @param params [Hash] Query parameters
+  # @param headers [Hash] Additional request headers
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result]
+  def get(path:, params: {}, headers: {}, request_options: {})
+    Uploadcare::Result.capture do
+      make_request(:get, path, params, headers, request_options)
+    end
+  end
+
+  # Make a POST request to the Upload API wrapped in a Result.
+  #
+  # @param path [String] API endpoint path
+  # @param params [Hash] Request body parameters
+  # @param headers [Hash] Additional request headers
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result]
+  def post(path:, params: {}, headers: {}, request_options: {})
+    Uploadcare::Result.capture do
+      make_request(:post, path, params, headers, request_options)
+    end
+  end
+
+  # Upload binary data to a presigned URL (for multipart uploads).
+  #
+  # @param presigned_url [String] Presigned URL from multipart_start
+  # @param part_data [String, IO] Binary data for this part
+  # @param max_retries [Integer] Maximum retry attempts (default: 3)
+  # @param timeout [Integer, nil] Request timeout in seconds
+  # @param open_timeout [Integer, nil] Open timeout in seconds
+  # @return [Boolean] true on success
+  # @raise [Uploadcare::Exception::MultipartUploadError] on failure after retries
+  def upload_part_to_url(presigned_url, part_data, max_retries: 3, timeout: nil, open_timeout: nil)
+    uri = validated_presigned_uri(presigned_url)
+    retries = 0
+    begin
+      conn = Faraday.new(url: "#{uri.scheme}://#{uri.host}") do |f|
+        f.adapter Faraday.default_adapter
+      end
+
+      data = part_data.respond_to?(:read) ? part_data.read : part_data
+      response = upload_part_request(
+        conn: conn, request_uri: uri.request_uri, data: data, timeout: timeout, open_timeout: open_timeout
+      )
+      raise_multipart_upload_error("Failed to upload part: HTTP #{response.status}") unless success_response?(response)
+
+      true
+    rescue StandardError => e
+      retry_part_upload_or_raise!(error: e, retries: retries, max_retries: max_retries)
+      retries += 1
+      retry
+    end
+  end
+
+  protected
+
+  def make_request(method, path, params = {}, headers = {}, request_options = {})
+    handle_throttling(max_attempts: request_options[:max_throttle_attempts]) do
+      response = connection.public_send(method, path) do |req|
+        prepare_request(req, method, path, params, headers, request_options)
+      end
+      handle_response(response)
+    end
+  rescue Faraday::Error => e
+    handle_error(e)
+  end
+
+  def handle_response(response)
+    return handle_error_response(response) unless success_response?(response)
+
+    parse_success_response(response)
+  rescue JSON::ParserError => e
+    handle_json_error(e, response)
+  end
+
+  private
+
+  def prepare_request(req, method, path, params, headers, request_options)
+    upcase_method_name = method.to_s.upcase
+    uri = path
+    uri = build_request_uri(path, params, upcase_method_name) if upcase_method_name == 'GET'
+
+    prepare_headers(req, upcase_method_name, uri, headers)
+    prepare_body_or_params(req, upcase_method_name, params)
+    apply_request_options(req, request_options)
+  end
+
+  def build_request_uri(path, params, method)
+    return path unless method == 'GET' && params.is_a?(Hash) && !params.empty?
+
+    uri = Addressable::URI.parse(path)
+    uri.query_values = params
+    uri.to_s
+  end
+
+  def prepare_headers(req, _method, _uri, headers)
+    req.headers['User-Agent'] ||= Uploadcare::Internal::UserAgent.call(config: config)
+    req.headers.merge!(headers)
+  end
+
+  def prepare_body_or_params(req, method, params)
+    if method == 'GET'
+      req.params.update(params) unless params.empty?
+    else
+      req.body = params unless params.empty?
+    end
+  end
+
+  def apply_request_options(req, request_options)
+    return if request_options.nil? || request_options.empty?
+
+    req.options.timeout = request_options[:timeout] if request_options[:timeout]
+    req.options.open_timeout = request_options[:open_timeout] if request_options[:open_timeout]
+  end
+
+  def success_response?(response)
+    response.status >= 200 && response.status < 300
+  end
+
+  def handle_error_response(response)
+    raise Uploadcare::Exception::UploadError, "Upload API error: #{response.status} #{response.body}"
+  end
+
+  def parse_success_response(response)
+    return {} if response.body.nil? || (response.body.is_a?(String) && response.body.strip.empty?)
+    return response.body if response.body.is_a?(Hash)
+
+    JSON.parse(response.body)
+  end
+
+  def handle_json_error(error, response)
+    config.logger&.error("Invalid JSON response: #{error.message}")
+    success_response?(response) ? {} : response.body
+  end
+
+  def validated_presigned_uri(url)
+    uri = URI.parse(url.to_s)
+    raise ArgumentError, 'presigned_url must use HTTPS' unless uri.is_a?(URI::HTTPS)
+    raise ArgumentError, 'presigned_url host is required' if uri.host.to_s.empty?
+    raise ArgumentError, 'presigned_url cannot target localhost' if local_hostname?(uri.host)
+    raise ArgumentError, 'presigned_url cannot target a private address' if private_host?(uri.host)
+
+    uri
+  rescue URI::InvalidURIError => e
+    raise ArgumentError, "Invalid presigned_url: #{e.message}"
+  end
+
+  def local_hostname?(host)
+    normalized_host = host.to_s.downcase
+    normalized_host == 'localhost' || normalized_host.end_with?('.localhost', '.local')
+  end
+
+  def private_host?(host)
+    return private_ip?(host) if ip_literal?(host)
+
+    Resolv.getaddresses(host).any? { |address| private_ip?(address) }
+  rescue Resolv::ResolvError, SocketError
+    false
+  end
+
+  def ip_literal?(host)
+    IPAddr.new(host)
+    true
+  rescue IPAddr::InvalidAddressError
+    false
+  end
+
+  def private_ip?(address)
+    ip = IPAddr.new(address)
+    return true if ip.loopback?
+    return true if ip.link_local?
+
+    ip.private?
+  rescue IPAddr::InvalidAddressError
+    false
+  end
+
+  def upload_part_request(conn:, request_uri:, data:, timeout:, open_timeout:)
+    conn.put(request_uri) do |req|
+      req.headers['Content-Type'] = 'application/octet-stream'
+      req.options.timeout = timeout if timeout
+      req.options.open_timeout = open_timeout if open_timeout
+      req.body = data
+    end
+  end
+
+  def retry_part_upload_or_raise!(error:, retries:, max_retries:)
+    if retries >= max_retries
+      raise_multipart_upload_error("Failed to upload part after #{max_retries} retries: #{error.message}")
+    end
+
+    sleep(2**retries)
+  end
+
+  def raise_multipart_upload_error(message)
+    raise Uploadcare::Exception::MultipartUploadError, message
+  end
+
+  def memoized(ivar)
+    cached = instance_variable_get(ivar)
+    return cached if cached
+
+    @memo_mutex.synchronize do
+      instance_variable_get(ivar) || instance_variable_set(ivar, yield)
+    end
+  end
+end