cgminer_api_client 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df86a4b12bb2eef41633534532290139749a0491fb27d89a5c7ce55b596d4a5
-  data.tar.gz: adce4406c1bcec642a7b6698473a355a211b5c467765aaba466ef34efd563d64
+  metadata.gz: 129410d116f95439ef734a1ae6265c047eb7f95007755e5788fc416e78741388
+  data.tar.gz: 386bd4f91ce093e290777a1b00be6efaa173f03f951b8bcc00d4b8683ce0c576
 SHA512:
-  metadata.gz: 0305613f25ab54883339bb54f7155ff08b09af899d42a57dabd8dd051b6176d4aed3f698584606dd6081045756cb6ffe16035ec8abaca382271289f30859e86c
-  data.tar.gz: e093f302848547c460865383a7fd65eb48103c1dab9d2991109376ab5bc9c3c3e1d32c66140dcb031da5e65ee634f840d51dfff6a689364426b360f6099cdf91
+  metadata.gz: d7ebd6316421e95755768cf0f77dd672e3860c2fd508fd2314cc898f46b9c76d39efc78d3b1f4ac422c873871e1896b5fb8859e681c8ff3712f5f60f12c85351
+  data.tar.gz: 99a4578907f13668e8f0bf5cf466298f40774e318d3f470ad38df7f0cfa2455b51c028866084a264201156b6e30505daf7849e1d6a12aec4122ec5092d788fed

data/CHANGELOG.md

