uploadcare-ruby 4.4.2 → 5.0.0.rc1

data/lib/uploadcare/collections/paginated.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+# Paginated collection for API list responses.
+#
+# Wraps paginated API responses and provides methods for navigating between pages.
+# Implements Enumerable for easy iteration over resources.
+#
+# @example Iterating over resources
+#   files = client.files.list
+#   files.each { |file| puts file.uuid }
+#
+# @example Navigating pages
+#   files = client.files.list
+#   while files
+#     files.each { |file| process(file) }
+#     files = files.next_page
+#   end
+#
+# @example Fetching all resources
+#   all_files = client.files.list.all
+class Uploadcare::Collections::Paginated
+  include Enumerable
+
+  # @return [Array] Array of resource objects in the current page
+  attr_reader :resources
+
+  # @return [String, nil] URL for the next page, or nil if on last page
+  attr_reader :next_page_url
+
+  # @return [String, nil] URL for the previous page, or nil if on first page
+  attr_reader :previous_page_url
+
+  # @return [Integer] Number of items per page
+  attr_reader :per_page
+
+  # @return [Integer] Total number of items across all pages
+  attr_reader :total
+
+  # @return [Object] API endpoint client for fetching additional pages
+  attr_reader :api_client
+
+  # @return [Class] Resource class for instantiating items from raw data
+  attr_reader :resource_class
+
+  # @return [Uploadcare::Client, nil] Client for resource instantiation
+  attr_reader :client
+
+  # @return [Hash] Request options used when fetching pages
+  attr_reader :request_options
+
+  # Initialize a new Paginated collection.
+  #
+  # @param params [Hash] Collection parameters
+  # @option params [Array] :resources Array of resource objects
+  # @option params [String, nil] :next_page URL for next page
+  # @option params [String, nil] :previous_page URL for previous page
+  # @option params [Integer] :per_page Items per page
+  # @option params [Integer] :total Total item count
+  # @option params [Object] :api_client API client for fetching pages
+  # @option params [Class] :resource_class Class for instantiating resources
+  # @option params [Uploadcare::Client, nil] :client Client for resources
+  # @option params [Hash] :request_options Request options for subsequent page fetches
+  def initialize(params = {})
+    @resources = params[:resources] || []
+    @next_page_url = params[:next_page]
+    @previous_page_url = params[:previous_page]
+    @per_page = params[:per_page]
+    @total = params[:total]
+    @api_client = params[:api_client]
+    @resource_class = params[:resource_class]
+    @client = params[:client]
+    @request_options = params[:request_options] || {}
+  end
+
+  # Iterate over resources in the current page.
+  #
+  # @yield [resource] Block to execute for each resource
+  # @yieldparam resource [Object] A resource object
+  def each(&)
+    @resources.each(&)
+  end
+
+  # Fetch the next page of resources.
+  #
+  # @return [Uploadcare::Collections::Paginated, nil] Next page, or nil if on last page
+  def next_page
+    fetch_page(@next_page_url)
+  end
+
+  # Fetch the previous page of resources.
+  #
+  # @return [Uploadcare::Collections::Paginated, nil] Previous page, or nil if on first page
+  def previous_page
+    fetch_page(@previous_page_url)
+  end
+
+  # Fetch all resources across all pages.
+  #
+  # @param limit [Integer, nil] Maximum number of resources to return
+  # @return [Array<Object>] All resources up to the requested limit
+  def all(limit: nil)
+    return [] if limit && limit <= 0
+
+    collection = self
+    items = []
+    remaining = limit
+
+    while collection
+      page_items = collection.resources || []
+      if remaining
+        page_slice = page_items.first(remaining)
+        items.concat(page_slice)
+        remaining -= page_slice.length
+        break if remaining <= 0
+      else
+        items.concat(page_items)
+      end
+
+      collection = collection.next_page
+    end
+
+    items
+  end
+
+  private
+
+  def fetch_page(page_url)
+    return nil unless page_url
+
+    params = extract_params_from_url(page_url)
+    response = fetch_response(params)
+    build_paginated_collection(response)
+  end
+
+  def extract_params_from_url(page_url)
+    uri = URI.parse(page_url)
+    URI.decode_www_form(uri.query.to_s).to_h
+  end
+
+  def fetch_response(params)
+    Uploadcare::Result.unwrap(api_client.list(params: params, request_options: request_options))
+  end
+
+  def build_paginated_collection(response)
+    new_resources = build_resources(response['results'])
+
+    self.class.new(
+      resources: new_resources,
+      next_page: response['next'],
+      previous_page: response['previous'],
+      per_page: response['per_page'],
+      total: response['total'],
+      api_client: api_client,
+      resource_class: resource_class,
+      client: client,
+      request_options: request_options
+    )
+  end
+
+  def build_resources(results)
+    results.map { |data| resource_class.new(data, client) }
+  end
+end

