durable_huggingface_hub 0.2.0

data/lib/durable_huggingface_hub/utils/progress.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module DurableHuggingfaceHub
+  module Utils
+    # Progress tracking for long-running operations.
+    #
+    # This module provides a simple progress tracking mechanism for operations
+    # like file downloads. It supports custom callbacks for progress updates.
+    #
+    # @example Basic progress tracking
+    #   progress = Progress.new(total: 1000)
+    #   progress.update(100)  # 10% complete
+    #   progress.update(500)  # 50% complete
+    #   progress.finish
+    #
+    # @example With callback
+    #   progress = Progress.new(total: 1000) do |current, total, percentage|
+    #     puts "Progress: #{percentage.round(1)}% (#{current}/#{total})"
+    #   end
+    #   progress.update(500)  # Calls callback
+    class Progress
+      # @return [Integer, nil] Total size/count expected
+      attr_reader :total
+
+      # @return [Integer] Current progress
+      attr_reader :current
+
+       # @return [Time] Start time
+       attr_reader :start_time
+
+       # Creates a new Progress tracker.
+       #
+       # @param total [Integer, nil] Total size/count expected
+       # @param callback [Proc, nil] Callback to invoke on updates
+       # @yield [current, total, percentage] Optional block called on updates
+       # @yieldparam current [Integer] Current progress
+       # @yieldparam total [Integer, nil] Total expected
+       # @yieldparam percentage [Float] Percentage complete (0-100)
+       # @raise [ValidationError] If total is provided but not positive
+       def initialize(total: nil, callback: nil, &block)
+         validate_total(total)
+         @total = total
+         @current = 0
+         @start_time = Time.now
+         @callback = callback || block
+         @finished = false
+       end
+
+       # Updates the progress.
+       #
+       # @param amount [Integer] Amount to add to current progress
+       # @return [void]
+       # @raise [ValidationError] If amount is negative
+       def update(amount)
+         return if @finished
+
+         validate_amount(amount)
+         @current += amount
+         notify_callback
+       end
+
+       # Sets the current progress to a specific value.
+       #
+       # @param value [Integer] New current value
+       # @return [void]
+       # @raise [ValidationError] If value is negative
+       def set(value)
+         return if @finished
+
+         validate_value(value)
+         @current = value
+         notify_callback
+       end
+
+      # Marks the progress as finished.
+      #
+      # @return [void]
+      def finish
+        return if @finished
+
+        @finished = true
+        @current = @total if @total
+        notify_callback
+      end
+
+      # Checks if progress is finished.
+      #
+      # @return [Boolean] True if finished
+      def finished?
+        @finished
+      end
+
+      # Calculates the percentage complete.
+      #
+      # @return [Float, nil] Percentage (0-100) or nil if total unknown
+      def percentage
+        return nil unless @total&.positive?
+
+        (@current.to_f / @total * 100).round(2)
+      end
+
+      # Calculates elapsed time.
+      #
+      # @return [Float] Elapsed seconds
+      def elapsed
+        Time.now - @start_time
+      end
+
+       # Estimates time remaining.
+       #
+       # @return [Float, nil] Estimated seconds remaining or nil if unknown
+       def eta
+         return nil unless @total&.positive? && @current.positive?
+
+         elapsed_time = elapsed
+         return nil if elapsed_time <= 0
+
+         rate = @current.to_f / elapsed_time
+         remaining = @total - @current
+         remaining / rate
+       end
+
+       # Resets the progress tracker to its initial state.
+       #
+       # @return [void]
+       def reset
+         @current = 0
+         @start_time = Time.now
+         @finished = false
+         notify_callback
+       end
+
+       # Returns a string representation of the progress.
+       #
+       # @return [String] String representation
+       def to_s
+         if @total
+           "#{@current}/#{@total} (#{percentage&.round(1)}%)"
+         else
+           "#{@current} completed"
+         end
+       end
+
+       private
+
+       # Validates the total parameter.
+       #
+       # @param total [Integer, nil] Total value to validate
+       # @raise [ValidationError] If total is provided but not positive
+       def validate_total(total)
+         return if total.nil?
+
+         unless total.is_a?(Integer) && total.positive?
+           raise ValidationError.new("total", "Total must be a positive integer, got #{total.inspect}")
+         end
+       end
+
+       # Validates the amount parameter.
+       #
+       # @param amount [Integer] Amount to validate
+       # @raise [ValidationError] If amount is negative
+       def validate_amount(amount)
+         unless amount.is_a?(Integer) && amount >= 0
+           raise ValidationError.new("amount", "Amount must be a non-negative integer, got #{amount.inspect}")
+         end
+       end
+
+       # Validates the value parameter.
+       #
+       # @param value [Integer] Value to validate
+       # @raise [ValidationError] If value is negative
+       def validate_value(value)
+         unless value.is_a?(Integer) && value >= 0
+           raise ValidationError.new("value", "Value must be a non-negative integer, got #{value.inspect}")
+         end
+       end
+
+       # Notifies the callback of progress update.
+       def notify_callback
+         return unless @callback
+
+         @callback.call(@current, @total, percentage)
+       end
+     end
+
+     # No-op progress tracker for when progress tracking is disabled.
+     class NullProgress
+       def update(_amount); end
+
+       def set(_value); end
+
+       def finish; end
+
+       def finished?
+         false
+       end
+
+       def percentage
+         nil
+       end
+
+       def elapsed
+         0
+       end
+
+       def eta
+         nil
+       end
+
+       def reset; end
+
+       def to_s
+         "NullProgress"
+       end
+     end
+  end
+end

