radfish 0.2.12 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56ac8a4bd0fa74d4925bd369825c0d7df1b87e77acea9a41d1327461a058e2e4
-  data.tar.gz: 5089df7444609d31fd193e8d6c022640ec57cbda96baf26c1df920eeb17bc3ab
+  metadata.gz: ddba2c0632175f4f75abe456074d912b7d6644371ca78699b7979abb4e9dd3de
+  data.tar.gz: 44eedf5868fbea6171d2714a922f1ab35dec320293208c5472e32d7d2104ece7
 SHA512:
-  metadata.gz: 10cdabeb27695b1a66aeb6531fa83da737b2a66e9f6ab24505a870797968ec5de49a388299627a954f1641e45ef356182535dcd7e4916bb2e8469b447c1d7dc4
-  data.tar.gz: bb95d3be33e59529b53231948763f60803f637353a707395cbc674aa898932696868dae481108fc64545055ed26072a7fda308c948214b770635618ab850b8dc
+  metadata.gz: 127e46cc938fe890f04ae0ad6b68b2ea0d2643ab7ca27c0855586291f363853cfb3151b0d88860d1f02f364f1430c42bef6f2c35880b6a8cc9504b5c7962b23c
+  data.tar.gz: c0e1fb812a023c8ecdfcf47a701dfc2fa4b959c9a63527109b4367a960f6261d5f3a35daa0415fe706ef0f3a66c4097a103bbd0a7d1ecc25b32872191013da46

data/README.md

@@ -35,6 +35,76 @@ Future adapters:
 - radfish-asrockrack
 ```
 
+### The HTTP layer
+
+`Radfish::HttpClient` is the single seam between the library and the network.
+Faraday is an implementation detail behind it: the vendor detector, the core
+classes and the adapters talk to `HttpClient` (or to `BaseClient#http_get` and
+friends, which delegate to it) and never build a Faraday connection of their
+own. Everything that BMCs make awkward lives in that one class - permissive TLS
+for old firmware, the `Host` header for SSH tunnels, retries, redirects, debug
+logging, and the translation of transport failures into Radfish errors.
+
+Two consequences worth knowing:
+
+- **Callers rescue Radfish errors, not Faraday errors.** `HttpClient` converts
+  Faraday's connection, timeout and SSL failures into `Radfish::ConnectionError`
+  and `Radfish::TimeoutError`. Code above the seam that rescues `Faraday::Error`
+  catches nothing.
+- **Adapters that wrap another gem are outside the seam.** The Dell and
+  Supermicro adapters delegate to the `idrac` and `supermicro` gems, which have
+  their own HTTP stacks, so the behaviour described here does not apply to their
+  requests.
+
+#### Errors
+
+All library errors descend from `Radfish::Error`, so one rescue catches
+everything the library raises:
+
+```
+Radfish::Error
+├── Radfish::ConnectionError        # unreachable host, refused connection, TLS failure
+├── Radfish::TimeoutError           # request took too long
+│   └── Radfish::BootProgressTimeout
+├── Radfish::AuthenticationError    # bad credentials
+├── Radfish::NotFoundError
+├── Radfish::UnsupportedVendorError # no adapter for this BMC
+├── Radfish::VirtualMediaError      # + NotFound / Connection / License / Busy
+└── Radfish::TaskError              # + TaskTimeoutError / TaskFailedError
+```
+
+#### Retries
+
+Failed requests are retried with an exponential backoff on 408, 429, 500, 502,
+503 and 504, and on connection and timeout failures. **Only idempotent methods
+are retried** - GET, HEAD, PUT and DELETE. A repeated POST is not safe on
+Redfish: it can mean a second session, a second reset, or a second job. A caller
+that knows its POST is safe to repeat can widen the set for one client:
+
+```ruby
+Radfish::HttpClient.new(
+  host: '192.168.1.100',
+  retry_count: 3,                    # attempts after the first
+  retry_delay: 1,                    # initial delay, doubled each retry
+  retry_methods: Radfish::HttpClient::IDEMPOTENT_METHODS + [:post]
+)
+```
+
+For a whole operation rather than a single request, `BaseClient#with_retries`
+wraps a block.
+
+#### Redirects
+
+Some BMCs (AMI MegaRAC, for one) redirect `/redfish/v1` to `/redfish/v1/`.
+`HttpClient` follows redirects on GET and HEAD, up to `max_redirects` hops
+(3 by default; pass `max_redirects: 0` on a call to get the 3xx response
+itself). A redirect is only followed back to the same endpoint - a relative
+path, or an absolute URL whose scheme, host and port match the BMC already
+being addressed - because every request carries credentials and Faraday would
+otherwise hand them to whatever host the `Location` header named. POST and
+PATCH redirects are returned to the caller rather than followed, since
+301/302/303 do not preserve the method.
+
 ## Features
 
 ### Automatic Vendor Detection