data/lib/uploadcare/configuration.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# Configuration container for client defaults and per-client overrides.
+class Uploadcare::Configuration
+  attr_accessor :public_key, :secret_key, :auth_type, :multipart_size_threshold, :rest_api_root,
+                :upload_api_root, :max_request_tries, :base_request_sleep, :max_request_sleep, :sign_uploads,
+                :upload_signature_lifetime, :max_throttle_attempts, :upload_threads, :framework_data,
+                :file_chunk_size, :logger, :use_subdomains, :cdn_base_postfix, :default_cdn_base,
+                :multipart_chunk_size, :upload_timeout, :max_upload_retries
+
+  # Default configuration values used as the template for new instances.
+  DEFAULTS = {
+    public_key: nil,
+    secret_key: nil,
+    auth_type: 'Uploadcare',
+    multipart_size_threshold: 100 * 1024 * 1024,
+    rest_api_root: 'https://api.uploadcare.com',
+    upload_api_root: 'https://upload.uploadcare.com',
+    max_request_tries: 100,
+    base_request_sleep: 1,         # seconds
+    max_request_sleep: 60.0,       # seconds
+    sign_uploads: false,
+    upload_signature_lifetime: 30 * 60, # seconds
+    max_throttle_attempts: 5,
+    upload_threads: 2, # used for multiupload only ATM
+    framework_data: '',
+    file_chunk_size: 100,
+    logger: nil,
+    use_subdomains: false,
+    cdn_base_postfix: 'https://ucarecd.net/',
+    default_cdn_base: 'https://ucarecdn.com/',
+    multipart_chunk_size: 5 * 1024 * 1024, # 5MB chunks for multipart upload
+    upload_timeout: 60,            # seconds
+    max_upload_retries: 3          # retry failed uploads 3 times
+  }.freeze
+
+  # @param options [Hash] Configuration overrides
+  def initialize(**options)
+    values = DEFAULTS.merge(options)
+    values[:public_key] = ENV.fetch('UPLOADCARE_PUBLIC_KEY', '') unless options.key?(:public_key)
+    values[:secret_key] = ENV.fetch('UPLOADCARE_SECRET_KEY', '') unless options.key?(:secret_key)
+
+    values.each do |attribute, value|
+      send("#{attribute}=", value)
+    end
+    @logger ||= Logger.new($stdout)
+  end
+
+  # Build the deterministic subdomain prefix for the configured public key.
+  #
+  # @return [String]
+  def custom_cname
+    Uploadcare::CnameGenerator.generate_cname(public_key: public_key)
+  end
+
+  # Resolve the CDN base URL for this configuration.
+  #
+  # @return [String]
+  def cdn_base
+    return Uploadcare::CnameGenerator.cdn_base_postfix(config: self) if use_subdomains
+
+    default_cdn_base
+  end
+
+  # Clone this configuration with overrides.
+  #
+  # @param options [Hash]
+  # @return [Uploadcare::Configuration]
+  def with(**options)
+    self.class.new(**to_h, **options)
+  end
+
+  # Convert this configuration to a serializable hash.
+  #
+  # @return [Hash]
+  def to_h
+    DEFAULTS.keys.to_h { |attribute| [attribute, public_send(attribute)] }
+  end
+end

data/lib/uploadcare/exception/auth_error.rb

@@ -1,8 +1,4 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module Exception
-    # Invalid Auth configuration error
-    class AuthError < StandardError; end
-  end
-end
+# Invalid Auth configuration error
+class Uploadcare::Exception::AuthError < StandardError; end

data/lib/uploadcare/exception/configuration_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Standard error for invalid API configuration responses
+class Uploadcare::Exception::ConfigurationError < StandardError; end

data/lib/uploadcare/exception/conversion_error.rb

