cgminer_api_client 0.2.6 → 0.3.0

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'
 
@@ -9,39 +11,51 @@ 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
+      @host    = host    || CgminerApiClient.default_host
+      @port    = port    || CgminerApiClient.default_port
+      @timeout = timeout || CgminerApiClient.default_timeout
     end
 
     def query(method, *params)
-      if available?
-        request = {command: method}
-
-        unless params.length == 0
-          params = params.map { |p| p.to_s.gsub('\\', '\\\\').gsub(',', '\,') }
-          request[:parameter] = params.join(',')
-        end
-
-        response = perform_request(request)
-        data = sanitized(response)
-        method.to_s.match('\+') ? data : data[method.to_sym]
+      request = { command: method }
+
+      unless params.empty?
+        # 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).
+        params = params.map { |p| p.to_s.gsub('\\') { '\\\\' }.gsub(',') { '\\,' } }
+        request[:parameter] = params.join(',')
       end
+
+      response = perform_request(request)
+      data = sanitized(response)
+      method.to_s.match?('\+') ? data : data[method.to_sym]
     end
 
-    def available?(force_reload = false)
-      @available = nil if force_reload
+    # 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
 
-      @available ||= begin
-        open_socket(@host, @port, @timeout).close
-        true
-      rescue
-        false
-      end
+    def method_missing(name, *)
+      query(name, *)
     end
 
-    def method_missing(name, *args)
-      query(name, *args)
+    # 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
 
     private
@@ -49,12 +63,12 @@ module CgminerApiClient
     def perform_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
 
       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! '}{', '}, {'
@@ -62,37 +76,44 @@ module CgminerApiClient
 
       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 ApiError so callers
+      # can distinguish them from ConnectionError (transport-level
+      # failures).
       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, "#{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

data/lib/cgminer_api_client/miner_pool.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CgminerApiClient
   class MinerPool
     include Miner::Commands
@@ -13,56 +15,100 @@ module CgminerApiClient
       load_miners!
     end
 
+    # Runs `method` against every miner in the pool in parallel and
+    # returns a PoolResult — an Enumerable wrapper around a
+    # MinerResult per miner, in pool order. Successes and failures
+    # are both captured structurally; this method does NOT write
+    # to stderr. Callers that want to display failures should
+    # iterate the result (or use PoolResult#errors).
     def query(method, *params)
-      threads = @miners.collect do |miner|
+      threads = @miners.map do |miner|
         Thread.new do
-          begin
-            miner.query(method, *params)
-          rescue => e
-            $stderr.puts "#{e.class}: #{e}"
-            []
-          end
+          MinerResult.success(miner, miner.query(method, *params))
+        rescue StandardError => e
+          MinerResult.failure(miner, e)
         end
       end
-      threads.each { |thr| thr.join }
-      threads.collect(&:value)
+      threads.each(&:join)
+      PoolResult.new(threads.map(&:value))
+    end
+
+    # The Commands::ReadOnly convenience methods that unwrap
+    # single-element cgminer responses with `query(:name)[0]` make
+    # sense on a single Miner, but on a MinerPool they silently
+    # returned only the first miner's hash — a pre-existing latent
+    # bug masked by always calling .first on the result.
+    #
+    # Override them here to return a PoolResult where each
+    # successful MinerResult carries the unwrapped hash instead of
+    # the one-element array. Failures pass through unchanged.
+    %i[summary coin config version].each do |cmd|
+      define_method(cmd) do
+        unwrap_first(query(cmd))
+      end
+    end
+
+    def check(command)
+      unwrap_first(query(:check, command))
     end
 
-    def available_miners(force_reload = false)
-      threads = @miners.collect do |miner|
+    def available_miners
+      threads = @miners.map do |miner|
         Thread.new do
-          begin
-            miner if miner.available?(force_reload)
-          rescue
-            nil
-          end
+          # Suppress Ruby's default "auto-print unhandled thread
+          # exceptions to stderr" behavior. Bugs that propagate
+          # here will be re-raised by Thread#value to the caller of
+          # #available_miners; we don't want them double-reported
+          # to stderr in the meantime.
+          Thread.current.report_on_exception = false
+          miner if miner.available?
+        rescue SocketError, SystemCallError, CgminerApiClient::TimeoutError
+          # Miner#available? already returns false for these; this
+          # rescue is defensive against a future refactor. Bugs
+          # (NoMethodError, ArgumentError) still propagate via
+          # Thread#value re-raising.
+          nil
         end
       end
-      threads.each { |thr| thr.join }
-      threads.collect(&:value).compact
+      threads.each(&:join)
+      threads.map(&:value).compact
     end
 
-    def unavailable_miners(force_reload = false)
-      @miners - available_miners(force_reload)
+    def unavailable_miners
+      @miners - available_miners
     end
 