@@ -183,13 +253,28 @@ All commands support these options:
   --host, -h HOST          # BMC hostname or IP address
   --username, -u USER      # BMC username
   --password, -p PASS      # BMC password
-  --vendor VENDOR          # Force specific vendor (dell, supermicro, etc.)
+  --vendor, -v VENDOR      # Force specific vendor (dell, supermicro, etc.)
   --port PORT              # BMC port (default: 443)
+  --config, -c FILE        # Read options from a YAML config file
   --json                   # Output in JSON format
-  --verbose, -v            # Enable verbose output (repeat for more verbosity)
-  --no-verify-ssl          # Skip SSL certificate verification
+  --verbose                # Application-level progress messages
+  --debug [N]              # HTTP-level debug output (default 2, see below)
+  --insecure               # Skip SSL certificate verification (default: true)
 ```
 
+`--verbose` and `--debug` set the same verbosity level, and `--debug` wins:
+
+| Level | Flag          | Output                                              |
+|-------|---------------|-----------------------------------------------------|
+| 0     | (none)        | Results only                                        |
+| 1     | `--verbose`   | Progress messages from the library                  |
+| 2     | `--debug`     | Adds the HTTP request and response log              |
+| 3     | `--debug 3`   | Adds request and response bodies, and call sites    |
+
+The `Authorization` header and password fields are filtered out of the log, but
+level 3 prints request and response bodies, which can carry other sensitive
+data - read it before pasting it into an issue.
+
 ### Output Formats
 
 #### Default (Human-Readable)
@@ -391,7 +476,7 @@ client.mount_iso_and_boot("http://example.com/os.iso")
 options = client.boot_options
 
 # Set one-time boot
-client.set_boot_override("Pxe", persistent: false)
+client.set_boot_override("Pxe", persistence: 'Once')
 
 # Quick boot methods
 client.boot_to_pxe
@@ -457,8 +542,10 @@ Radfish::Client.new(
   use_ssl: true,            # Use HTTPS
   verify_ssl: false,        # Verify certificates
   direct_mode: false,       # Use Basic Auth instead of sessions
-  retry_count: 3,           # Retry failed requests
-  retry_delay: 1,           # Initial delay between retries
+  retry_count: 3,           # Retries after the first attempt
+  retry_delay: 1,           # Initial delay between retries, doubled each time
+  retry_methods: nil,       # Defaults to idempotent methods only
+  max_redirects: 3,         # Same-endpoint redirects to follow (0 disables)
   verbosity: 0              # Debug output level (0-3)
 )
 ```