@@ -0,0 +1,286 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-04-07
+
+### Removed
+- Support for Ruby 2.x and Ruby 3.1. The gem now requires Ruby 3.2 or higher.
+- `Miner#query`'s short-circuit on `!available?`. `query` now calls
+  `perform_request` directly and lets `ConnectionError` propagate to
+  the caller. Previously an unreachable miner caused `query` to
+  return `nil` silently.
+- `Miner#available?`'s `force_reload` parameter. The method no
+  longer caches, so the parameter is meaningless.
+- `MinerPool#available_miners` and `MinerPool#unavailable_miners`
+  `force_reload` parameter. Same reason.
+- The host:port-prefixed stderr warning inside `MinerPool#query`
+  (added earlier in the 0.3.0 cycle). Library code should not
+  print unsolicited; the error is now structurally available via
+  `PoolResult` and the CLI prints it explicitly.
+- `pry` from the development dependencies (it was unused).
+- `.travis.yml` (Travis CI is effectively deprecated for OSS Ruby).
+- `.whitesource` (Mend Bolt for GitHub was sunset; if SCA is wanted
+  later, configure Dependabot via `.github/dependabot.yml`).
+
+### Added
+- **`CgminerApiClient::MinerResult`** — immutable value object
+  (backed by `Data.define`) wrapping a single per-miner outcome.
+  Has `miner`, `value`, `error`, `ok?`, `failed?`, `raise!`,
+  plus free `==`, `hash`, `eql?`, `inspect`, `to_h`, and
+  `deconstruct_keys` from `Data.define` for pattern matching.
+- **`CgminerApiClient::PoolResult`** — Enumerable wrapper around
+  `Array<MinerResult>` returned from every `MinerPool` query.
+  Preserves miner order. High-level helpers: `#values`, `#errors`,
+  `#successful`, `#failed`, `#all_successful?`, `#any_succeeded?`,
+  `#any_failed?`, plus `#[](key)` for lookup by index, Miner
+  instance, or `"host:port"` string.
+- `CgminerApiClient::Error`, `CgminerApiClient::ConnectionError`,
+  `CgminerApiClient::TimeoutError` (subclass of ConnectionError),
+  and `CgminerApiClient::ApiError` exception classes. All subclass
+  the base `Error` which itself subclasses `StandardError`, so
+  existing rescues keep working.
+- `respond_to_missing?` on `Miner` and `MinerPool` so introspection
+  (`respond_to?`, `Object#method`, etc.) reflects the dynamic API
+  surface while excluding internal probes (`to_*`, `_*`).
+- `# frozen_string_literal: true` pragma on every Ruby file.
+- `required_ruby_version >= 3.2` in the gemspec.
+- Gemspec metadata (`source_code_uri`, `changelog_uri`,
+  `bug_tracker_uri`, `rubygems_mfa_required`).
+- RuboCop with `rubocop-rspec` and `rubocop-rake` plugins,
+  integrated into the default Rake task.
+- GitHub Actions CI matrix testing Ruby 3.2, 3.3, 3.4, and 4.0
+  (plus `head` as an early-warning, allowed to fail).
+- `.ruby-version` file pinning local development to 4.0.2 (the
+  gem itself supports 3.2+; the pin is only for contributors).
+- `CHANGELOG.md` (this file).
+- Unit test coverage brought to 99.66% on `lib/` (was 97.4% before
+  the 0.3.0 work). The entire `SocketWithTimeout#open_socket`
+  method, `MinerPool#available_miners`, `#unavailable_miners`,
+  the thread-rescue branch in `MinerPool#query`, the control-
+  character escape path in `Miner#perform_request`, and the new
+  `MinerResult` / `PoolResult` value objects all have dedicated
+  specs.
+- End-to-end integration test suite at `spec/integration/`.
+  `miner_integration_spec.rb` exercises the full request → TCP
+  socket → response → parse → result path against a `FakeCgminer`
+  server running in a background thread. `cli_spec.rb` spawns
+  the real binary via `Open3` and asserts on exit codes,
+  stdout/stderr split, and `DEBUG=1` backtrace behavior.
+- `script/fake_cgminer` for manual sandbox testing. Starts the
+  same fake cgminer server on a fixed port (default 4028) in the
+  foreground, so you can run the CLI against it without hardware.
+  Intentionally lives in `script/` rather than `bin/` so it isn't
+  packaged with the gem.
+
+### Changed
+- **`MinerPool#query` now returns a `PoolResult`** instead of an
+  `Array` with `[]` sentinels for failed miners. Callers iterate
+  `MinerResult` instances and explicitly distinguish success from
+  failure. Failed miners are no longer confused with successful
+  ones returning empty arrays.
+- **`MinerPool` now overrides `summary`, `coin`, `config`,
+  `version`, and `check`** to return a `PoolResult` of unwrapped
+  hashes. Previously these convenience methods called
+  `query(:name)[0]`, which silently returned only the *first*
+  miner's hash on multi-miner pools (a pre-existing latent bug).
+- **`Miner#query` now raises `ConnectionError`** instead of
+  returning `nil` when a miner is unreachable. Single-Miner
+  callers need to rescue; MinerPool callers get the error
+  captured in a `MinerResult.failure` automatically.
+- **`Miner#available?` is now a true reachability probe.** No
+  cache, narrow rescue list (only `SocketError`,
+  `SystemCallError`, and `TimeoutError` — bugs like `ArgumentError`
+  propagate). Always re-checks.
+- `SocketWithTimeout` raises `CgminerApiClient::TimeoutError`
+  instead of a bare `RuntimeError` on connect timeout.
+- `Miner#perform_request` raises `ConnectionError` (not
+  `RuntimeError`) on socket open failure, with a message that
+  includes the original error class and message.
+- `Miner#check_status` raises `ApiError` (not `RuntimeError`) for
+  cgminer status codes `E` and `F`.
+- **`bin/cgminer_api_client` redesigned**: errors go to stderr
+  (not stdout), exit codes follow shell conventions (0 on any
+  success, 1 on all-failure, 64/EX_USAGE on unknown command),
+  `DEBUG=1` env var prints full backtraces via
+  `Exception#full_message`, and output is structured per-miner
+  with `host:port:` headers.
+- `YAML.load_file` → `YAML.safe_load_file` for the miners config.
+- `IO.select(nil, [socket], nil, timeout)` →
+  `socket.wait_writable(timeout)` in `SocketWithTimeout` —
+  Fiber-scheduler compatible.
+- `String#match` → `String#match?` where the result is only used
+  as a boolean.
+- `length == 0` → `empty?`, `'%04x' %` → `format`, and other
+  small modernizations.
+- Bare `rescue` clauses now specify `StandardError` explicitly.
+- Gemspec file list switched from `git ls-files` to explicit
+  `Dir.glob` patterns; `spec/` is no longer packaged in the gem.
+- Bumped minimum versions of `rake`, `rspec`, and `simplecov`.
+
+### Fixed
+- **`Miner#query` parameter escape was a silent no-op for
+  backslashes.** The intent was to double literal backslashes so
+  they round-trip through cgminer's comma-separated parameter
+  syntax, but `gsub('\\', '\\\\')` is parsed as "replace `\` with
+  `\`" because in gsub's replacement-string DSL, `\\` denotes a
+  single literal backslash. Fixed by switching to
+  `gsub('\\') { '\\\\' }` (block form bypasses replacement-string
+  interpretation). Verified empirically; locked down by four
+  explicit specs.
+- **`Miner::Commands#privileged` mislabeled connection errors as
+  access denied.** Previously rescued every `StandardError` and
+  returned `false`, which propagated through `access_denied?` to
+  raise `'access_denied'` from every privileged command
+  (`addpool`, `restart`, `quit`, `save`, `ascset`, etc.) during a
+  transient network outage — sending operators chasing phantom
+  auth/whitelist bugs. Now rescues only `ApiError` so
+  connection-layer failures surface as `ConnectionError` instead.
+- **`MinerPool#summary` / `#coin` / `#config` / `#version` /
+  `#check` silently returned only the first miner's hash on
+  multi-miner pools.** The inherited `Miner::Commands::ReadOnly`
+  methods do `query(:name)[0]` to unwrap cgminer's single-element
+  response arrays, which works on a single Miner but drops every
+  result except the first on a pool. Fixed by overriding all five
+  on `MinerPool` to return a `PoolResult` of unwrapped hashes.
+- **`Miner#available?` permanently cached `false` after any
+  transient failure.** Once a brief network blip had marked a
+  miner unavailable, the gem refused to talk to it for the
+  lifetime of the process. Fixed by dropping the cache entirely.
+- Mismatched indentation in `def privileged` that was producing a
+  Ruby parser warning.
+
+## Migration guide: 0.2.x → 0.3.0
+
+This release intentionally contains breaking changes to finish
+cleanups that were overdue. The gem is still on 0.x and only
+~2,600 of 35,000 total downloads are on 0.2.6, so the
+migration surface is small. Here's what to update.
+
+### Ruby 3.2+
+
+The gemspec now requires Ruby 3.2. If you're on 3.1 or older, you
+need to upgrade Ruby before you can use this release.
+
+### `MinerPool#query` (and all pool commands) return `PoolResult`
+
+```ruby
+# Before (0.2.x)
+pool.summary.each { |s| puts s[:mhs_av] }
+pool.summary.first[:mhs_av]
+
+# After (0.3.0)
+pool.summary.values.each { |s| puts s[:mhs_av] }
+pool.summary.values.first[:mhs_av]
+
+# Or iterate per-miner with failure handling:
+pool.summary.each do |result|
+  if result.ok?
+    puts "#{result.miner.host}: #{result.value[:mhs_av]}"
+  else
+    warn "#{result.miner.host}: #{result.error.message}"
+  end
+end
+```
+
+`PoolResult` includes `Enumerable`, so `.first`, `.map`, `.count`,
+`.find` etc. all work — but now they yield `MinerResult`
+instances, not raw hashes. Use `.values` to get just the
+successful values as an Array.
+
+### `Miner#query` raises `ConnectionError` instead of returning `nil`
+
+```ruby
+# Before (0.2.x)
+result = miner.summary
+return unless result   # nil meant unreachable
+puts result[:mhs_av]
+
+# After (0.3.0)
+begin
+  result = miner.summary
+  puts result[:mhs_av]
+rescue CgminerApiClient::ConnectionError => e
+  warn "miner unreachable: #{e.message}"
+end
+```
+
+If you're using `MinerPool` instead of `Miner` directly, you
+don't need to change anything — `MinerPool` catches the
+`ConnectionError` per miner and turns it into a
+`MinerResult.failure`.
+
+### `MinerPool#summary` etc. now return every miner, not just the first
+
+If you were calling `pool.summary` on a multi-miner pool and
+relying on getting back a single Hash, you were actually being
+bitten by a pre-existing bug (the result was silently dropping
+every miner except the first). Now you get a `PoolResult` with
+one entry per miner. Use `.values.first` if you really want
+just the first miner.
+
+### `force_reload` parameter removed
+
+```ruby
+# Before (0.2.x)
+pool.available_miners(true)   # force re-check
+miner.available?(true)
+
+# After (0.3.0)
+pool.available_miners         # always re-checks
+miner.available?
+```
+
+There's no cache to flush anymore.
+
+### `MinerPool#query` no longer writes to stderr
+
+Previously, a failed per-miner query would print
+`[host:port] ErrorClass: message` to stderr as a side effect of
+calling `pool.query`. That was an earlier 0.3.0 addition; it's
+removed because library code shouldn't print. The error is now
+carried structurally in the `MinerResult.failure` inside the
+`PoolResult`, and you can display it however you want. The CLI
+(`bin/cgminer_api_client`) does display it on stderr.
+
+### CLI exit codes changed
+
+```
+# Before (0.2.x)
+cgminer_api_client summary     # exit 0 whether or not it worked
+                                # errors written to stdout
+
+# After (0.3.0)
+cgminer_api_client summary     # exit 0 if any miner succeeded,
+                                # 1 if all failed,
+                                # 64 for unknown command.
+                                # errors on stderr.
+DEBUG=1 cgminer_api_client summary  # also prints full backtraces
+```
+
+If you had a shell pipeline that captured the CLI's stdout
+expecting the whole data blob (including errors), your script
+needs updating. Errors now go to stderr like they should.
+
+### Exception class hierarchy
+
+All gem-specific errors now inherit from
+`CgminerApiClient::Error < StandardError`:
+
+```
+CgminerApiClient::Error
+├── CgminerApiClient::ConnectionError
+│   └── CgminerApiClient::TimeoutError
+└── CgminerApiClient::ApiError
+```
+
+Existing `rescue StandardError` clauses keep working. If you
+want to catch everything the gem raises, `rescue CgminerApiClient::Error`
+now works.
+
+## [0.2.6] - earlier
+
+See git history for changes prior to 0.3.0.

