cgminer_api_client 0.2.6 → 0.4.0

data/bin/cgminer_api_client

@@ -1,22 +1,83 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 $LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib/")
 
 require 'cgminer_api_client'
 require 'pp'
+require 'optparse'
+
+# permute! (rather than order!) lets a flag appear after the command —
+# `cgminer_api_client summary -v` works the same as `-v summary`.
+verbose = false
+begin
+  OptionParser.new do |opts|
+    opts.banner = 'USAGE: cgminer_api_client [-v|--verbose] command (arguments)'
+    opts.on('-v', '--verbose', 'Log JSON request and raw response to stderr') do
+      verbose = true
+    end
+  end.permute!(ARGV)
+rescue OptionParser::ParseError => e
+  warn "cgminer_api_client: #{e.message}"
+  warn 'USAGE: cgminer_api_client [-v|--verbose] command (arguments)'
+  exit 64 # EX_USAGE
+end
 
 command = ARGV.shift&.to_sym
 commands = CgminerApiClient::Miner::Commands.instance_methods
 
-unless command and commands.include?(command)
-  puts "USAGE: cgminer_api_client command (arguments)"
-  puts "commands: " + commands.sort.collect(&:to_s).join(', ')
-  exit(0)
+unless command && commands.include?(command)
+  warn 'USAGE: cgminer_api_client [-v|--verbose] command (arguments)'
+  warn "commands: #{commands.sort.join(', ')}"
+  warn ''
+  warn 'Set DEBUG=1 to see full backtraces on errors.'
+  exit 64 # EX_USAGE
+end
+
+# `MinerPool` fans out across miners in separate threads; Ruby's
+# `warn` / `$stderr.write` is not atomic across threads for
+# arbitrary-length payloads, so multi-miner fan-out can interleave
+# mid-JSON without a mutex. The mutex also keeps a request/response
+# pair contiguous. The host:port prefix lets operators grep a single
+# miner out of the mixed stream.
+on_wire = nil
+if verbose
+  wire_mutex = Mutex.new
+  wire_prefix = {
+    request: '>>>',
+    response: '<<<',
+    response_repaired: '<<< (repaired)'
+  }.freeze
+  on_wire = lambda do |direction, host, port, payload|
+    wire_mutex.synchronize do
+      warn "#{wire_prefix[direction]} #{host}:#{port} #{payload}"
+    end
+  rescue Errno::EPIPE, IOError
+    # stderr was closed mid-run (piped through a command that exited, etc.).
+    # Best-effort logging must not take down the query fan-out.
+    nil
+  end
 end
 
 begin
-  miner_pool = CgminerApiClient::MinerPool.new
-  pp(ARGV.empty? ? miner_pool.query(command) : miner_pool.query(command, *ARGV))
-rescue => e
-  puts e.message
-end
+  pool = CgminerApiClient::MinerPool.new(on_wire: on_wire)
+  result = ARGV.empty? ? pool.query(command) : pool.query(command, *ARGV)
+
+  result.each do |r|
+    if r.ok?
+      puts "#{r.miner.host}:#{r.miner.port}:"
+      pp r.value
+    else
+      warn "#{r.miner.host}:#{r.miner.port}: #{r.error.class}: #{r.error.message}"
+    end
+  end
+
+  # Exit 0 if at least one miner succeeded; 1 only if every miner
+  # failed. Matches how fleet-oriented CLIs (ping, ssh -o) typically
+  # behave — partial failures don't trigger alerts.
+  exit(result.any_succeeded? ? 0 : 1)
+rescue StandardError => e
+  warn "cgminer_api_client: #{e.class}: #{e.message}"
+  warn e.full_message(highlight: false) if ENV['DEBUG']
+  exit 1
+end

data/cgminer_api_client.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'cgminer_api_client/version'
 
@@ -8,13 +9,31 @@ Gem::Specification.new do |spec|
   spec.version       = CgminerApiClient::VERSION
   spec.authors       = ["Justin Ramos"]
   spec.email         = ["justin.ramos@gmail.com"]