@@ -1,8 +1,4 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module Exception
-    # Standard error for invalid API conversion responses
-    class ConversionError < StandardError; end
-  end
-end
+# Standard error for invalid API conversion responses
+class Uploadcare::Exception::ConversionError < StandardError; end

data/lib/uploadcare/exception/invalid_request_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Specific error for invalid requests (400 Bad Request)
+class Uploadcare::Exception::InvalidRequestError < Uploadcare::Exception::RequestError; end

data/lib/uploadcare/exception/multipart_upload_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Raised when multipart upload fails
+class Uploadcare::Exception::MultipartUploadError < Uploadcare::Exception::UploadError; end

data/lib/uploadcare/exception/not_found_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Specific error for not found resources (404 Not Found)
+class Uploadcare::Exception::NotFoundError < Uploadcare::Exception::RequestError; end

data/lib/uploadcare/exception/request_error.rb

@@ -1,8 +1,4 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module Exception
-    # Standard error for invalid API responses
-    class RequestError < StandardError; end
-  end
-end
+# Standard error for invalid API responses
+class Uploadcare::Exception::RequestError < StandardError; end

data/lib/uploadcare/exception/retry_error.rb

@@ -1,8 +1,4 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module Exception
-    # Standard error to raise when needing to retry a request
-    class RetryError < StandardError; end
-  end
-end
+# Standard error to raise when needing to retry a request
+class Uploadcare::Exception::RetryError < StandardError; end

data/lib/uploadcare/exception/throttle_error.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module Exception
-    # Exception for throttled requests
-    class ThrottleError < StandardError
-      attr_reader :timeout
+# Exception for throttled requests
+class Uploadcare::Exception::ThrottleError < StandardError
+  attr_reader :timeout
 
-      # @param timeout [Float] Amount of seconds the request have been throttled for
-      def initialize(timeout = 10.0)
-        super
-        @timeout = timeout
-      end
-    end
+  # @param timeout [Float] Amount of seconds the request have been throttled for
+  def initialize(message = nil, timeout: 10.0)
+    super(message)
+    @timeout = timeout
   end
 end

data/lib/uploadcare/exception/unknown_status_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Raised when upload status is unknown
+class Uploadcare::Exception::UnknownStatusError < Uploadcare::Exception::UploadError; end

data/lib/uploadcare/exception/upload_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# General upload error
+class Uploadcare::Exception::UploadError < StandardError; end

data/lib/uploadcare/exception/upload_timeout_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Raised when upload times out
+class Uploadcare::Exception::UploadTimeoutError < Uploadcare::Exception::UploadError; end