-    def method_missing(name, *args)
-      query(name, *args)
+    def method_missing(name, *)
+      query(name, *)
+    end
+
+    # See Miner#respond_to_missing? for the rationale.
+    def respond_to_missing?(name, _include_private = false)
+      !name.to_s.start_with?('to_', '_')
     end
 
     private
 
+    # Rebuild a PoolResult where each successful MinerResult's
+    # value is replaced with value.first (i.e. the unwrapped
+    # single-element response). Failures pass through unchanged.
+    def unwrap_first(pool_result)
+      PoolResult.new(pool_result.results.map do |r|
+        r.ok? ? MinerResult.success(r.miner, r.value.first) : r
+      end)
+    end
+
     def load_miners!
       raise 'Please create config/miners.yml' unless File.exist?('config/miners.yml')
 
-      miners_config = YAML.load_file('config/miners.yml')
-      @miners = miners_config.collect{|miner|
+      miners_config = YAML.safe_load_file('config/miners.yml')
+      @miners = miners_config.collect do |miner|
         CgminerApiClient::Miner.new(
           miner['host'],
           miner['port'],
           miner['timeout']
         )
-      }
+      end
     end
   end
-end
+end

data/lib/cgminer_api_client/miner_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CgminerApiClient
+  # A single per-miner outcome from a MinerPool query. Either a
+  # successful response (error is nil, value holds the parsed data)
+  # or a failure (value is nil, error holds the exception).
+  #
+  # Immutable value object backed by Data.define, which gives us
+  # ==, hash, eql?, inspect, to_h, and deconstruct_keys for pattern
+  # matching for free.
+  #
+  # Usage:
+  #   result = pool.summary.first
+  #   if result.ok?
+  #     puts result.value[:mhs_av]
+  #   else
+  #     warn "#{result.miner.host}: #{result.error.message}"
+  #   end
+  #
+  # Or with pattern matching:
+  #   case result
+  #   in { ok?: true, value: }  then use(value)
+  #   in { ok?: false, error: } then log(error)
+  #   end
+  MinerResult = Data.define(:miner, :value, :error) do
+    def self.success(miner, value)
+      new(miner: miner, value: value, error: nil)
+    end
+
+    def self.failure(miner, error)
+      new(miner: miner, value: nil, error: error)
+    end
+
+    def ok?
+      error.nil?
+    end
+
+    def failed?
+      !ok?
+    end
+
+    # Re-raise the captured error, or return the value if successful.
+    # Equivalent to `result.ok? ? result.value : raise(result.error)`
+    # but shorter at call sites.
+    def raise!
+      raise error if failed?
+
+      value
+    end
+  end
+end

data/lib/cgminer_api_client/pool_result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module CgminerApiClient
+  # An Enumerable wrapper around Array<MinerResult> returned from
+  # every MinerPool query. Preserves miner order (position N in the
+  # pool maps to position N in the result). Callers can either
+  # iterate per-Result for full control, or use the high-level
+  # helpers for common cases.
+  #
+  # Usage:
+  #   result = pool.summary
+  #   result.values          # [{mhs_av: ..., elapsed: ...}]  — successes only
+  #   result.errors          # [<ConnectionError>, ...]       — failures only
+  #   result.successful      # [<MinerResult>, ...]           — ok? Results
+  #   result.failed          # [<MinerResult>, ...]           — !ok? Results
+  #   result.all_successful? # true if every miner succeeded
+  #   result.any_succeeded?  # true if at least one miner succeeded
+  #   result.any_failed?     # true if any miner failed
+  #   result[0]              # MinerResult at index 0
+  #   result[miner]          # MinerResult for a specific Miner instance
+  #   result["10.0.0.1:4028"] # MinerResult by "host:port" string
+  #   result.each { |r| r.miner.host }  # iterates MinerResult instances
+  class PoolResult
+    include Enumerable
+
+    attr_reader :results
+
+    def initialize(results)
+      @results = results.freeze
+    end
+
+    def each(&)
+      @results.each(&)
+    end
+
+    def size
+      @results.size
+    end
+
+    def empty?
+      @results.empty?
+    end
+
+    def to_a
+      @results.dup
+    end
+
+    def values
+      @results.select(&:ok?).map(&:value)
+    end
+
+    def errors
+      @results.reject(&:ok?).map(&:error)
+    end
+
+    def successful
+      @results.select(&:ok?)
+    end
+
+    def failed
+      @results.reject(&:ok?)
+    end
+
+    def all_successful?
+      @results.all?(&:ok?)
+    end
+
+    def any_succeeded?
+      @results.any?(&:ok?)
+    end
+
+    def any_failed?
+      @results.any?(&:failed?)
+    end
+
+    # Lookup by integer index, Miner instance, or "host:port" string.
+    def [](key)
+      case key
+      when Integer then @results[key]
+      when String  then @results.find { |r| "#{r.miner.host}:#{r.miner.port}" == key }
+      else              @results.find { |r| r.miner == key }
+      end
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && @results == other.results
+    end
+    alias eql? ==
+
+    def hash
+      @results.hash
+    end
+  end
+end