@@ -468,11 +555,14 @@ Radfish::Client.new(
 Enable verbose output:
 
 ```ruby
-client.verbosity = 1  # Basic debug info
-client.verbosity = 2  # Include request/response details  
-client.verbosity = 3  # Include stack traces
+client.verbosity = 1  # Progress messages from the library
+client.verbosity = 2  # Adds the HTTP request and response log
+client.verbosity = 3  # Adds request and response bodies, and call sites
 ```
 
+These are the same levels the CLI sets with `--verbose` and `--debug N`. The
+`Authorization` header and password fields are filtered out of the log.
+
 ## Supported Vendors
 
 Currently supported:

data/lib/radfish/boot_info.rb

@@ -29,6 +29,28 @@ module Radfish
       match ? adapter.disable_boot_entries(match: match, **opts) : adapter.disable_boot_entries(**opts)
     end
 
+    # One-time boot to the virtual CD via the vendor's reliable path (Dell: an SCP import that drains
+    # any pending config job first, then sets ServerBoot BootOnce + FirstBootDevice=VCD-DVD). Returns
+    # the vendor result; raises NotImplementedError on an adapter with no SCP one-time-boot path.
+    def set_one_time_cd_boot(**opts)
+      require_adapter!(:set_one_time_cd_boot)
+      adapter.set_one_time_cd_boot(**opts)
+    end
+
+    # Poll the config job +jid+ (e.g. the BIOS config job a boot-source change schedules) to a
+    # terminal state. Returns the state string, or nil on timeout (never raises).
+    def wait_config_job(jid, **opts)
+      require_adapter!(:wait_config_job)
+      adapter.wait_config_job(jid, **opts)
+    end
+
+    # Drain every pending (non-Completed) config job so scheduling a new one does not trip LC068.
+    # Returns the ids drained.
+    def drain_config_jobs
+      require_adapter!(:drain_pending_config_jobs!)
+      adapter.drain_pending_config_jobs!
+    end
+
     # Underlying boot configuration hash (BootSourceOverride*, boot order, ...).
     def to_h
       adapter.boot_config

data/lib/radfish/cli.rb

@@ -16,6 +16,7 @@ module Radfish
     class_option :port, type: :numeric, default: 443, desc: 'BMC port (env: RADFISH_PORT)'
     class_option :insecure, type: :boolean, default: true, desc: 'Skip SSL verification'
     class_option :verbose, type: :boolean, default: false, desc: 'Enable verbose output'
+    class_option :debug, type: :numeric, lazy_default: 2, desc: 'Debug output level'
     class_option :json, type: :boolean, default: false, desc: 'Output in JSON format'
     
     desc "detect", "Detect the vendor of a BMC"
@@ -25,6 +26,7 @@ module Radfish
           host: opts[:host],
           username: opts[:username],
           password: opts[:password],
+          verbosity: opts[:verbosity],
           port: opts[:port],
           verify_ssl: !opts[:insecure]
         )
@@ -336,7 +338,7 @@ module Radfish
     # Storage Commands
     desc "storage SUBCOMMAND", "Storage information"
     def storage(subcommand = 'summary')
-      with_client do |client|
+      with_client do |client, opts|
         case subcommand
         when 'summary', 'all'
           data = client.storage_summary
@@ -370,7 +372,7 @@ module Radfish
               all_drives.concat(drives) if drives
             rescue => e
               ctrl_name = controller.respond_to?(:name) ? controller.name : 'controller'
-              puts "Error fetching drives for #{ctrl_name}: #{e.message}".yellow if options[:verbose]
+              puts "Error fetching drives for #{ctrl_name}: #{e.message}".yellow if opts[:verbosity] > 0
             end
           end
           
@@ -402,7 +404,7 @@ module Radfish
               all_volumes.concat(volumes) if volumes
             rescue => e
               ctrl_name = controller.respond_to?(:name) ? controller.name : 'controller'
-              puts "Error fetching volumes for #{ctrl_name}: #{e.message}".yellow if options[:verbose]
+              puts "Error fetching volumes for #{ctrl_name}: #{e.message}".yellow if opts[:verbosity] > 0
             end
           end
           
@@ -652,17 +654,17 @@ module Radfish
           password: opts[:password],
           port: opts[:port],
           verify_ssl: !opts[:insecure],
