cgminer_api_client 0.2.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df86a4b12bb2eef41633534532290139749a0491fb27d89a5c7ce55b596d4a5
-  data.tar.gz: adce4406c1bcec642a7b6698473a355a211b5c467765aaba466ef34efd563d64
+  metadata.gz: 97da0040fa9d47c7d6a8157e53a30decf6e62ca216e3fb50af638dbcc6189d7c
+  data.tar.gz: aa30a0192cbf07991b90d904ecb476558ad509d15f001d0cc1f5b3daefc0f835
 SHA512:
-  metadata.gz: 0305613f25ab54883339bb54f7155ff08b09af899d42a57dabd8dd051b6176d4aed3f698584606dd6081045756cb6ffe16035ec8abaca382271289f30859e86c
-  data.tar.gz: e093f302848547c460865383a7fd65eb48103c1dab9d2991109376ab5bc9c3c3e1d32c66140dcb031da5e65ee634f840d51dfff6a689364426b360f6099cdf91
+  metadata.gz: 73458d32d4079dc3483967d9329cf5bbbb1be4a73cd6ef8e202e3872b36ae9c18eac60bfb5ce81befe575cb0085ec1fd6f49e7df28fd7386e432ad40f83d71a3
+  data.tar.gz: 7bcde1758bd4ce3a8f111c7d21fe931683158a284de7055d3eed1be3b91bafc1ee2f8694dbd53a14173383da35e5691f2be64091dd4dbf317e3a65dc66f70bbf

data/CHANGELOG.md