-  spec.summary       = %q{A gem that allows sending API commands to a pool of cgminer instances}
-  spec.description   = %q{}
+  spec.summary       = "A gem that allows sending API commands to a pool of cgminer instances"
+  spec.description   = "Ruby client for the cgminer JSON API. Supports querying a single miner " \
+                       "or a pool of miners in parallel, with full coverage of read-only and " \
+                       "privileged commands."
   spec.homepage      = "https://github.com/jramos/cgminer_api_client"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0")
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata = {
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/master/CHANGELOG.md",
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.glob([
+                          "lib/**/*.rb",
+                          "bin/*",
+                          "config/*.example",
+                          "README.md",
+                          "LICENSE.txt",
+                          "CHANGELOG.md",
+                          "cgminer_api_client.gemspec"
+                        ])
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 end

data/config/miners.yml.example

@@ -1,2 +1,3 @@
 - host: 127.0.0.1
-  port: 4028
+  port: 4028
+  timeout: 5

data/lib/cgminer_api_client/errors.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module CgminerApiClient
+  # Base class for all errors raised by the gem. Catch this if you want
+  # to handle every cgminer-specific failure together.
+  class Error < StandardError; end
+
+  # Raised when the gem cannot reach a miner: socket open failure, DNS
+  # failure, connect timeout, or any other transport-level problem.
+  # Distinct from ApiError so callers can tell "I never spoke to the
+  # miner" apart from "the miner spoke to me and refused."
+  class ConnectionError < Error; end
+
+  # Raised specifically for connect-timeout failures, as a subclass
+  # of ConnectionError. Lets callers distinguish "the miner took too
+  # long to answer the SYN" from other connection-layer problems.
+  class TimeoutError < ConnectionError; end
+
+  # Raised when the miner returned a response whose STATUS field
+  # indicates an error (cgminer status code 'E' or 'F'). The message
+  # contains the cgminer code and message verbatim.
+  #
+  # Carries two structured fields for dispatch: callers `case e.code`
+  # instead of parsing English messages. The integer (#cgminer_code)
+  # is preserved verbatim from cgminer; the symbol (#code) is
+  # best-effort — cgminer's MSG enum names are stable but the
+  # integers occasionally shift between firmware versions, so add a
+  # row to CGMINER_CODES when you find a wire-observed integer worth
+  # dispatching on.
+  #
+  # Prefer #code for dispatch over #cgminer_code: paths that raise
+  # without a wire integer (the access_denied? local guard's call
+  # to #privileged hits the wire, but the rescue inside #privileged
+  # drops the integer) leave #cgminer_code nil while still setting
+  # #code consistently.
+  #
+  # Backward compatibility: `raise ApiError, "msg"` keeps working
+  # and #message is unchanged at every emission site.
+  class ApiError < Error
+    CGMINER_CODES = {
+      14 => :invalid_command,
+      45 => :access_denied
+    }.freeze
+
+    attr_reader :cgminer_code, :code
+
+    # Factory used at the wire-side emission point in Miner#check_status.
+    # Picks AccessDeniedError when the cgminer integer maps to
+    # :access_denied so callers can `rescue AccessDeniedError` for
+    # the most commonly dispatched-on case; falls back to ApiError
+    # for everything else. Wire boundary stays best-effort: a
+    # non-numeric Code coerces to nil and the symbolic tag becomes
+    # :unknown rather than raising mid-poll.
+    def self.for_status(status_code, message)
+      cgminer_code = Integer(status_code, exception: false)
+      klass = CGMINER_CODES[cgminer_code] == :access_denied ? AccessDeniedError : ApiError
+      klass.new("#{status_code}: #{message}", cgminer_code: cgminer_code)
+    end
+
+    def initialize(message = nil, cgminer_code: nil, code: nil)
+      # Fail loud at the library boundary on bad input. Without these
+      # guards, cgminer_code: "45" or 45.0 silently produces code:
+      # :unknown (CGMINER_CODES uses integer keys), and code: 42 raises
+      # NoMethodError on .to_sym deep in the constructor — both
+      # opaque failure modes. Wire-side callers that want best-effort
+      # Integer coercion go through ApiError.for_status.
+      unless cgminer_code.nil? || cgminer_code.is_a?(Integer)
+        raise ArgumentError,
+              "cgminer_code must be Integer or nil, got #{cgminer_code.class}: #{cgminer_code.inspect}"
+      end
+      unless code.nil? || code.is_a?(Symbol) || code.is_a?(String)
+        raise ArgumentError,
+              "code must be Symbol, String, or nil, got #{code.class}: #{code.inspect}"
+      end
+
+      super(message)
+      @cgminer_code = cgminer_code
+      @code = (code || CGMINER_CODES[cgminer_code] || :unknown).to_sym
+    end
+  end
+
+  # Specific subclass for cgminer's "access denied" response (STATUS=E
+  # Code 45) and the gem's own #access_denied? local guard. Inherits
+  # from ApiError so existing `rescue ApiError` clauses still catch
+  # it; callers wanting finer dispatch use `rescue AccessDeniedError`
+  # instead of `case e.code; when :access_denied`. Constructor pins
+  # code: :access_denied so the symbolic tag is consistent regardless
+  # of which call site raised.
+  class AccessDeniedError < ApiError
+    def initialize(message = nil, cgminer_code: nil)
+      super(message, cgminer_code: cgminer_code, code: :access_denied)
+    end
+  end
+end

data/lib/cgminer_api_client/miner/commands.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CgminerApiClient
   class Miner
     module Commands
@@ -43,11 +45,14 @@ module CgminerApiClient
         end
 
         def privileged
-            query(:privileged)
-            true
-          rescue
-            false
-
+          query(:privileged)
+          true
+        rescue CgminerApiClient::ApiError
+          # The miner answered and rejected: not privileged.
+          false
+          # ConnectionError and any other StandardError propagate so
+          # callers don't misinterpret a transient network blip as
+          # "access denied".
         end
 
         def notify
@@ -86,9 +91,9 @@ module CgminerApiClient
           end
 
           def ascset(number, option, value = nil)
-            unless access_denied?
-              value ? query(:ascset, number, option, value) : query(:ascset, number, option)
-            end
+            return if access_denied?
+
+            value ? query(:ascset, number, option, value) : query(:ascset, number, option)
           end
         end
 
@@ -106,9 +111,9 @@ module CgminerApiClient
           end
 
           def pgaset(number, option, value = nil)
-            unless access_denied?
-              value ? query(:pgaset, number, option, value) : query(:pgaset, number, option)
-            end
+            return if access_denied?
+
+            value ? query(:pgaset, number, option, value) : query(:pgaset, number, option)
           end
         end
 
@@ -164,9 +169,9 @@ module CgminerApiClient
           end
 
           def save(filename = nil)
-            unless access_denied?
-              filename ? query(:save, filename) : query(:save)
-            end
+            return if access_denied?
+
+            filename ? query(:save, filename) : query(:save)
           end
 
           def setconfig(name, value)
@@ -181,11 +186,17 @@ module CgminerApiClient
         private
 
         def access_denied?
-          if !privileged
-            raise 'access_denied'
-          else
-            return false
-          end
+          # privileged calls query(:privileged), so the wire IS hit; if
+          # the miner answers with STATUS=E Code 45, check_status raises
+          # AccessDeniedError and privileged rescues + returns false,
+          # dropping the cgminer integer in the rescue. Re-raise the
+          # specific subclass so callers can't tell which call path
+          # raised — `rescue AccessDeniedError` works identically for
+          # "real wire denied" and "guard-locally denied". cgminer_code
+          # stays nil here because it was discarded by privileged's rescue.
+          raise CgminerApiClient::AccessDeniedError, 'access denied' unless privileged
+
+          false
         end
 
         include Miner::Commands::Privileged::Asc
@@ -198,4 +209,4 @@ module CgminerApiClient
       include Miner::Commands::Privileged
     end
   end
-end
+end

data/lib/cgminer_api_client/miner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cgminer_api_client/socket_with_timeout'
 require 'cgminer_api_client/miner/commands'
 
@@ -8,91 +10,168 @@ module CgminerApiClient
 
     attr_accessor :host, :port, :timeout
 
-    def initialize(host = nil, port = nil, timeout = nil)
-      @host    = host    ? host    : CgminerApiClient.default_host
-      @port    = port    ? port    : CgminerApiClient.default_port
-      @timeout = timeout ? timeout : CgminerApiClient.default_timeout
+    # Positional parameters at these indices carry user-controlled values
+    # (pool passwords, setconfig values, ascset/pgaset option values)
+    # that should not appear verbatim in wire-logs. The wire request is
+    # never modified; only the copy passed to the on_wire callback is
+    # redacted. If a new privileged command is added that accepts a
+    # secret positional arg, register its index here.
+    REDACTED_PARAM_INDEX = {
+      addpool: 2,
+      setconfig: 1,
+      ascset: 2,
+      pgaset: 2
+    }.freeze
+
+    def initialize(host = nil, port = nil, timeout = nil, on_wire: nil)
+      @host    = host    || CgminerApiClient.default_host
+      @port    = port    || CgminerApiClient.default_port
+      @timeout = timeout || CgminerApiClient.default_timeout
+      @on_wire = on_wire
     end
 
     def query(method, *params)
-      if available?
-        request = {command: method}
+      request, loggable_request = build_requests(method, params)
+      response = perform_request(request, loggable_request: loggable_request)
+      data = sanitized(response)
+      method.to_s.match?('\+') ? data : data[method.to_sym]
+    end
 
-        unless params.length == 0
-          params = params.map { |p| p.to_s.gsub('\\', '\\\\').gsub(',', '\,') }
-          request[:parameter] = params.join(',')
-        end
+    # Reachability probe. Opens a fresh socket every call — no
+    # caching. Returns true on a successful connect, false on
+    # transport-level failure (DNS, refused, unreachable, timeout).
+    # Bugs like ArgumentError or NoMethodError propagate instead
+    # of being silently swallowed.
+    def available?
+      open_socket(@host, @port, @timeout).close
+      true
+    rescue SocketError, SystemCallError, CgminerApiClient::TimeoutError
+      false
+    end
 
-        response = perform_request(request)
-        data = sanitized(response)
-        method.to_s.match('\+') ? data : data[method.to_sym]
-      end
+    def method_missing(name, *)
+      query(name, *)
     end
 
-    def available?(force_reload = false)
-      @available = nil if force_reload
+    # method_missing forwards everything to query as a cgminer command,
+    # so respond to anything except names that look like Ruby internals
+    # or implicit conversion probes (to_ary, to_str, to_int, to_hash, ...).
+    def respond_to_missing?(name, _include_private = false)
+      !name.to_s.start_with?('to_', '_')
+    end
 
-      @available ||= begin
-        open_socket(@host, @port, @timeout).close
-        true
-      rescue
-        false
-      end
+    private
+
+    def build_requests(method, params)
+      return [{ command: method }, { command: method }] if params.empty?
+
+      escaped          = params.map { |p| escape_param(p) }
+      loggable_escaped = redact_params(method, params).map { |p| escape_param(p) }
+
+      [
+        { command: method, parameter: escaped.join(',') },
+        { command: method, parameter: loggable_escaped.join(',') }
+      ]
     end
 
-    def method_missing(name, *args)
-      query(name, *args)
+    # cgminer uses comma to separate parameters, so any literal commas in
+    # parameter values must be backslash-escaped, and any literal
+    # backslashes must themselves be doubled. The block form of gsub is
+    # used so the replacement string isn't interpreted (in gsub's
+    # replacement-string syntax, '\\' means a single literal backslash,
+    # which makes the obvious gsub('\\', '\\\\') a silent no-op).
+    def escape_param(param)
+      param.to_s.gsub('\\') { '\\\\' }.gsub(',') { '\\,' }
     end
 
-    private
+    def redact_params(method, params)
+      idx = REDACTED_PARAM_INDEX[method.to_sym]
+      return params unless idx && params[idx]
+
+      redacted = params.dup
+      redacted[idx] = '[REDACTED]'
+      redacted
+    end
+
+    # on_wire is best-effort telemetry — a callback that raises must
+    # not break the real query path or leak the connection. Operators
+    # who suspect their callback is broken can remove -v to isolate.
+    def safe_on_wire(direction, payload)
+      return unless @on_wire
+
+      @on_wire.call(direction, @host, @port, payload)
+    rescue StandardError
+      nil
+    end
 
-    def perform_request(request)
+    def perform_request(request, loggable_request: request)
       begin
         s = open_socket(@host, @port, @timeout)
-      rescue
-        raise "Connection to #{@host}:#{@port} failed"
+      rescue StandardError => e
+        raise ConnectionError, "Connection to #{@host}:#{@port} failed: #{e.class}: #{e.message}"
       end
 
+      safe_on_wire(:request, loggable_request.to_json)
       s.write(request.to_json)
-      response = s.read.strip.chars.map { |c| c.ord >= 32 ? c : "\\u#{'%04x' % c.ord}" }.join
+      response = s.read.strip.chars.map { |c| c.ord >= 32 ? c : format('\\u%04x', c.ord) }.join
       s.close
-
-      response.gsub! '}{', '}, {'
-      response.gsub! '[,{', '[ {'
+      safe_on_wire(:response, response)
+
+      # Legacy defensive repair for malformed multi-object responses. We
+      # haven't reproduced a case where this actually fires on modern
+      # cgminer; see spec/support/cgminer_fixtures.rb for commentary.
+      # Keep in place until we can confirm it isn't needed on real traffic.
+      # If the repair ever fires, emit an additional :response_repaired
+      # callback so a broken-looking JSON log isn't mysterious.
+      repaired = response.gsub('}{', '}, {').gsub('[,{', '[ {')
+      if repaired != response
+        safe_on_wire(:response_repaired, repaired)
+        response = repaired
+      end
 
       data = JSON.parse(response)
 
-      if request[:command].to_s.match('\+')
-        data.each_pair do |command, response|
+      if request[:command].to_s.match?('\+')
+        data.each_pair do |_command, response|
           check_status(response.first) if response.respond_to?(:first)
         end
       else
         check_status(data)
       end
 
-      return data
+      data
     end
 
     def check_status(data)
-      status =   data['STATUS'][0]
+      status = data['STATUS'][0]
       sc     = status['STATUS']
       c      = status['Code']
       msg    = status['Msg']
 
+      # cgminer STATUS codes: S=Success (silent), I=Info, W=Warning,
+      # E=Error, F=Fatal. Errors and Fatals raise via ApiError.for_status
+      # which picks AccessDeniedError for Code 45 (so callers can
+      # `rescue AccessDeniedError`) and falls back to ApiError otherwise.
+      # The wire boundary stays best-effort — non-numeric Codes coerce
+      # to nil and the symbolic tag becomes :unknown rather than
+      # raising mid-poll.
       case sc
-        when 'S'
-        when 'I'
-          puts "Info from API [#{c}]: #{msg}"
-        when 'W'
-          puts "Warning from API [#{c}]: #{msg}"
-        else
-          raise "#{c}: #{msg}"
+      when 'S'
+        # no-op: success needs no notification
+      when 'I'
+        puts "Info from API [#{c}]: #{msg}"
+      when 'W'
+        puts "Warning from API [#{c}]: #{msg}"
+      else
+        raise ApiError.for_status(c, msg)
       end
     end
 
     def sanitized(data)
       if data.is_a?(Hash)
-        data.inject({}) { |n, (k, v)| n[k.to_s.downcase.tr(' ', '_').to_sym] = sanitized(v); n }
+        data.each_with_object({}) do |(k, v), n|
+          n[k.to_s.downcase.tr(' ', '_').to_sym] = sanitized(v)
+        end
       elsif data.is_a?(Array)
         data.map { |v| sanitized(v) }
       else