-          direct_mode: true
+          direct_mode: true,
+          verbosity: opts[:verbosity]
         }
         
         client_opts[:vendor] = opts[:vendor] if opts[:vendor]
         
         begin
           client = Radfish::Client.new(**client_opts)
-          client.verbosity = 1 if opts[:verbose]
-          
+
           client.login
-          yield client
+          yield client, opts
         rescue => e
           error "Error: #{e.message}"
           exit 1
@@ -695,7 +697,16 @@ module Radfish
       opts[:port] = options[:port] if options[:port]
       opts[:insecure] = options[:insecure] if options.key?(:insecure)
       opts[:verbose] = options[:verbose] if options.key?(:verbose)
-      
+      opts[:debug] = options[:debug] if options.key?(:debug)
+
+      if opts[:debug]
+        opts[:verbosity] = opts[:debug].to_i
+      elsif opts[:verbose]
+        opts[:verbosity] = 1
+      else
+        opts[:verbosity] = 0
+      end
+
       # Check environment variables as fallback
       opts[:host] ||= ENV['RADFISH_HOST']
       opts[:username] ||= ENV['RADFISH_USERNAME']
@@ -713,7 +724,7 @@ module Radfish
     def safe_call
       yield
     rescue => e
-      options[:verbose] ? e.message : 'N/A'
+      (options[:verbose] || options[:debug].to_i > 0) ? e.message : 'N/A'
     end
     
     def error(message)

data/lib/radfish/core/base_client.rb

@@ -155,4 +155,4 @@ module Radfish
       end
     end
   end
-end
+end

data/lib/radfish/core/boot.rb

@@ -7,7 +7,7 @@ module Radfish
         raise NotImplementedError, "Adapter must implement #boot_config"
       end
       
-      def set_boot_override(target, persistent: false)
+      def set_boot_override(target, persistence: nil, mode: nil)
         raise NotImplementedError, "Adapter must implement #set_boot_override"
       end
       
@@ -53,4 +53,4 @@ module Radfish
       end
     end
   end
-end
+end

data/lib/radfish/core/session.rb

@@ -108,9 +108,7 @@ module Radfish
           false
         end
       end
-      
-      private
-      
+
       def verbosity
         client.verbosity
       end

data/lib/radfish/http_client.rb

@@ -11,12 +11,27 @@ module Radfish
   class HttpClient
     include Debuggable
     
+    # Redirects we follow, and the methods we follow them for. GET/HEAD only:
+    # 307/308 preserve the method, but 301/302/303 do not, so re-sending a POST
+    # body after one would be wrong. Callers doing anything else get the 3xx back.
+    REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+    REDIRECT_METHODS = [:get, :head].freeze
+    
+    # Methods we retry by default. A repeated GET or DELETE is harmless, but a
+    # repeated POST is not: on Redfish it can mean a second session, a second
+    # reset, a second job. Callers that know a POST is safe to repeat can widen
+    # this per client with retry_methods:.
+    IDEMPOTENT_METHODS = [:get, :head, :put, :delete].freeze
+    RETRY_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    
     attr_reader :host, :port, :use_ssl, :verify_ssl
-    attr_accessor :username, :password, :verbosity, :retry_count, :retry_delay
+    attr_accessor :username, :password, :verbosity, :retry_count, :retry_delay,
+                  :retry_methods, :max_redirects
     
     def initialize(host:, port: 443, use_ssl: true, verify_ssl: false, 
                    username: nil, password: nil, verbosity: 0,
-                   retry_count: 3, retry_delay: 1, **options)
+                   retry_count: 3, retry_delay: 1,
+                   retry_methods: IDEMPOTENT_METHODS, max_redirects: 3, **options)
       @host = host
       @port = port
       @use_ssl = use_ssl