@@ -0,0 +1,385 @@
+# 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).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-04-25
+
+### Added
+- **`CgminerApiClient::AccessDeniedError`**, a subclass of `ApiError`
+  for the most commonly dispatched-on case (cgminer Code 45 + the
+  `access_denied?` local guard). Inherits from `ApiError` so existing
+  `rescue ApiError` clauses still catch it; callers wanting finer
+  dispatch use `rescue AccessDeniedError`. Constructor pins
+  `code: :access_denied` so the symbolic tag is consistent. The
+  wire-side `Miner#check_status` delegates to a new factory
+  `ApiError.for_status(c, msg)` that picks the right subclass
+  based on the integer Code.
+- **Structured error codes on `CgminerApiClient::ApiError`.** Two new
+  reader methods alongside the existing `#message`:
+  `#cgminer_code` (the integer Code from cgminer's STATUS hash —
+  e.g., `45` for access denied — or `nil` if the wire integer was
+  discarded, as happens when the `access_denied?` local guard's
+  call to `privileged` hits the wire and the rescue inside
+  `privileged` drops the integer before re-raising) and `#code`
+  (a symbolic tag derived from the integer via
+  `ApiError::CGMINER_CODES`, falling back to `:unknown` for codes
+  not in the map). Callers can now `case e.code; when :access_denied`
+  instead of parsing English error strings. **Prefer `e.code` for
+  dispatch over `e.cgminer_code`** — `cgminer_code` can be nil even
+  when the symbolic tag is set. The map is intentionally
+  conservative — `14 → :invalid_command`, `45 → :access_denied`,
+  the codes observed against real cgminer wire fixtures.
+  Backward-compatible: `raise ApiError, "msg"` still works and
+  `e.message` is unchanged.
+
+### Changed
+- `ApiError` constructor now validates `cgminer_code:` is `Integer`
+  or `nil` and `code:` is `Symbol`, `String`, or `nil`. Bad input
+  raises `ArgumentError` with a clear message instead of silently
+  producing `code: :unknown` (string `cgminer_code`) or
+  `NoMethodError` deep in the constructor (`code: 42`). Wire-side
+  callers go through `ApiError.for_status` which coerces a
+  non-numeric Code to `nil` so dispatch falls through to `:unknown`.
+- **`docs/logging.md`** — short stub stating that `cgminer_api_client`
+  is intentionally silent: no `Logger` module, no structured log
+  events. The library raises on failure and returns result objects
+  on success; callers (`cgminer_monitor`, `cgminer_manager`, the
+  operator CLIs) own the log call sites. Points at
+  `cgminer_monitor/docs/log_schema.md` for the cross-repo schema
+  contract and names the events (`poll.miner_failed`,
+  `poll.unexpected_error`) that surface api_client exception classes.
+- **`bundle-audit` in CI** (`.github/workflows/ci.yml`). New `audit`
+  job runs `bundle exec bundle-audit check --update` on every push
+  and PR, gating merges on known CVEs in `Gemfile.lock`. Advisory
+  DB is refreshed on each run from `rubysec/ruby-advisory-db`. Also
+  available locally as `bundle exec rake audit`.
+- **Dependabot config** (`.github/dependabot.yml`). Weekly bump PRs
+  for Bundler and GitHub Actions, with `open-pull-requests-limit: 3`
+  per ecosystem. `versioning-strategy: lockfile-only` on bundler, so
+  Gemfile / gemspec constraints are never auto-widened — humans
+  widen `~>` bounds intentionally. Targets `develop` so bumps flow
+  through the normal release cycle alongside feature work.
+- **`-v` / `--verbose` flag on the `cgminer_api_client` CLI.** Logs the
+  JSON request and raw response to stderr, one line each, with a
+  `host:port` prefix so multi-miner fan-out output stays grep-able. The
+  formatted result still goes to stdout unchanged. Parsed via
+  `OptionParser#permute!`, so the flag works before or after the
+  command. Passwords in `addpool`, `setconfig`, `ascset`, and `pgaset`
+  are replaced with `[REDACTED]` in the log output (wire bytes are
+  unaffected).
+- **`on_wire:` kwarg on `Miner#initialize` and `MinerPool#initialize`.**
+  Library-level hook used by the CLI's `-v` flag. Accepts a Proc of
+  shape `(direction, host, port, payload)` where direction is
+  `:request`, `:response`, or `:response_repaired`. Default `nil` is a
+  no-op; library code does not write to stderr itself.
+
+### Changed
+- **`Miner::Commands::Privileged#access_denied?`** now raises
+  `CgminerApiClient::ApiError` with message `'access denied'`
+  instead of a bare `RuntimeError` with message `'access_denied'`.
+  Callers using `rescue CgminerApiClient::Error` or
+  `rescue StandardError` are unaffected; only code that specifically
+  pattern-matched on `RuntimeError` from a privileged command on an
+  unprivileged miner needs to update.
+- **`MinerPool#load_miners!`** now raises `CgminerApiClient::Error`
+  (was `RuntimeError`) when `config/miners.yml` is missing. Existing
+  `rescue StandardError` clauses still work.
+- Test-support code (FakeCgminer, CgminerFixtures) extracted to the
+  shared `cgminer_test_support` gem. Spec references now use
+  `CgminerTestSupport::FakeCgminer` and
+  `CgminerTestSupport::Fixtures::SUMMARY` etc. `script/fake_cgminer`
+  is now a thin shim that delegates to `bundle exec fake_cgminer`;
+  operator muscle memory unchanged.
+
+### Fixed
+- **`MinerPool` no longer silently defaults a miners.yml entry
+  missing `host` to `CgminerApiClient.default_host`.** A typo'd
+  config entry like `{port: 4028}` used to quietly produce a Miner
+  pointing at `127.0.0.1`; now raises
+  `CgminerApiClient::Error "config/miners.yml: entry N is missing 'host'"`
+  on `MinerPool.new`.
+
+## [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. Ships as both a Ruby library and a CLI (`cgminer_api_client <command>`). Zero runtime dependencies beyond the Ruby standard library.
 
-## 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,35 +62,122 @@ Restart cgminer:
 
 ## Gem Usage
 