data/lib/uploadcare/internal/authenticator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'time'
+
+# Handles authentication for Uploadcare REST API requests.
+#
+# Supports two authentication modes:
+# - Simple authentication: Basic auth with public_key:secret_key
+# - Secure authentication: signature-based authentication
+#
+# @example Using the authenticator
+#   authenticator = Uploadcare::Internal::Authenticator.new(config: config)
+#   headers = authenticator.headers('GET', '/files/', '')
+#
+# @see https://uploadcare.com/docs/api_reference/rest/requests_auth/
+class Uploadcare::Internal::Authenticator
+  BODY_DIGEST_NAME = 'MD5'
+  SIGNATURE_DIGEST_NAME = 'SHA1'
+
+  # @return [Hash] Default headers included in all requests
+  attr_reader :default_headers
+
+  # Initialize a new Authenticator.
+  #
+  # @param config [Uploadcare::Configuration] Configuration object with API credentials
+  def initialize(config:)
+    @config = config
+    @default_headers = {
+      'Accept' => 'application/vnd.uploadcare-v0.7+json',
+      'User-Agent' => Uploadcare::Internal::UserAgent.call(config: config)
+    }
+  end
+
+  # Generate authentication headers for an API request.
+  #
+  # @param http_method [String] HTTP method (GET, POST, PUT, DELETE)
+  # @param uri [String] Request URI path
+  # @param body [String] Request body content (default: '')
+  # @param content_type [String] Content-Type header value (default: 'application/json')
+  # @return [Hash] Headers hash including authentication
+  # @raise [Uploadcare::Exception::AuthError] if credentials are blank when using secure auth
+  def headers(http_method, uri, body = '', content_type = nil)
+    resolved_content_type = content_type || 'application/json'
+    raise Uploadcare::Exception::AuthError, 'Secret Key is blank.' if @config.secret_key.to_s.empty?
+
+    validate_public_key
+
+    return simple_auth_headers(resolved_content_type) if @config.auth_type == 'Uploadcare.Simple'
+
+    secure_auth_headers(http_method, uri, body, resolved_content_type)
+  end
+
+  private
+
+  def simple_auth_headers(content_type)
+    @default_headers.merge(
+      'Content-Type' => content_type,
+      'Authorization' => "#{@config.auth_type} #{@config.public_key}:#{@config.secret_key}"
+    )
+  end
+
+  def validate_public_key
+    return unless @config.public_key.nil? || @config.public_key.empty?
+
+    raise Uploadcare::Exception::AuthError, 'Public Key is blank.'
+  end
+
+  def secure_auth_headers(http_method, uri, body, content_type)
+    date = Time.now.gmtime.strftime('%a, %d %b %Y %H:%M:%S GMT')
+    signature = generate_signature(http_method, uri, body, content_type, date)
+    auth_headers = { 'Authorization' => "Uploadcare #{@config.public_key}:#{signature}", 'Date' => date }
+    @default_headers.merge('Content-Type' => content_type).merge(auth_headers)
+  end
+
+  def generate_signature(http_method, uri, body, content_type, date)
+    normalized_uri = uri.start_with?('/') ? uri : "/#{uri}"
+
+    sign_string = [
+      http_method.upcase,
+      body_digest(body),
+      content_type,
+      date,
+      normalized_uri
+    ].join("\n")
+
+    OpenSSL::HMAC.hexdigest(
+      signature_digest,
+      @config.secret_key,
+      sign_string
+    )
+  end
+
+  def body_digest(body)
+    OpenSSL::Digest.new(BODY_DIGEST_NAME).hexdigest(body)
+  end
+
+  def signature_digest
+    OpenSSL::Digest.new(SIGNATURE_DIGEST_NAME)
+  end
+end

data/lib/uploadcare/internal/error_handler.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+# Handles API errors and converts them to appropriate exceptions.
+#
+# This module is included in API base classes to provide consistent error handling
+# across all API requests. It parses error responses and raises typed exceptions.
+#
+# @see Uploadcare::Api::Rest
+# @see Uploadcare::Api::Upload
+module Uploadcare::Internal::ErrorHandler
+  # Handle a failed API request and raise an appropriate exception.
+  #
+  # Parses the error response and raises a typed exception based on the HTTP status code.
+  # Also handles Upload API errors which return status 200 with error details in the body.
+  #
+  # @param error [Faraday::Error] The error from the HTTP client
+  # @raise [Uploadcare::Exception::InvalidRequestError] for 400 Bad Request
+  # @raise [Uploadcare::Exception::NotFoundError] for 404 Not Found
+  # @raise [Uploadcare::Exception::ThrottleError] for 429 Too Many Requests
+  # @raise [Uploadcare::Exception::RequestError] for other error statuses
+  def handle_error(error)
+    response = error.response
+    return raise Uploadcare::Exception::RequestError, error.message if response.nil?
+
+    catch_upload_errors(response)
+
+    error_message = extract_error_message(response)
+    raise_status_error(response, error_message)
+  end
+
+  private
+
+  # Extract error message from response body.
+  #
+  # @param response [Hash] Response hash with :body key
+  # @return [String] Extracted error message
+  def extract_error_message(response)
+    parsed = JSON.parse(response[:body].to_s)
+    return parsed['detail'] if parsed.is_a?(Hash) && parsed['detail']
+    return parsed.map { |k, v| "#{k}: #{v}" }.join('; ') if parsed.is_a?(Hash)
+
+    parsed.to_s
+  rescue JSON::ParserError
+    response[:body].to_s
+  end
+
+  # Raise appropriate error based on HTTP status code.
+  #
+  # @param response [Hash] Response hash with :status key
+  # @param message [String] Error message
+  # @raise [Uploadcare::Exception::InvalidRequestError] for 400
+  # @raise [Uploadcare::Exception::NotFoundError] for 404
+  # @raise [Uploadcare::Exception::ThrottleError] for 429
+  # @raise [Uploadcare::Exception::RequestError] for other statuses
+  def raise_status_error(response, message)
+    status = response.is_a?(Hash) ? response[:status] : response
+    raise Uploadcare::Exception::InvalidRequestError, message if status == 400
+    raise Uploadcare::Exception::NotFoundError, message if status == 404
+    return raise_throttle_error(response, message) if status == 429
+
+    raise Uploadcare::Exception::RequestError, message
+  end
+
+  # Upload API returns its errors with code 200, and stores its actual code and details
+  # within the response message. This method detects that and raises an appropriate error.
+  #
+  # @param response [Hash] Response hash
+  def catch_upload_errors(response)
+    return unless response[:status] == 200
+
+    parsed_response = JSON.parse(response[:body].to_s)
+    error = parsed_response['error'] if parsed_response.is_a?(Hash)
+    raise Uploadcare::Exception::RequestError, error if error
+  rescue JSON::ParserError
+    nil
+  end
+
+  # Raise a throttle error with retry-after timeout.
+  #
+  # @param response [Hash] Response hash
+  # @param message [String] Error message
+  # @raise [Uploadcare::Exception::ThrottleError]
+  def raise_throttle_error(response, message)
+    headers = response.is_a?(Hash) ? response[:headers] : nil
+    retry_after = headers && (headers['retry-after'] || headers['Retry-After'])
+    timeout =
+      if retry_after.to_s.match?(/\A\d+(\.\d+)?\z/)
+        retry_after.to_f
+      else
+        begin
+          [Time.httpdate(retry_after.to_s) - Time.now, 0].max
+        rescue ArgumentError
+          0
+        end
+      end
+    timeout = 10.0 if timeout <= 0
+    raise Uploadcare::Exception::ThrottleError.new(message, timeout: timeout)
+  end
+end