data/lib/durable_huggingface_hub/utils/retry.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module DurableHuggingfaceHub
+  module Utils
+    # Retry logic with exponential backoff for HTTP requests.
+    #
+    # This module provides retry functionality for handling transient failures
+    # in HTTP requests, with configurable retry attempts and exponential backoff.
+    module Retry
+      # Default maximum number of retry attempts
+      DEFAULT_MAX_RETRIES = 3
+
+      # Default initial delay in seconds
+      DEFAULT_INITIAL_DELAY = 1
+
+      # Maximum delay between retries (in seconds)
+      MAX_DELAY = 60
+
+      # Multiplier for exponential backoff
+      BACKOFF_MULTIPLIER = 2
+
+      # HTTP status codes that should trigger a retry
+      RETRYABLE_STATUS_CODES = [
+        408, # Request Timeout
+        429, # Too Many Requests
+        500, # Internal Server Error
+        502, # Bad Gateway
+        503, # Service Unavailable
+        504  # Gateway Timeout
+      ].freeze
+
+      # Errors that should trigger a retry
+      RETRYABLE_ERRORS = [
+        Faraday::TimeoutError,
+        Faraday::ConnectionFailed,
+        Faraday::SSLError
+      ].freeze
+
+      # Executes a block with retry logic.
+      #
+      # @param max_retries [Integer] Maximum number of retry attempts (must be >= 0)
+      # @param initial_delay [Float] Initial delay in seconds (must be > 0)
+      # @param logger [Logger, nil] Logger for retry messages
+      # @yield Block to execute with retry
+      # @yieldreturn Result of the block
+      # @return Result of the block if successful
+      # @raise [ArgumentError] If parameters are invalid
+      # @raise Last exception if all retries exhausted
+      #
+      # @example Basic usage
+      #   result = Retry.with_retry do
+      #     perform_http_request
+      #   end
+      #
+      # @example Custom retry configuration
+      #   result = Retry.with_retry(max_retries: 5, initial_delay: 2) do
+      #     risky_operation
+      #   end
+      def self.with_retry(max_retries: DEFAULT_MAX_RETRIES, initial_delay: DEFAULT_INITIAL_DELAY, logger: nil)
+        # Validate parameters
+        validate_max_retries(max_retries)
+        validate_initial_delay(initial_delay)
+
+        attempt = 0
+        last_error = nil
+
+        loop do
+          begin
+            return yield
+          rescue => e
+            attempt += 1
+            last_error = e
+
+            # Check if error is retryable
+            unless retryable_error?(e)
+              raise e
+            end
+
+            # Check if we've exhausted retries
+            if attempt > max_retries
+              logger&.error("Max retries (#{max_retries}) exhausted for #{e.class}: #{e.message}")
+              raise e
+            end
+
+            # Calculate delay with exponential backoff
+            delay = calculate_delay(attempt, initial_delay)
+
+            # Log retry attempt
+            logger&.warn("Retry attempt #{attempt}/#{max_retries} after #{delay}s due to #{e.class}: #{e.message}")
+
+            # Wait before retrying
+            sleep(delay)
+          end
+        end
+      end
+
+      # Checks if an error should trigger a retry.
+      #
+      # @param error [Exception] The error to check
+      # @return [Boolean] True if error is retryable
+      def self.retryable_error?(error)
+        # Check if it's a known retryable error class
+        return true if RETRYABLE_ERRORS.any? { |klass| error.is_a?(klass) }
+
+        # Check if it's an HTTP error with retryable status
+        if error.is_a?(HfHubHTTPError) && error.status_code
+          return RETRYABLE_STATUS_CODES.include?(error.status_code)
+        end
+
+        # Check Faraday response errors
+        if error.respond_to?(:response) && error.response
+          status = error.response[:status]
+          return RETRYABLE_STATUS_CODES.include?(status) if status
+        end
+
+        false
+      end
+
+      # Calculates the delay for a retry attempt using exponential backoff.
+      #
+      # @param attempt [Integer] Current attempt number (1-based)
+      # @param initial_delay [Float] Initial delay in seconds
+      # @return [Float] Delay in seconds (capped at MAX_DELAY)
+      #
+      # @example
+      #   Retry.calculate_delay(1, 1.0)  # => 1.0
+      #   Retry.calculate_delay(2, 1.0)  # => 2.0
+      #   Retry.calculate_delay(3, 1.0)  # => 4.0
+      #   Retry.calculate_delay(4, 1.0)  # => 8.0
+       def self.calculate_delay(attempt, initial_delay)
+         # Exponential backoff: initial_delay * (2 ^ (attempt - 1))
+         delay = initial_delay * (BACKOFF_MULTIPLIER**(attempt - 1))
+
+         # Cap at maximum delay
+         [delay, MAX_DELAY].min
+       end
+
+       # Validates the max_retries parameter.
+       #
+       # @param max_retries [Integer] Maximum number of retry attempts
+       # @raise [ArgumentError] If max_retries is invalid
+       # @private
+       def self.validate_max_retries(max_retries)
+         unless max_retries.is_a?(Integer) && max_retries >= 0
+           raise ArgumentError, "max_retries must be a non-negative integer, got #{max_retries.inspect}"
+         end
+       end
+       private_class_method :validate_max_retries
+
+       # Validates the initial_delay parameter.
+       #
+       # @param initial_delay [Numeric] Initial delay in seconds
+       # @raise [ArgumentError] If initial_delay is invalid
+       # @private
+       def self.validate_initial_delay(initial_delay)
+         unless initial_delay.is_a?(Numeric) && initial_delay > 0
+           raise ArgumentError, "initial_delay must be a positive number, got #{initial_delay.inspect}"
+         end
+       end
+       private_class_method :validate_initial_delay
+     end
+   end
+ end

