durable_huggingface_hub 0.2.0

data/lib/durable_huggingface_hub/utils/auth.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+
+module DurableHuggingfaceHub
+  module Utils
+    # Authentication token management utilities.
+    #
+    # This module provides functions for retrieving, storing, and managing
+    # HuggingFace authentication tokens.
+    module Auth
+      # File permissions for token storage (owner read/write only)
+      TOKEN_FILE_PERMISSIONS = 0o600
+
+      # Retrieves the authentication token from multiple sources.
+      #
+      # Priority order:
+      # 1. Explicitly provided token parameter
+      # 2. HF_TOKEN environment variable
+      # 3. HUGGING_FACE_HUB_TOKEN environment variable
+      # 4. Token file (~/.cache/huggingface/token)
+      #
+      # @param token [String, nil] Explicitly provided token
+      # @return [String, nil] Authentication token or nil if not found
+      #
+      # @example Explicit token
+      #   Auth.get_token(token: "hf_...")
+      #
+      # @example From environment or file
+      #   Auth.get_token  # Checks ENV then file
+      def self.get_token(token: nil)
+        # Priority 1: Explicit parameter
+        return token if token && !token.empty?
+
+        # Priority 2: HF_TOKEN environment variable
+        env_token = ENV["HF_TOKEN"]
+        return env_token if env_token && !env_token.empty?
+
+        # Priority 3: HUGGING_FACE_HUB_TOKEN environment variable
+        legacy_token = ENV["HUGGING_FACE_HUB_TOKEN"]
+        return legacy_token if legacy_token && !legacy_token.empty?
+
+        # Priority 4: Token file
+        read_token_from_file
+      end
+
+      # Reads the authentication token from the token file.
+      #
+      # @return [String, nil] Token from file or nil if not found
+      def self.read_token_from_file
+        token_path = get_token_path
+        return nil unless File.exist?(token_path)
+
+        token = File.read(token_path).strip
+        token.empty? ? nil : token
+      rescue Errno::EACCES, Errno::ENOENT
+        nil
+      end
+
+      # Writes the authentication token to the token file.
+      #
+      # Creates the cache directory if it doesn't exist and sets
+      # appropriate file permissions for security.
+      #
+      # @param token [String] Token to store
+      # @return [Boolean] True if successful
+      # @raise [IOError] If unable to write token
+      #
+      # @example
+      #   Auth.write_token_to_file("hf_...")
+      def self.write_token_to_file(token)
+        token_path = get_token_path
+
+        # Ensure cache directory exists
+        token_path.dirname.mkpath unless token_path.dirname.exist?
+
+        # Write token atomically
+        temp_path = Pathname.new("#{token_path}.tmp")
+        temp_path.write(token)
+
+        # Set restrictive permissions before moving
+        File.chmod(TOKEN_FILE_PERMISSIONS, temp_path)
+
+        # Atomic move
+        File.rename(temp_path, token_path)
+
+        true
+      rescue => e
+        # Clean up temp file if it exists
+        temp_path&.delete if temp_path&.exist?
+        raise IOError, "Failed to write token: #{e.message}"
+      end
+
+      # Deletes the token file.
+      #
+      # @return [Boolean] True if file was deleted, false if it didn't exist
+      def self.delete_token_file
+        token_path = get_token_path
+        return false unless token_path.exist?
+
+        token_path.delete
+        true
+      rescue Errno::EACCES, Errno::ENOENT
+        false
+      end
+
+      # Returns the path to the token file.
+      #
+      # @return [Pathname] Path to token file
+      def self.get_token_path
+        Configuration.instance.token_path
+      end
+
+      # Validates a token format.
+      #
+      # HuggingFace tokens typically start with "hf_" and are alphanumeric.
+      #
+      # @param token [String] Token to validate
+      # @return [Boolean] True if token format appears valid
+      #
+      # @example
+      #   Auth.valid_token_format?("hf_abc123")  # => true
+      #   Auth.valid_token_format?("invalid")     # => false
+      def self.valid_token_format?(token)
+        return false if token.nil? || token.empty?
+
+        # HuggingFace tokens start with "hf_" followed by alphanumeric characters
+        # Minimum reasonable length is around 10 characters
+        token.match?(/\Ahf_[A-Za-z0-9_-]{8,}\z/)
+      end
+
+      # Retrieves a token and raises an error if not found.
+      #
+      # @param token [String, nil] Explicitly provided token
+      # @return [String] Authentication token
+      # @raise [LocalTokenNotFoundError] If no token is available
+      #
+      # @example
+      #   token = Auth.get_token!  # Raises if not found
+      def self.get_token!(token: nil)
+        result = get_token(token: token)
+        return result if result
+
+        raise LocalTokenNotFoundError.new
+      end
+
+      # Masks a token for safe display.
+      #
+      # Shows first 7 characters and last 4 characters, masking the middle.
+      #
+      # @param token [String] Token to mask
+      # @return [String] Masked token
+      #
+      # @example
+      #   Auth.mask_token("hf_abc123def456ghi789")
+      #   # => "hf_abc1...h789"
+      def self.mask_token(token)
+        return "" if token.nil? || token.empty?
+        return token if token.length <= 11
+
+        if token.length <= 15
+          prefix = token[0, 4]
+          suffix = token[-1]
+          "#{prefix}...#{suffix}"
+        else
+          prefix = token[0, 7]
+          suffix = token[-4..]
+          "#{prefix}...#{suffix}"
+        end
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/utils/headers.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "validators"
+
+module DurableHuggingfaceHub
+  module Utils
+    # HTTP header building utilities for HuggingFace Hub API requests.
+    #
+    # This module provides functions for constructing proper HTTP headers
+    # including User-Agent, Authorization, and custom headers.
+    module Headers
+      # Builds standard headers for HuggingFace Hub API requests.
+      #
+      # @param token [String, nil] Authentication token
+      # @param library_name [String, nil] Name of the library using this client
+      # @param library_version [String, nil] Version of the library
+      # @param user_agent [String, nil] Custom user agent string
+      # @param headers [Hash, nil] Additional custom headers
+      # @return [Hash] Complete headers hash
+      # @raise [ValidationError] If any parameter has invalid type or format
+      #
+      # @example Basic usage
+      #   headers = Headers.build_hf_headers(token: "hf_...")
+      #
+      # @example With custom library info
+      #   headers = Headers.build_hf_headers(
+      #     token: "hf_...",
+      #     library_name: "my_app",
+      #     library_version: "1.0.0"
+      #   )
+      def self.build_hf_headers(token: nil, library_name: nil, library_version: nil, user_agent: nil, headers: nil)
+        # Validate parameters
+        if token && !token.is_a?(String)
+          raise ValidationError.new("token", "Token must be a string")
+        end
+
+        if library_name && !library_name.is_a?(String)
+          raise ValidationError.new("library_name", "Library name must be a string")
+        end
+
+        if library_version && !library_version.is_a?(String)
+          raise ValidationError.new("library_version", "Library version must be a string")
+        end
+
+        if user_agent && !user_agent.is_a?(String)
+          raise ValidationError.new("user_agent", "User agent must be a string")
+        end
+
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Custom headers must be a hash")
+        end
+
+        result = {}
+
+        # User-Agent header
+        result["User-Agent"] = build_user_agent(
+          library_name: library_name,
+          library_version: library_version,
+          custom_agent: user_agent
+        )
+
+        # Authorization header
+        if token
+          result["Authorization"] = "Bearer #{token}"
+        end
+
+        # Merge custom headers
+        if headers
+          result.merge!(headers)
+        end
+
+        result
+      end
+
+      # Builds a User-Agent string for HTTP requests.
+      #
+      # Format: "[custom] [library/version] huggingface_hub/version; ruby/version"
+      #
+      # @param library_name [String, nil] Name of the calling library
+      # @param library_version [String, nil] Version of the calling library
+      # @param custom_agent [String, nil] Custom user agent to prepend
+      # @return [String] User-Agent string
+      # @raise [ValidationError] If any parameter has invalid type
+      #
+      # @example
+      #   Headers.build_user_agent
+      #   # => "huggingface_hub/0.1.0; ruby/3.3.0"
+      #
+      # @example With library info
+      #   Headers.build_user_agent(library_name: "transformers", library_version: "4.0.0")
+      #   # => "transformers/4.0.0 huggingface_hub/0.1.0; ruby/3.3.0"
+      def self.build_user_agent(library_name: nil, library_version: nil, custom_agent: nil)
+        # Validate parameters
+        if library_name && !library_name.is_a?(String)
+          raise ValidationError.new("library_name", "Library name must be a string")
+        end
+
+        if library_version && !library_version.is_a?(String)
+          raise ValidationError.new("library_version", "Library version must be a string")
+        end
+
+        if custom_agent && !custom_agent.is_a?(String)
+          raise ValidationError.new("custom_agent", "Custom agent must be a string")
+        end
+
+        parts = []
+
+        # Custom agent
+        parts << custom_agent if custom_agent
+
+        # Library identification
+        if library_name && library_version && !library_version.empty?
+          parts << "#{library_name}/#{library_version}"
+        elsif library_name && !library_name.empty?
+          parts << library_name
+        end
+
+        # HuggingFace Hub client identification
+        hf_part = "huggingface_hub/#{DurableHuggingfaceHub::VERSION}"
+
+        # Ruby version
+        ruby_part = "ruby/#{RUBY_VERSION}"
+
+        # Join library/custom parts with space, then add hf; ruby
+        library_part = parts.empty? ? "" : "#{parts.join(" ")} "
+        "#{library_part}#{hf_part}; #{ruby_part}"
+      end
+
+      # Extracts request ID from response headers.
+      #
+      # @param headers [Hash] Response headers
+      # @return [String, nil] Request ID if present
+      # @raise [ValidationError] If headers is not a hash
+      def self.extract_request_id(headers)
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Headers must be a hash")
+        end
+
+        return nil unless headers
+
+        # Try common header names
+        headers["X-Request-Id"] ||
+          headers["x-request-id"] ||
+          headers["Request-Id"] ||
+          headers["request-id"]
+      end
+
+      # Extracts commit SHA from response headers.
+      #
+      # @param headers [Hash] Response headers
+      # @return [String, nil] Commit SHA if present
+      # @raise [ValidationError] If headers is not a hash
+      def self.extract_commit_sha(headers)
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Headers must be a hash")
+        end
+
+        return nil unless headers
+
+        headers[Constants::HEADER_X_REPO_COMMIT] ||
+          headers[Constants::HEADER_X_REPO_COMMIT.downcase]
+      end
+
+      # Extracts ETag from response headers.
+      #
+      # @param headers [Hash] Response headers
+      # @return [String, nil] ETag value (with quotes removed)
+      # @raise [ValidationError] If headers is not a hash
+      def self.extract_etag(headers)
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Headers must be a hash")
+        end
+
+        return nil unless headers
+
+        etag = headers["ETag"] || headers["etag"]
+        return nil unless etag
+
+        # Remove surrounding quotes if present
+        etag.gsub(/^"|"$/, "")
+      end
+
+      # Extracts linked file size from response headers.
+      #
+      # @param headers [Hash] Response headers
+      # @return [Integer, nil] File size in bytes
+      # @raise [ValidationError] If headers is not a hash
+      def self.extract_linked_size(headers)
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Headers must be a hash")
+        end
+
+        return nil unless headers
+
+        size = headers[Constants::HEADER_X_LINKED_SIZE] ||
+               headers[Constants::HEADER_X_LINKED_SIZE.downcase]
+
+        size&.to_i
+      end
+
+      # Checks if response indicates the file is stored in LFS.
+      #
+      # @param headers [Hash] Response headers
+      # @return [Boolean] True if file is in LFS
+      # @raise [ValidationError] If headers is not a hash
+      def self.lfs_file?(headers)
+        if headers && !headers.is_a?(Hash)
+          raise ValidationError.new("headers", "Headers must be a hash")
+        end
+
+        return false unless headers
+
+        etag = headers[Constants::HEADER_X_LINKED_ETAG] ||
+               headers[Constants::HEADER_X_LINKED_ETAG.downcase]
+
+        !etag.nil?
+      end
+    end
+  end
+end