data/README.md

@@ -1,28 +1,15 @@
-# CgminerApiClient [![Codacy Badge](https://api.codacy.com/project/badge/Grade/b59cb27aeae64f7c992f7072c5909788)](https://app.codacy.com/app/justin_28/cgminer_api_client?utm_source=github.com&utm_medium=referral&utm_content=jramos/cgminer_api_client&utm_campaign=Badge_Grade_Dashboard) [![Build Status](https://travis-ci.org/jramos/cgminer_api_client.png?branch=master)](https://travis-ci.org/jramos/cgminer_api_client) [![DepShield Badge](https://depshield.sonatype.org/badges/jramos/cgminer_api_client/depshield.svg)](https://depshield.github.io)
+# CgminerApiClient
 
-A gem that allows sending API commands to a pool of cgminer instances.
+[![CI](https://github.com/jramos/cgminer_api_client/actions/workflows/ci.yml/badge.svg)](https://github.com/jramos/cgminer_api_client/actions/workflows/ci.yml)
 
-## Requirements
-
--   Ruby (~> 2.0.0, ~> 2.1.0)
-    -   YAML
-    -   JSON
-    -   Socket
-    -   Thread
--   cgminer (~> 3.12.0)
+A gem that allows sending API commands to a pool of [cgminer](https://github.com/ckolivas/cgminer) instances.
 
-## GUI
+## Requirements
 
--   <https://github.com/jramos/cgminer_manager>
+Ruby 3.2 or higher.
 
 ## Installation Options
 
-### Bundler
-
-Add the following to your `Gemfile`:
-
-    gem 'cgminer_api_client', '~> 0.2.6'
-
 ### RubyGems
 
     $ gem install cgminer_api_client
@@ -32,18 +19,18 @@ Add the following to your `Gemfile`:
     $ git clone git@github.com:jramos/cgminer_api_client.git
     $ cd cgminer_api_client
     $ gem build cgminer_api_client.gemspec
-    $ gem install cgminer_api_client-0.2.6.gem
+    $ gem install cgminer_api_client-<VERSION>.gem
 
 ## Configuration
 
 Copy [`config/miners.yml.example`](https://github.com/jramos/cgminer_api_client/blob/master/config/miners.yml.example) to `config/miners.yml` and update with the IP addresses (and optional ports and timeouts) of your cgminer instances. E.g.:
 
-    # connect to localhost on the default port (4028) with the default timeout (5 seconds)
+    # connect to localhost on default port (4028) with default timeout (5 seconds)
     - host: 127.0.0.1
-    # connect to 192.168.1.1 on a non-standard port (1234) with a custom timeout (1 second)
+    # connect to 192.168.1.1 on port (1234) with custom timeout (3 seconds)
     - host: 192.168.1.1
       port: 1234
-      timeout: 1
+      timeout: 3
 
 ### Remote API Access
 
@@ -75,29 +62,74 @@ Restart cgminer:
 
 ## Gem Usage
 
-    require 'cgminer_api_client'
-
-    # change the default timeout and port for the miners
-    CgminerApiClient.config do |config|
-        config.default_port    = 4023
-        config.default_timeout = 3
-    end
-
-    pool = CgminerApiClient::MinerPool.new
-
-    # run 'devs' on each miner in the pool; returns an array of response hashes
-    devices = pool.devs
-
-    # run 'summary' on each miner in the pool; returns an array of response hashes
-    summaries = pool.summary
-
-    # run 'devs' on available miners; returns an array of response hashes
-    pool.available_miners.collect do |miner|
-        miner.devs
-    end
-
-    # restart the pool
-    pool.restart
+```ruby
+require 'cgminer_api_client'
+
+# Change the defaults for any miners whose config doesn't set them.
+CgminerApiClient.config do |config|
+  config.default_port    = 4028
+  config.default_timeout = 3
+end
+
+pool = CgminerApiClient::MinerPool.new
+```
+
+### Pool queries return a `PoolResult`
+
+Every pool query returns a `PoolResult` — an `Enumerable` wrapper
+around one `MinerResult` per miner, in pool order. Each
+`MinerResult` is either a success (carrying a parsed value) or a
+failure (carrying the exception). Callers choose how much detail
+they care about.
+
+```ruby
+# Just give me the data, ignore failures:
+pool.summary.values.each do |s|
+  puts "hashrate: #{s[:mhs_av]}"
+end
+
+# Handle successes and failures explicitly:
+pool.summary.each do |result|
+  if result.ok?
+    puts "#{result.miner.host}: #{result.value[:mhs_av]}"
+  else
+    warn "#{result.miner.host}: #{result.error.message}"
+  end
+end
+
+# Quick checks:
+pool.summary.all_successful?   # true if every miner responded
+pool.summary.any_failed?       # true if any miner failed
+pool.summary.errors            # [<ConnectionError>, ...]
+pool.summary['10.0.0.5:4028']  # lookup by host:port string
+```
+
+### Single-miner access
+
+If you want to talk to one specific miner without the pool
+wrapping, use `Miner` directly. Unreachable miners raise
+`CgminerApiClient::ConnectionError`:
+
+```ruby
+miner = CgminerApiClient::Miner.new('10.0.0.5', 4028)
+begin
+  puts miner.summary[:mhs_av]
+rescue CgminerApiClient::ConnectionError => e
+  warn "miner unreachable: #{e.message}"
+end
+```
+
+### Privileged commands
+
+Commands like `restart`, `quit`, `save`, `addpool`, `removepool`,
+`ascset`, etc. require privileged API access on the cgminer side.
+They propagate `CgminerApiClient::ApiError` on rejection and
+`CgminerApiClient::ConnectionError` on network failure — two
+distinct conditions, unlike in 0.2.x where they were conflated.
+
+```ruby
+pool.restart      # PoolResult of per-miner outcomes
+```
 
 ## CLI Usage
 
@@ -181,7 +213,7 @@ Any cgminer API commands not explictly defined above are implemented using `meth
 
 If you find this gem useful, please consider donating.
 
-BTC: `18HFFqZv2KJMHPNwPes839PJd5GZc4cT3U`
+BTC: `bc1q00genlpcpcglgd4rezqcurf4t4taz0acmm9vea`
 
 ## License
 

data/bin/cgminer_api_client

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 $LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib/")
 
@@ -8,15 +9,33 @@ require 'pp'
 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 command (arguments)'
+  warn "commands: #{commands.sort.join(', ')}"
+  warn ''
+  warn 'Set DEBUG=1 to see full backtraces on errors.'
+  exit 64 # EX_USAGE
 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
+  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,23 @@
+# 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.
+  class ApiError < Error; 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,9 @@ module CgminerApiClient
         private
 
         def access_denied?
-          if !privileged
-            raise 'access_denied'
-          else
-            return false
-          end
+          raise 'access_denied' unless privileged
+
+          false
         end
 
         include Miner::Commands::Privileged::Asc
@@ -198,4 +201,4 @@ module CgminerApiClient
       include Miner::Commands::Privileged
     end
   end
-end
+end