data/lib/durable_huggingface_hub/utils/validators.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module DurableHuggingfaceHub
+  module Utils
+    # Input validation utilities for HuggingFace Hub parameters.
+    #
+    # This module provides validation functions for repository IDs, revisions,
+    # filenames, and other user inputs to ensure they meet HuggingFace Hub requirements.
+    module Validators
+      # Maximum length for repository ID
+      MAX_REPO_ID_LENGTH = 96
+
+       # Validates a repository ID format.
+       #
+       # Rules:
+       # - Between 1 and 96 characters
+       # - Either "repo_name" or "namespace/repo_name"
+       # - Contains only [a-zA-Z0-9] or "-", "_", "."
+       # - Cannot have "--" or ".." sequences
+       # - Cannot end with ".git"
+       # - Name parts cannot start or end with ".", "-", or "_"
+       #
+       # @param repo_id [String] Repository ID to validate
+       # @param repo_type [String, nil] Repository type (optional, for error messages)
+       # @return [String] The validated repo_id
+       # @raise [ValidationError] If repo_id is invalid
+       #
+       # @example Valid repository IDs
+       #   Validators.validate_repo_id("bert-base-uncased")
+       #   Validators.validate_repo_id("huggingface/transformers")
+       #   Validators.validate_repo_id("my-org/my.model-v2")
+       #
+       # @example Invalid repository IDs
+       #   Validators.validate_repo_id("")  # raises ValidationError
+       #   Validators.validate_repo_id("foo--bar")  # raises ValidationError
+       #   Validators.validate_repo_id("foo.git")  # raises ValidationError
+       def self.validate_repo_id(repo_id, repo_type: nil)
+         if repo_id.nil?
+           raise ValidationError.new("repo_id", "Repository ID cannot be empty")
+         end
+
+         unless repo_id.is_a?(String)
+           raise ValidationError.new("repo_id", "Repository ID must be a string, not #{repo_id.class}: '#{repo_id}'")
+         end
+
+         if repo_id.empty?
+           raise ValidationError.new("repo_id", "Repository ID cannot be empty")
+         end
+
+         if repo_id.length > MAX_REPO_ID_LENGTH
+           raise ValidationError.new("repo_id", "Repository ID is too long (max #{MAX_REPO_ID_LENGTH} characters)")
+         end
+
+         # Check for multiple slashes
+         if repo_id.count("/") > 1
+           raise ValidationError.new("repo_id", "Repository ID must be in format 'repo_name' or 'namespace/repo_name': '#{repo_id}'")
+         end
+
+         # Check for "--" and ".." sequences
+         if repo_id.include?("--") || repo_id.include?("..")
+           raise ValidationError.new("repo_id", "Cannot have -- or .. in repo_id: '#{repo_id}'")
+         end
+
+         # Check for .git suffix
+         if repo_id.end_with?(".git")
+           raise ValidationError.new("repo_id", "Repository ID cannot end with '.git': '#{repo_id}'")
+         end
+
+         # Validate with regex pattern (equivalent to Python REPO_ID_REGEX)
+         unless repo_id.match?(/\A(\b[\w\-.]+\b\/)?\b[\w\-.]{1,96}\b\z/)
+           raise ValidationError.new("repo_id", "Repository ID must use alphanumeric chars, '-', '_' or '.'. The name cannot start or end with '-' or '.' and the maximum length is 96: '#{repo_id}'")
+         end
+
+         # Additional validation for namespace/repo format
+         if repo_id.include?("/")
+           namespace, name = repo_id.split("/", 2)
+
+           if namespace.empty? || name.empty?
+             raise ValidationError.new("repo_id", "Both namespace and name must be non-empty")
+           end
+
+           # Validate no leading/trailing special chars in parts
+           [namespace, name].each do |part|
+             if part.start_with?(".", "-", "_") || part.end_with?(".", "-", "_")
+               raise ValidationError.new("repo_id", "Repository name parts cannot start or end with '.', '-', or '_'")
+             end
+           end
+         elsif repo_id.start_with?(".", "-", "_") || repo_id.end_with?(".", "-", "_")
+           raise ValidationError.new("repo_id", "Repository name cannot start or end with '.', '-', or '_'")
+         end
+
+         repo_id
+       end
+
+      # Validates a revision (branch, tag, or commit SHA).
+      #
+      # Valid formats:
+      # - Branch names: "main", "dev", "feature/my-feature"
+      # - Tags: "v1.0.0", "release-2023"
+      # - Commit SHAs: 40 hexadecimal characters
+      #
+      # @param revision [String] Revision to validate
+      # @return [String] The validated revision
+      # @raise [ValidationError] If revision is invalid
+      #
+      # @example
+      #   Validators.validate_revision("main")
+      #   Validators.validate_revision("v1.0.0")
+      #   Validators.validate_revision("a" * 40)  # commit SHA
+      def self.validate_revision(revision)
+        if revision.nil? || revision.empty?
+          raise ValidationError.new("revision", "Revision cannot be empty")
+        end
+
+        # Check length (reasonable max for branch/tag names)
+        if revision.length > 255
+          raise ValidationError.new("revision", "Revision name is too long")
+        end
+
+        # If it looks like a commit SHA (40 hex chars), validate that
+        if revision.match?(Constants::REGEX_COMMIT_OID)
+          return revision
+        end
+
+        # For branch/tag names, allow alphanumeric, hyphen, underscore, dot, slash
+        unless revision.match?(/\A[a-zA-Z0-9._\/-]+\z/)
+          raise ValidationError.new("revision", "Revision contains invalid characters")
+        end
+
+        # Disallow leading/trailing slashes
+        if revision.start_with?("/") || revision.end_with?("/")
+          raise ValidationError.new("revision", "Revision cannot start or end with '/'")
+        end
+
+        revision
+      end
+
+      # Validates a filename for use in repository paths.
+      #
+      # Ensures filename doesn't contain path traversal sequences or
+      # other potentially dangerous patterns.
+      #
+      # @param filename [String] Filename to validate
+      # @return [String] The validated filename
+      # @raise [ValidationError] If filename is unsafe
+      #
+      # @example Valid filenames
+      #   Validators.validate_filename("config.json")
+      #   Validators.validate_filename("models/pytorch_model.bin")
+      #   Validators.validate_filename("data/train.csv")
+      #
+      # @example Invalid filenames
+      #   Validators.validate_filename("../etc/passwd")  # raises
+      #   Validators.validate_filename("/absolute/path")  # raises
+      def self.validate_filename(filename)
+        if filename.nil? || filename.empty?
+          raise ValidationError.new("filename", "Filename cannot be empty")
+        end
+
+        # Disallow absolute paths
+        if filename.start_with?("/")
+          raise ValidationError.new("filename", "Filename cannot be an absolute path")
+        end
+
+        # Disallow path traversal
+        if filename.include?("../") || filename.include?("..\\")
+          raise ValidationError.new("filename", "Filename cannot contain path traversal sequences")
+        end
+
+        # Disallow null bytes
+        if filename.include?("\0")
+          raise ValidationError.new("filename", "Filename cannot contain null bytes")
+        end
+
+        # Disallow Windows reserved names
+        basename = File.basename(filename)
+        windows_reserved = %w[CON PRN AUX NUL COM1 COM2 COM3 COM4 COM5 COM6 COM7 COM8 COM9
+                             LPT1 LPT2 LPT3 LPT4 LPT5 LPT6 LPT7 LPT8 LPT9]
+        if windows_reserved.include?(basename.upcase)
+          raise ValidationError.new("filename", "Filename cannot use Windows reserved names")
+        end
+
+        filename
+      end
+
+      # Validates a repository type.
+      #
+      # @param repo_type [String] Repository type
+      # @return [String] The validated repo_type
+      # @raise [ValidationError] If repo_type is invalid
+      #
+      # @example
+      #   Validators.validate_repo_type("model")
+      #   Validators.validate_repo_type("dataset")
+      def self.validate_repo_type(repo_type)
+        unless Constants::REPO_TYPES.include?(repo_type)
+          valid_types = Constants::REPO_TYPES.join(", ")
+          raise ValidationError.new(
+            "repo_type",
+            "Invalid repository type '#{repo_type}'. Must be one of: #{valid_types}"
+          )
+        end
+
+        repo_type
+      end
+
+      # Validates that a value is not nil.
+      #
+      # @param value [Object] Value to check
+      # @param name [String] Parameter name for error message
+      # @return [Object] The value if not nil
+      # @raise [ValidationError] If value is nil
+      def self.require_non_nil(value, name)
+        if value.nil?
+          raise ValidationError.new(name, "#{name} is required and cannot be nil")
+        end
+
+        value
+      end
+
+      # Validates that a string is not empty.
+      #
+      # @param value [String] String to check
+      # @param name [String] Parameter name for error message
+      # @return [String] The value if not empty
+      # @raise [ValidationError] If value is nil or empty
+      def self.require_non_empty(value, name)
+        if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          raise ValidationError.new(name, "#{name} cannot be empty")
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "rubygems/version"
+
+module DurableHuggingfaceHub
+  # Current version of the HuggingFace Hub Ruby client library
+  VERSION = "0.2.0"
+end