data/lib/uploadcare/internal/signature_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+# Generates HMAC-SHA256 signatures for signed uploads.
+#
+# Used when `config.sign_uploads` is enabled to generate authentication
+# signatures for Upload API requests.
+#
+# @example
+#   Uploadcare::Internal::SignatureGenerator.call(config: config)
+#   # => { signature: "abc123...", expire: 1234567890 }
+class Uploadcare::Internal::SignatureGenerator
+  # Generate signature params for signed uploads.
+  #
+  # @param config [Uploadcare::Configuration] Configuration with secret key and lifetime
+  # @return [Hash] Hash with :signature and :expire keys
+  # @raise [ArgumentError] if secret_key is empty or lifetime is invalid
+  def self.call(config: Uploadcare.configuration)
+    secret_key = config.secret_key.to_s
+    lifetime = config.upload_signature_lifetime
+    raise ArgumentError, 'secret_key is required for upload signature' if secret_key.empty?
+    unless lifetime.is_a?(Integer) && lifetime.positive?
+      raise ArgumentError, 'upload_signature_lifetime must be a positive Integer'
+    end
+
+    expires_at = Time.now.to_i + lifetime
+    signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, expires_at.to_s)
+    { signature: signature, expire: expires_at }
+  end
+end

data/lib/uploadcare/internal/throttle_handler.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Handles API rate limiting (throttling) with automatic retry.
+#
+# This module is included in API base classes to provide automatic retry logic
+# when the API returns a throttle error (HTTP 429). It respects the retry-after
+# header (via ThrottleError#timeout) and implements exponential backoff.
+#
+# @see https://uploadcare.com/docs/api_reference/rest/rate_limiting/
+module Uploadcare::Internal::ThrottleHandler
+  # Execute a block with automatic retry on throttle errors.
+  #
+  # Wraps an HTTP request and automatically retries if a ThrottleError is raised.
+  # Sleep duration between retries is determined by the error's timeout value
+  # with exponential backoff.
+  #
+  # @param max_attempts [Integer, nil] Maximum retry attempts (defaults to config value)
+  # @yield Block containing the HTTP request to execute
+  # @return [Object] The result of the block execution
+  # @raise [Uploadcare::Exception::ThrottleError] if max retry attempts exceeded
+  def handle_throttling(max_attempts: nil)
+    attempts = max_attempts
+    if attempts.nil?
+      attempts = respond_to?(:config) ? config.max_throttle_attempts : Uploadcare.configuration.max_throttle_attempts
+    end
+    attempts = attempts.to_i
+    raise ArgumentError, 'max_attempts must be at least 1' if attempts < 1
+
+    (attempts - 1).times do |index|
+      return yield
+    rescue Uploadcare::Exception::ThrottleError => e
+      sleep(e.timeout * (2**index))
+    end
+    yield
+  end
+end