@@ -26,6 +41,8 @@ module Radfish
       @verbosity = verbosity
       @retry_count = retry_count
       @retry_delay = retry_delay
+      @retry_methods = retry_methods
+      @max_redirects = max_redirects
       @options = options
     end
     
@@ -54,8 +71,12 @@ module Radfish
       request(:delete, path, headers: headers, **options)
     end
     
-    def request(method, path, body: nil, headers: {}, auth: true, timeout: nil, **options)
+    # max_redirects overrides the client default for one call; pass 0 to get the
+    # 3xx response itself rather than what it points at.
+    def request(method, path, body: nil, headers: {}, auth: true, timeout: nil,
+                max_redirects: nil, **options)
       debug "Starting HTTP #{method.upcase} request to #{path}", 2, :yellow
+      redirects_left = max_redirects.nil? ? @max_redirects.to_i : max_redirects.to_i
       
       # Add host header if specified (needed for SSH tunnels to iDRAC)
       if @options[:host_header]
@@ -90,6 +111,18 @@ module Radfish
       
       debug "Request completed with status: #{response.status}", 2, :green
       
+      if redirects_left > 0 && redirect?(method, response)
+        target = safe_redirect_path(response['location'])
+        
+        if target.nil?
+          debug "Not following redirect to #{response['location'].inspect} - it leaves #{base_url}", 1, :yellow
+        else
+          debug "Following redirect to #{target}, #{redirects_left - 1} left", 2, :yellow
+          return request(method, target, body: body, headers: headers, auth: auth,
+                         timeout: timeout, max_redirects: redirects_left - 1, **options)
+        end
+      end
+      
       response
     rescue Faraday::ConnectionFailed => e
       debug "Connection failed: #{e.message}", 1, :red
@@ -127,8 +160,42 @@ module Radfish
       raise e
     end
     
+    def redirect?(method, response)
+      REDIRECT_METHODS.include?(method) && REDIRECT_STATUSES.include?(response.status)
+    end
+    
+    # The path (with query) to request for +location+, or nil when we must not
+    # follow it. Every request we make carries credentials -- Basic auth here, an
+    # X-Auth-Token on the adapters' authenticated_request -- and Faraday honours an
+    # absolute URL by replacing the host, so a BMC answering with
+    # "Location: https://elsewhere/" would be handed those credentials. Accept a
+    # relative path, or an absolute URL for this same endpoint, and return only the
+    # path so the request stays on this connection.
+    #
+    # Note: with an SSH tunnel (host_header set) an absolute redirect to the BMC's
+    # own name is refused, since that name is not the host we connect to. Relative
+    # redirects are unaffected.
+    def safe_redirect_path(location)
+      location = location.to_s
+      return nil if location.empty?
+      
+      uri = URI.parse(location)
+      return nil if uri.path.to_s.empty?
+      return nil unless uri.host.nil? || same_endpoint?(uri)
+      
+      uri.query ? "#{uri.path}?#{uri.query}" : uri.path
+    rescue URI::InvalidURIError
+      nil
+    end
+    
     private
     
+    def same_endpoint?(uri)
+      uri.host == host &&
+        uri.port == port &&
+        uri.scheme == (use_ssl ? 'https' : 'http')
+    end
+    
     def connection(auth: true)
       @connections ||= {}
       cache_key = auth ? :with_auth : :without_auth
@@ -182,8 +249,8 @@ module Radfish
             Faraday::TimeoutError,
             Faraday::RetriableResponse
           ],
-          methods: [:get, :put, :delete, :post, :patch],
-          retry_statuses: [408, 429, 500, 502, 503, 504]
+          methods: retry_methods,
+          retry_statuses: RETRY_STATUSES
           # Removed retry_block to debug ArgumentError - can add back later
         }
         
@@ -192,8 +259,8 @@ module Radfish
         faraday.options.open_timeout = 10
         
         # Add logging if verbose