data/lib/cgminer_api_client/socket_with_timeout.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CgminerApiClient
   module SocketWithTimeout
     def open_socket(host, port, timeout)
@@ -10,21 +12,25 @@ module CgminerApiClient
         begin
           socket.connect_nonblock(sockaddr)
         rescue IO::WaitWritable
-          if IO.select(nil, [socket], nil, timeout)
+          if socket.wait_writable(timeout)
             begin
               socket.connect_nonblock(sockaddr)
             rescue Errno::EISCONN
-              # the socket is connected
-            rescue
+              # On Linux, the second connect_nonblock on a now-writable
+              # socket reports EISCONN to mean "the connection completed
+              # while we were waiting." Treat as success. On other
+              # platforms the second call returns 0 cleanly and this
+              # branch never fires.
+            rescue StandardError
               socket.close
               raise
             end
           else
             socket.close
-            raise "Connection timeout"
+            raise CgminerApiClient::TimeoutError, "Connection to #{host}:#{port} timed out after #{timeout}s"
           end
         end
       end
     end
   end
-end
+end

data/lib/cgminer_api_client/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CgminerApiClient
-  VERSION = "0.2.6"
+  VERSION = "0.3.0"
 end

data/lib/cgminer_api_client.rb

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'socket'
-require 'thread'
 require 'yaml'
 
-require "cgminer_api_client/miner"
-require "cgminer_api_client/miner/commands"
-require "cgminer_api_client/miner_pool"
-require "cgminer_api_client/socket_with_timeout"
-require "cgminer_api_client/version"
+require 'cgminer_api_client/errors'
+require 'cgminer_api_client/miner_result'
+require 'cgminer_api_client/pool_result'
+require 'cgminer_api_client/miner'
+require 'cgminer_api_client/miner_pool'
+require 'cgminer_api_client/version'
 
 module CgminerApiClient
   def self.default_host
@@ -37,4 +39,4 @@ module CgminerApiClient
   def self.config
     yield self if block_given?
   end
-end
+end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: cgminer_api_client
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.3.0
 platform: ruby
 authors:
 - Justin Ramos
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: ''
+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.
 email:
 - justin.ramos@gmail.com
 executables:
@@ -18,33 +19,29 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
-- ".whitesource"
-- Gemfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - bin/cgminer_api_client
 - cgminer_api_client.gemspec
 - config/miners.yml.example
 - lib/cgminer_api_client.rb
+- lib/cgminer_api_client/errors.rb
 - lib/cgminer_api_client/miner.rb
 - lib/cgminer_api_client/miner/commands.rb
 - lib/cgminer_api_client/miner_pool.rb
+- lib/cgminer_api_client/miner_result.rb
+- lib/cgminer_api_client/pool_result.rb
 - lib/cgminer_api_client/socket_with_timeout.rb
 - lib/cgminer_api_client/version.rb
-- spec/cgminer_api_client/miner/commands_spec.rb
-- spec/cgminer_api_client/miner_pool_spec.rb
-- spec/cgminer_api_client/miner_spec.rb
-- spec/cgminer_api_client_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/jramos/cgminer_api_client
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  source_code_uri: https://github.com/jramos/cgminer_api_client
+  changelog_uri: https://github.com/jramos/cgminer_api_client/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jramos/cgminer_api_client/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -52,20 +49,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
-signing_key: 
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A gem that allows sending API commands to a pool of cgminer instances
-test_files:
-- spec/cgminer_api_client/miner/commands_spec.rb
-- spec/cgminer_api_client/miner_pool_spec.rb
-- spec/cgminer_api_client/miner_spec.rb
-- spec/cgminer_api_client_spec.rb
-- spec/spec_helper.rb
+test_files: []

data/.gitignore

@@ -1,16 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
-config/miners.yml
-._*

data/.rspec

@@ -1,3 +0,0 @@
---color
---warnings
---require spec_helper

data/.travis.yml

@@ -1,5 +0,0 @@
-language: ruby
-rvm:
-  - 2.6
-notifications:
-  email: false

data/.whitesource

@@ -1,8 +0,0 @@
-##########################################################
-#### WhiteSource "Bolt for Github" configuration file ####
-##########################################################
-
-# Configuration #
-#---------------#
-ws.repo.scan=true
-vulnerable.check.run.conclusion.level=failure

data/Gemfile

@@ -1,10 +0,0 @@
-source 'https://rubygems.org'
-
-gemspec
-
-group :development do
-  gem 'pry' ,       '>= 0.12.0'
-  gem 'rake' ,      '>= 13.0.0'
-  gem 'rspec' ,     '>= 3.9'
-  gem 'simplecov' , '>= 0.17.0'
-end

data/Rakefile

@@ -1,7 +0,0 @@
-require "bundler/gem_tasks"
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec
-task :test => :spec