durable_huggingface_hub 0.2.0

data/devenv.lock

@@ -0,0 +1,171 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1761091275,
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "a795c32dc826b51d12706f27fb344f966bb2b084",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1760663237,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1758532697,
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "207a4cb0e1253c7658c6736becc6eb9cace1f25f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "flake-utils": "flake-utils",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1759902829,
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "5fba6c022a63f1e76dee4da71edddad8959f088a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "git-hooks": "git-hooks",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby",
+        "pre-commit-hooks": [
+          "git-hooks"
+        ]
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/devenv.nix

@@ -0,0 +1,15 @@
+{ pkgs, lib, config, inputs, ... }:
+
+{
+  # https://devenv.sh/packages/
+  packages = with pkgs; [ git libyaml openssl ];
+
+  languages.ruby.enable = true;
+  languages.ruby.version = "3.4.7";
+
+
+  enterShell = ''
+
+  '';
+
+}

data/devenv.yaml

@@ -0,0 +1,8 @@
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/huggingface_hub.gemspec

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "lib/durable_huggingface_hub/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "durable_huggingface_hub"
+  spec.version = DurableHuggingfaceHub::VERSION.to_s
+  spec.authors = ["David Berube"]
+  spec.email = ["commercial@durableprogramming.com"]
+
+  spec.summary = "Pure Ruby client for HuggingFace Hub"
+  spec.description = <<~DESC
+    A complete, production-ready Ruby implementation of the HuggingFace Hub client library.
+    Download models, datasets, and manage repositories with zero Python dependencies.
+    Features smart caching, authentication, progress tracking, and comprehensive error handling.
+  DESC
+  spec.homepage = "https://github.com/durableprogramming/huggingface-hub-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/durableprogramming/huggingface-hub-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/durableprogramming/huggingface-hub-ruby/blob/master/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/huggingface_hub"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/durableprogramming/huggingface-hub-ruby/issues"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile reference/ philosophy/ durableprogramming-coding-standards/])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+  spec.add_dependency "dry-struct", "~> 1.6"
+  spec.add_dependency "dry-types", "~> 1.7"
+  spec.add_dependency "ruby-progressbar", "~> 1.13"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-reporters", "~> 1.6"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "vcr", "~> 6.1"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-minitest", "~> 0.31"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/durable_huggingface_hub/authentication.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module DurableHuggingfaceHub
+  # Authentication methods for HuggingFace Hub.
+  #
+  # This module provides methods for logging in and out of HuggingFace Hub,
+  # storing authentication tokens securely, and verifying credentials.
+  module Authentication
+     # Logs in to HuggingFace Hub and stores the authentication token.
+     #
+     # If a token is provided, it will be validated and stored. If no token
+     # is provided and the process is running interactively, the user will
+     # be prompted to enter a token.
+     #
+     # @param token [String, nil] Authentication token
+     # @param add_to_git_credential [Boolean] Whether to add token to git credential helper
+     # @return [String] The stored token (masked)
+     # @raise [DurableHuggingfaceHubError] If token is invalid or login fails
+     #
+     # @example With explicit token
+     #   DurableHuggingfaceHub.login(token: "hf_...")
+     #
+     # @example Interactive login
+     #   DurableHuggingfaceHub.login  # Prompts for token
+     #
+     # @example Login with git credential storage
+     #   DurableHuggingfaceHub.login(token: "hf_...", add_to_git_credential: true)
+     def self.login(token: nil, add_to_git_credential: false)
+       # Get token from parameter or prompt
+       token = obtain_token(token)
+
+       # Validate token format
+       unless Utils::Auth.valid_token_format?(token)
+         raise ValidationError.new("token", "Invalid token format. Token should start with 'hf_'")
+       end
+
+       # Verify token works by calling whoami
+       begin
+         user_info = whoami(token: token)
+       rescue HfHubHTTPError => e
+         raise DurableHuggingfaceHubError.new("Login failed: #{e.message}")
+       end
+
+       # Store token
+       Utils::Auth.write_token_to_file(token)
+
+       # Store in git credential helper if requested
+       if add_to_git_credential
+         store_git_credential(token)
+       end
+
+       # Update configuration
+       Configuration.instance.token = token
+
+        # Return masked token and user info
+        masked = Utils::Auth.mask_token(token)
+        username = user_info.name || "unknown"
+
+       puts "Login successful!"
+       puts "Token: #{masked}"
+       puts "User: #{username}"
+
+       masked
+     end
+
+     # Logs out of HuggingFace Hub by removing the stored token.
+     #
+     # @return [Boolean] True if token was removed, false if no token existed
+     #
+     # @example
+     #   DurableHuggingfaceHub.logout
+     def self.logout
+       result = Utils::Auth.delete_token_file
+
+       # Remove from git credential helper if present
+       remove_git_credential
+
+       # Clear from configuration
+       Configuration.instance.token = nil
+
+       if result
+         puts "Logged out successfully. Token removed."
+       else
+         puts "No token found to remove."
+       end
+
+       result
+     end
+
+    # Returns information about the currently authenticated user.
+    #
+    # Makes a request to the /api/whoami endpoint to retrieve user information.
+    #
+    # @param token [String, nil] Authentication token (uses stored token if not provided)
+    # @return [Hash] User information hash
+    # @raise [LocalTokenNotFoundError] If no token is available
+    # @raise [HfHubHTTPError] If the API request fails
+    #
+    # @example
+    #   user_info = DurableHuggingfaceHub.whoami
+    #   puts user_info["name"]
+    #   puts user_info["fullname"]
+     def self.whoami(token: nil)
+       token = Utils::Auth.get_token!(token: token)
+
+       client = Utils::HttpClient.new(token: token)
+       response = client.get("/api/whoami")
+
+       Types::User.from_hash(response.body)
+     end
+
+    # Checks if a user is currently logged in (has a valid token).
+    #
+    # @return [Boolean] True if a token is available
+    #
+    # @example
+    #   if DurableHuggingfaceHub.logged_in?
+    #     puts "Already logged in"
+    #   end
+    def self.logged_in?
+      token = Utils::Auth.get_token
+      !token.nil? && !token.empty?
+    end
+
+     private
+
+       # Checks if git is available on the system.
+       #
+       # @return [Boolean] True if git is available
+       def self.git_available?
+         system("which git > /dev/null 2>&1")
+       end
+
+       # Stores the token in the git credential helper.
+       #
+       # @param token [String] Authentication token
+       # @return [Boolean] True if stored successfully
+       def self.store_git_credential(token)
+         # Check if git is available
+         return false unless git_available?
+
+         credential_data = <<~CREDENTIAL
+           protocol=https
+           host=huggingface.co
+           username=hf_#{token[3..]}  # Extract token part after 'hf_'
+           password=#{token}
+         CREDENTIAL
+
+         # Use git credential approve to store the credential
+         begin
+           IO.popen("git credential approve", "w+") do |io|
+             io.write(credential_data)
+             io.close_write
+             io.read # Consume any output
+           end
+           $?.success?
+         rescue Errno::ENOENT, IOError
+           false
+         end
+       end
+
+      # Removes the token from the git credential helper.
+       #
+       # @return [Boolean] True if removed successfully
+       def self.remove_git_credential
+         # Check if git is available
+         return false unless git_available?
+
+         # First check if we have a stored token to know what to remove
+         token = Utils::Auth.get_token
+         return false unless token
+
+         credential_data = <<~CREDENTIAL
+           protocol=https
+           host=huggingface.co
+           username=hf_#{token[3..]}  # Extract token part after 'hf_'
+         CREDENTIAL
+
+         # Use git credential reject to remove the credential
+         begin
+           IO.popen("git credential reject", "w+") do |io|
+             io.write(credential_data)
+             io.close_write
+             io.read # Consume any output
+           end
+           $?.success?
+         rescue Errno::ENOENT, IOError
+           false
+         end
+       end
+
+     # Obtains a token either from parameter or by prompting the user.
+     #
+     # @param token [String, nil] Provided token
+     # @return [String] Token
+     # @raise [DurableHuggingfaceHubError] If unable to obtain token
+     def self.obtain_token(token)
+       return token if token && !token.empty?
+
+         # Check if running interactively
+         unless $stdin.respond_to?(:tty?) && $stdin.tty?
+           raise DurableHuggingfaceHubError.new(
+             "No token provided and not running interactively. " \
+             "Please provide a token using the 'token' parameter."
+           )
+         end
+
+       # Prompt for token
+       prompt_for_token
+     end
+
+     # Prompts the user to enter their authentication token.
+     #
+     # The token input is hidden for security.
+     #
+     # @return [String] Entered token
+     # @raise [DurableHuggingfaceHubError] If token entry is cancelled
+     def self.prompt_for_token
+       puts "\nTo login, you need a User Access Token from https://huggingface.co/settings/tokens"
+       puts "You can create a new token or use an existing one."
+       puts "\nPaste your token (input will be hidden):"
+
+       # Read token without echoing to terminal
+       begin
+         if $stdin.respond_to?(:noecho) && $stdin.isatty
+           token = $stdin.noecho(&:gets)&.chomp
+         else
+           # For testing or when noecho is not available
+           token = $stdin.gets&.chomp
+         end
+       rescue Interrupt
+         puts "\nLogin cancelled"
+         raise DurableHuggingfaceHubError.new("Login cancelled by user")
+       end
+
+       if token.nil? || token.empty?
+         raise DurableHuggingfaceHubError.new("Token entry cancelled or empty")
+       end
+
+       token
+     end
+  end
+end