-        if verbosity > 0
-          faraday.response :logger, Logger.new(STDOUT), { bodies: verbosity >= 2 } do |logger|
+        if verbosity >= 2
+          faraday.response :logger, Logger.new(STDOUT), { bodies: verbosity >= 3 } do |logger|
             logger.filter(/(Authorization: Basic )([^,\n]+)/, '\1[FILTERED]')
             logger.filter(/(Password"=>"?)([^,"]+)/, '\1[FILTERED]')
             logger.filter(/("password":\s*")([^"]+)/, '\1[FILTERED]')

data/lib/radfish/vendor_detector.rb

@@ -60,7 +60,29 @@ module Radfish
     end
     
     private
-    
+
+    def check_response(response)
+      if response.status == 200
+        debug "Got 200 response, parsing JSON...", 2, :green
+        JSON.parse(response.body)
+      elsif HttpClient::REDIRECT_STATUSES.include?(response.status)
+        # HttpClient follows redirects that stay on this endpoint, so reaching
+        # here means it refused one or ran out of them.
+        debug "Redirect to #{response['location'].inspect} was not followed (HTTP #{response.status})", 1, :red
+        nil
+      elsif response.status == 401
+        debug "Authentication failed (HTTP 401) - check username/password", 1, :red
+        nil
+      elsif response.status == 404
+        debug "Redfish API not found at /redfish/v1 (HTTP 404)", 1, :red
+        nil
+      else
+        debug "Failed to fetch service root: HTTP #{response.status}", 1, :red
+        debug "Response body: #{response.body[0..200]}" if response.body && @verbosity >= 2
+        nil
+      end
+    end
+
     def fetch_service_root
       begin
         debug "About to make HTTP GET request to /redfish/v1", 2, :yellow
@@ -69,21 +91,8 @@ module Radfish
         debug "Using timeout: #{timeout}s (SSH tunnel detected)" if @host_header
         response = @http_client.get('/redfish/v1', timeout: timeout)
         debug "HTTP GET request completed", 2, :green
-        
-        if response.status == 200
-          debug "Got 200 response, parsing JSON...", 2, :green
-          JSON.parse(response.body)
-        elsif response.status == 401
-          debug "Authentication failed (HTTP 401) - check username/password", 1, :red
-          nil
-        elsif response.status == 404
-          debug "Redfish API not found at /redfish/v1 (HTTP 404)", 1, :red
-          nil
-        else
-          debug "Failed to fetch service root: HTTP #{response.status}", 1, :red
-          debug "Response body: #{response.body[0..200]}" if response.body && @verbosity >= 2
-          nil
-        end
+
+        check_response(response)
       rescue ConnectionError, TimeoutError => e
         debug "Connection failed to #{host}:#{port} - #{e.message}", 1, :red
         nil
@@ -210,4 +219,4 @@ module Radfish
       end
     end
   end
-end
+end

data/lib/radfish/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Radfish
-  VERSION = "0.2.12"
+  VERSION = "0.3.0"
 end

data/lib/radfish.rb

@@ -58,8 +58,10 @@ module Radfish
       Client.connect(**options, &block)
     end
 
-    def detect_vendor(host:, username:, password:, **options)
-      VendorDetector.new(host: host, username: username, password: password, **options).detect
+    def detect_vendor(host:, username:, password:, verbosity: 0, **options)
+      vendor_detector = VendorDetector.new(host: host, username: username, password: password, **options)
+      vendor_detector.verbosity = verbosity
+      vendor_detector.detect
     end
 
     def register_adapter(vendor, adapter_class)

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: radfish
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.3.0
 platform: ruby
 authors:
 - Jonathan Siegel
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -197,6 +198,7 @@ metadata:
   homepage_uri: https://github.com/buildio/radfish
   source_code_uri: https://github.com/buildio/radfish
   changelog_uri: https://github.com/buildio/radfish/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -211,7 +213,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Unified Redfish API Client for Server Management
 test_files: []