-    require 'cgminer_api_client'
+```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
+```
+
+### Errors
+
+All gem-specific errors descend from `CgminerApiClient::Error < StandardError`:
+
+-   `CgminerApiClient::ConnectionError` — transport-level: the miner
+    was unreachable (DNS failure, connection refused, etc.).
+-   `CgminerApiClient::TimeoutError` — a `ConnectionError` subclass
+    for connect timeouts specifically.
+-   `CgminerApiClient::ApiError` — protocol-level: the miner answered
+    and returned a `STATUS=E`/`F` response.
+
+`rescue CgminerApiClient::Error` catches everything gem-specific.
+`rescue CgminerApiClient::ConnectionError` catches both generic
+transport failures and connect timeouts. A `MinerPool` query never
+raises per-miner errors — they land on the corresponding
+`MinerResult.failure` inside the returned `PoolResult`.
 
-    # change the default timeout and port for the miners
-    CgminerApiClient.config do |config|
-        config.default_port    = 4023
-        config.default_timeout = 3
-    end
+## CLI Usage
 
-    pool = CgminerApiClient::MinerPool.new
+API commands can be sent to your miner pool from the command line.
 
-    # run 'devs' on each miner in the pool; returns an array of response hashes
-    devices = pool.devs
+    $ cgminer_api_client <command> (<arguments>)
 
-    # run 'summary' on each miner in the pool; returns an array of response hashes
-    summaries = pool.summary
+### Exit Codes and Streams
 
-    # run 'devs' on available miners; returns an array of response hashes
-    pool.available_miners.collect do |miner|
-        miner.devs
-    end
+-   exit `0` — at least one miner's command succeeded.
+-   exit `1` — every miner failed, or a top-level exception bubbled up.
+-   exit `64` — unknown command or missing command argument (`EX_USAGE`).
 
-    # restart the pool
-    pool.restart
+Per-miner responses are printed to stdout with a `host:port:` header.
+Per-miner errors are printed to stderr as
+`host:port: ErrorClass: message`. Set `DEBUG=1` to also print full
+backtraces for any top-level exception:
 
-## CLI Usage
+    $ DEBUG=1 cgminer_api_client summary
 
-API commands can be sent to your miner pool from the command line.
+Pass `-v` / `--verbose` to log the JSON request and raw response to
+stderr for wire-level debugging. Each line carries a `host:port`
+prefix so fan-out across multiple miners stays grep-able:
 
-    $ cgminer_api_client <command> (<arguments>)
+    $ cgminer_api_client -v summary
+    >>> 10.0.0.1:4028 {"command":"summary"}
+    <<< 10.0.0.1:4028 {"STATUS":[{"STATUS":"S",...}],"SUMMARY":[...]}
+
+Password-bearing arguments to `addpool`, `setconfig`, `ascset`, and
+`pgaset` are replaced with `[REDACTED]` in the log output (the real
+value is still sent on the wire).
 
 ### Commands & Arguments
 
@@ -169,6 +243,13 @@ The following privileged miner and pool commands are currently available:
 
 Any cgminer API commands not explictly defined above are implemented using `method_missing`. A complete list of available API commands and options can be found in the [cgminer API-README](https://github.com/ckolivas/cgminer/blob/master/API-README).
 
+## Further Reading
+
+-   [`CHANGELOG.md`](CHANGELOG.md) — release history and the 0.2.x → 0.3.0 migration guide.
+-   [`AGENTS.md`](AGENTS.md) — context for AI coding assistants; also a useful conventions-and-extension guide for human contributors.
+-   [`docs/`](docs/) — topic-split deep dives on architecture, components, interfaces, data models, workflows, and dependencies. Start with [`docs/index.md`](docs/index.md).
+-   [cgminer API-README](https://github.com/ckolivas/cgminer/blob/master/API-README) — upstream documentation for the JSON API surface this gem wraps.
+
 ## Contributing
 
 1.  Fork it ( <https://github.com/jramos/cgminer_api_client/fork> )
@@ -181,7 +262,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