jrpc 1.1.8 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e116c8eef34ce5bd8a4ced0e2e693ad37df69895e67c3d28d68537c60711d012
-  data.tar.gz: 8a60df19ba2676a28c03925d0be33b8cda720f9da147e4854a87cba9f25dd251
+  metadata.gz: c257edbf0909e62cffe47dc7b8a79e928b4b4c24f7166bbbbec3b7141d01270f
+  data.tar.gz: 671298a50f68328de11586e0e80eeba0ae18814ce79827b57dcd54699605c20c
 SHA512:
-  metadata.gz: 10a940570df20f1246c61c6df6d2c950e9acf5e16e397727c6693822f121bfeff14409529b732e385f2f8806ed9c26d32ddcd9c545406ab54c3b26b5e9ee6db2
-  data.tar.gz: e79fc4f45058b4aa8570928866d97fb9e473b805fbc2c730879d0d6478824e91c9a37728900fde9e827a58753978b3b9468dd03d145d6c2cd09310bafceb49e8
+  metadata.gz: 807cca67ef7ae784989daa7cf89797d9e255f77087822d1c1cae607839d02b2aed75916e5b1e75c47a11bfba5526eccd8df257fd1e36cf38029ba02e137ded28
+  data.tar.gz: c987f2beba104d457137aeaa74821db2fb6835dee9161c39c50f1e409f254efc924c8c23178cc43e07867e083d7c11ebfd1dbf8f3a70d617c652380267abc224

data/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  rspec:
+    name: RSpec (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.3'
+          - '3.4'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --parallel
+
+      - name: Run tests
+        run: bundle exec rake spec
+
+      - name: Code Coverage Summary
+        if: matrix.ruby == '3.4'
+        uses: irongut/CodeCoverageSummary@v1.3.0
+        with:
+          filename: coverage/coverage.xml
+          format: markdown
+          output: both
+
+      - name: Write coverage to job summary
+        if: matrix.ruby == '3.4'
+        run: cat code-coverage-results.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Add coverage comment to PR
+        if: matrix.ruby == '3.4' && github.event_name == 'pull_request'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          recreate: true
+          path: code-coverage-results.md

data/.rspec

@@ -1,2 +1,3 @@
 --format documentation
 --color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,228 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.3
+  DisplayStyleGuide: true
+  ExtraDetails: true
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+##################### Bundler ###############################
+
+Bundler/OrderedGems:
+  Exclude:
+    - Gemfile
+
+##################### Gemspec ###############################
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+##################### Lint ###############################
+
+Lint/UnderscorePrefixedVariableName:
+  Enabled: false
+
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Lint/UselessAccessModifier:
+  Enabled: true
+  MethodCreatingMethods:
+    - delegate
+    - attribute
+    - service_entity
+    - parameter
+    - parameters
+  ContextCreatingMethods:
+    - concerning
+    - included
+
+##################### Layout #############################
+
+Layout/LineLength:
+  Max: 311
+
+##################### Performance #########################
+
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'spec/**/*.rb'
+
+##################### Style ###############################
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/KeywordParametersOrder:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/WhenThen:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/HashAsLastArrayItem:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+  EnforcedStyle: literal
+
+Style/WordArray:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Enabled: true
+  EnforcedStyle: braces_for_chaining
+
+Style/InvertibleUnlessCondition:
+  Enabled: true
+  InverseMethods:
+    :!=: :==
+    :>: :<=
+    :<=: :>
+    :<: :>=
+    :>=: :<
+    :!~: :=~
+    :zero?: :nonzero?
+    :nonzero?: :zero?
+    :any?: :none?
+    :none?: :any?
+    :even?: :odd?
+    :odd?: :even?
+    :present?: :blank?
+    :blank?: :present?
+
+##################### Metrics #############################
+
+Metrics/PerceivedComplexity:
+  Max: 45
+
+Metrics/ClassLength:
+  Max: 1060
+
+Metrics/BlockNesting:
+  Max: 5
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 45
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 241
+
+Metrics/ParameterLists:
+  Max: 9
+
+##################### Naming ##############################
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - "iv"
+    - "by"
+    - "to"
+    - "id"
+    - "io"
+    - "on"
+
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+##################### RSpec ###############################
+
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 141
+
+RSpec/MultipleExpectations:
+  Max: 79
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/SharedExamples:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 18
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/ExampleWording:
+  Enabled: false
+
+RSpec/ExpectChange:
+  Enabled: false
+
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/ExpectInLet:
+  Enabled: true
+
+RSpec/IncludeExamples:
+  Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 ### Unreleased
 
+**New**
+
+* Debug-level wire-payload logging. When a `logger:` is configured, both
+  `SimpleClient` and `SharedClient` emit every request/response payload (the raw
+  JSON frame, exactly as written/read) at `DEBUG`, tagged `[JRPC::SimpleClient]`
+  / `[JRPC::SharedClient]` with `>>` (sent) / `<<` (received) markers. No logger,
+  no logging.
+* `JRPC::Transport::Test` — an in-process transport double for testing code that
+  uses JRPC, without a real server. Not required by default: `require
+  'jrpc/transport/test'`, then inject via `transport:` on either client. Stub
+  methods with `on('method') { |params| ... }` (return value becomes the result;
+  raise a `JRPC::Errors::ServerError` for an error response, or a transport error
+  to simulate a socket failure); records `requests`/`notifications`/`sent` for
+  assertions. A raw escape hatch (`push_response`/`push_raise`, `strict: false`)
+  covers malformed-response, id-mismatch, and orphan-frame cases. Works with both
+  `SimpleClient` and `SharedClient`. (Closes #10.)
+* Optional TCP MD5 Signature (RFC2385) support. Pass `tcp_md5_pass:` to
+  `SimpleClient`/`SharedClient` (or the transport directly) to authenticate the
+  connection with a per-peer MD5 key. Linux-only (`TCP_MD5SIG`); the key is
+  installed on the socket before connect, and a connect on a kernel/platform
+  without `TCP_MD5SIG` raises `ConnectionError`.
+
+### 2.0.0
+
+Full rewrite. JRPC 2.0 is not API-compatible with 1.x.
+
+**New**
+
+* `JRPC::SharedClient` — one shared instance, one connection, serving many caller
+  threads and/or fibers. Owns a dedicated transport thread that multiplexes
+  responses by id. Supports Puma threads, rage-rb/Falcon fibers, and mixed
+  thread/fiber callers. Fiber callers require a spec-compliant `Fiber.scheduler`.
+  (Internally drafted as `ThreadQueueClient`; never shipped under that name.)
+* `JRPC::SimpleClient` — single-threaded client, the functional replacement for
+  the old `TcpClient`.
+* `concurrent-ruby` (`~> 1.2`) added as a runtime dependency (backs the shared
+  client's result futures).
+* `logger` added as an explicit runtime dependency (no longer guaranteed bundled
+  on Ruby 3.5+).
+
+**Removed / breaking**
+
+* `JRPC::TcpClient` removed — use `JRPC::SimpleClient`.
+* `JRPC::BaseClient` removed, including the `BaseClient.connect` block helper.
+* All top-level error constants moved under `JRPC::Errors::*`.
+* `method_missing` magic removed — pass the full method name as a String or Symbol.
+* `invoke_request` / `invoke_notification` removed.
+* `perform_request` removed — use `request` and `notification`.
+* `namespace:` option removed.
+* Umbrella `timeout:` option removed — use `read_timeout` / `write_timeout` /
+  `connect_timeout` (`SimpleClient`), or `ttl:` (`SharedClient`).
+* `close_after_sent:` renamed to `autoclose:`.
+* `connect_retry_count` default changed from `10` to `0`.
+* Constructors no longer connect eagerly — the first call connects.
+* Malformed responses now raise `Errors::MalformedResponseError` (a `ServerError`),
+  not `ClientError`. In 1.x the missing-comma-terminator case raised `ClientError`.
+* `SimpleClient` read/write/connect timeouts now raise `Errors::Timeout`, not
+  `ConnectionError`.
+* `oj` runtime dependency dropped — JRPC uses stdlib `json`. For Oj speed,
+  `require 'oj'; Oj.mimic_JSON` yourself.
+* `netstring` is no longer a dependency — framing is owned in-tree by the transport.
+* `required_ruby_version` set to `>= 3.3` (the floor where the
+  `ConditionVariable` ↔ `Fiber.scheduler` cooperation that fiber callers depend on
+  is verified).
+* `bin/jrpc` and `bin/jrpc-shell` rewritten on top of `SimpleClient`; flag/usage
+  changes (see `README.md` and `jrpc --help`).
+
 ### 1.1.8
 * handling FIN signal for TCP socket [didww/jrpc#19](https://github.com/didww/jrpc/pull/19)
 * add gem executables [didww/jrpc#19](https://github.com/didww/jrpc/pull/19)

data/Gemfile

@@ -1,4 +1,21 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in jrpc.gemspec
 gemspec
+
+gem 'bundler'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+
+# Provides a real Fiber.scheduler for the fiber-caller specs (SharedClient §9.8).
+gem 'async', '~> 2.0'
+
+gem 'rubocop', '~> 1.21'
+gem 'rubocop-performance'
+gem 'rubocop-rspec'
+gem 'rubocop-rake', '~> 0.7.1'
+
+gem 'simplecov', '~> 0.22', require: false
+gem 'simplecov-cobertura', '~> 3.1', require: false

data/README.md

@@ -1,33 +1,260 @@
 # JRPC
 
-JSON RPC TCP client
+[![Gem Version](https://badge.fury.io/rb/jrpc.svg)](https://rubygems.org/gems/jrpc)
+[![CI](https://github.com/didww/jrpc/actions/workflows/ci.yml/badge.svg)](https://github.com/didww/jrpc/actions/workflows/ci.yml)
 
-## Installation
+A JSON-RPC 2.0 client for Ruby, over TCP, with netstring framing.
+
+JRPC ships two clients with sharp, separate responsibilities:
+
+| | `JRPC::SimpleClient` | `JRPC::SharedClient` |
+|---|---|---|
+| Concurrency | single thread/fiber only | shared across many threads **and/or** fibers |
+| Connection | one socket, lazy connect | one shared socket, dedicated transport thread |
+| Multiplexing | one in-flight call at a time | many in-flight calls, id-demuxed |
+| Timeouts | per-call `read_timeout`/`write_timeout` | per-message `ttl` |
+| Use it for | CLI tools, scripts, one-shot calls, per-thread pools | Rails+Puma, rage-rb, Falcon, any long-lived shared client |
 
-Add this line to your application's Gemfile:
+Pick `SimpleClient` unless you need one client instance to serve concurrent callers. It is not thread-safe or fiber-safe; use one instance per thread/fiber (or a pool). Pick `SharedClient` when a single process-wide instance must serve many caller threads or fibers over a single connection.
+
+## Installation
 
 ```ruby
 gem 'jrpc'
 ```
 
-And then execute:
+```sh
+$ bundle install
+```
 
-    $ bundle
+Requires **Ruby >= 3.3**. Fiber callers additionally require a spec-compliant `Fiber.scheduler` (e.g. [`async`](https://github.com/socketry/async)) on their thread — see [Fiber callers](#fiber-callers).
 
-Or install it yourself as:
+## SimpleClient
 
-    $ gem install jrpc
+```ruby
+client = JRPC::SimpleClient.new(
+  "127.0.0.1:1234",
+  connect_timeout:     60,    # total wall-clock budget for connect, across retries (seconds)
+  read_timeout:        60,
+  write_timeout:       60,
+  connect_retry_count: 0,     # retries after the first failed connect
+  autoclose:           false, # close the socket after every call
+  id_prefix:           nil,   # random per instance if nil
+  tcp_md5_pass:        nil,   # RFC2385 TCP MD5 Signature key (Linux-only); nil disables
+  logger:              nil    # when set, logs every wire payload at DEBUG; nil disables
+)
 
-## Usage
+result = client.request(:sum, [1, 2])
+result = client.request(:sum, [1, 2], read_timeout: 10, write_timeout: 10)
+client.notification(:log, { msg: "hi" })
+client.notification(:log, { msg: "hi" }, write_timeout: 10)
 
-TODO: Write usage instructions here
+client.close      # terminal; the instance cannot be reused
+client.closed?    # => true
+client.server     # => "127.0.0.1:1234"
+```
 
-## Contributing
+Behavior:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jrpc.
+- The constructor does **not** open the connection. The first `request`/`notification` connects.
+- `autoclose: true` closes the socket in an `ensure` after each call. The **client is still reusable** — the next call reconnects. `autoclose` controls the socket, not the client.
+- `#close` is **terminal**. After it, `#closed?` is `true` and every call raises `ClientError("client closed")`. There is no reopen — make a new client.
+- Not thread-safe, not fiber-safe.
 
+## SharedClient
 
-## License
+One instance, one connection, many concurrent callers. A dedicated transport thread owns the socket and demultiplexes responses by id.
+
+```ruby
+client = JRPC::SharedClient.new(
+  "127.0.0.1:1234",
+  connect_timeout:        60,
+  connect_retry_count:    0,
+  connect_retry_interval: 0.5,
+  write_timeout:          5,      # MUST be < default_ttl (see below)
+  reap_timeout:           nil,    # nil = never close an idle connection
+  default_ttl:            30,     # per-message lifetime, seconds
+  max_queue_size:         10_000, # bounded; pass nil for unbounded (opt-in OOM risk)
+  id_prefix:              nil,
+  tcp_md5_pass:           nil,    # RFC2385 TCP MD5 Signature key (Linux-only); nil disables
+  logger:                 nil     # when set, logs every wire payload at DEBUG; nil disables
+)
+
+result = client.request(:sum, [1, 2])
+result = client.request(:sum, [1, 2], ttl: 10)
+
+client.notification(:log, { msg: "hi" })
+client.notification(:log, { msg: "hi" }, ttl: 5)
+client.notification(:metric, [1], fire_and_forget: true) # send errors/TTL expiry are logged, not raised
+
+client.close              # graceful shutdown, default timeout: 5 seconds
+client.close(timeout: 10)
+client.closed?
+client.server
+```
+
+Behavior:
+
+- **TTL, not per-call timeout.** Each message carries `expires_at = now + ttl`. The transport thread is the timer authority; the caller blocks until the message resolves, fails, or its TTL elapses. `ttl: nil` blocks forever (opt-in).
+- **`write_timeout < default_ttl` is enforced.** While the transport thread is parked in a single `write_frame`, it cannot fire TTL deadlines for other messages, so `write_timeout` is the maximum TTL-firing lag. The constructor raises `ArgumentError` if `write_timeout >= default_ttl`.
+- **`notification` blocks until sent by default** (send errors propagate). Pass `fire_and_forget: true` to return immediately; then send errors and TTL expiry are logged, not raised. `request` never accepts `fire_and_forget`.
+- **Bounded queue.** When the outbound queue is at `max_queue_size`, enqueue raises `ClientError("queue full")`.
+- **Connection drops** resolve every in-flight request with `ConnectionError`; the transport thread keeps running and reconnects on the next message.
+- **Reaping.** With `reap_timeout` set, the connection closes after that many idle seconds (no in-flight messages, empty queue, no bytes received) and reopens on the next message.
+- `#close` is graceful: it lets in-flight work drain up to `timeout`, then force-closes. It returns `true` on a clean join, `false` on a forced close. Idempotent.
+- A crash in the transport thread is surfaced, not hidden: in-flight requests fail with `ConnectionError`, the client transitions to an unusable state, and every subsequent call raises `ClientError("client unusable: transport thread exited")`. The client does not auto-restart — instantiate a new one.
+
+### Fiber callers
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+`SharedClient` is shareable across the full Ruby concurrency matrix:
+
+| Deployment | Caller is a... |
+|---|---|
+| Rails + Puma | Thread |
+| rage-rb | Fiber under a single-thread Async reactor |
+| Rails + Falcon | Fiber under a multi-thread Async reactor |
+| Mixed | Some threads, some fibers, one client instance |
+
+A caller blocks in a scheduler-aware wait, so a fiber under `Async`/`Falcon`/`rage-rb` **yields to the reactor** instead of stalling its OS thread; other fibers keep running and the response is routed back to the right fiber. This requires:
+
+- Ruby **>= 3.3** (where the `ConditionVariable` ↔ `Fiber.scheduler` cooperation is verified), and
+- a spec-compliant `Fiber.scheduler` active on the caller's thread, with correct cross-thread `unblock` (Async and Polyphony qualify).
+
+No scheduler library is a runtime dependency — callers bring their own. Plain (non-scheduler) fibers are unsupported: they would block the OS thread on every wait. Use `SimpleClient` for non-scheduler code.
+
+## Errors
+
+All errors live under `JRPC::Errors::*` and descend from `JRPC::Errors::Error`. The four public-facing classes are siblings (no inheritance between them), so rescue each by name or rescue `Errors::Error` to catch all:
+
+```
+Errors::Error (RuntimeError)
+├── Errors::ClientError          # caller-side: bad args, bad URI, client closed, queue full
+├── Errors::ConnectionError      # cannot connect, or connection died (see Exception#cause)
+├── Errors::Timeout              # message TTL elapsed, or SimpleClient read/write/connect timeout
+└── Errors::ServerError          # peer returned an error, or the response was unusable
+       attr_reader :code         # nil for malformed responses
+       ├── Errors::ParseError              # -32700
+       ├── Errors::InvalidRequest          # -32600
+       ├── Errors::MethodNotFound          # -32601
+       ├── Errors::InvalidParams           # -32602
+       ├── Errors::InternalError           # -32603
+       ├── Errors::InternalServerError     # -32099..-32000
+       ├── Errors::UnknownError            # any other code
+       └── Errors::MalformedResponseError  # bad framing/JSON, id mismatch, wrong jsonrpc version
+```
+
+`MalformedResponseError` is a `ServerError`, not a `ClientError`: a malformed response is the peer's fault.
+
+```ruby
+begin
+  client.request(:do_thing, [1, 2])
+rescue JRPC::Errors::ServerError => e
+  warn "rpc error #{e.code}: #{e.message}"
+rescue JRPC::Errors::Timeout
+  warn "timed out"
+rescue JRPC::Errors::ConnectionError => e
+  warn "connection: #{e.message} (cause: #{e.cause})"
+end
+```
+
+## JSON serialization
+
+JRPC uses the stdlib `json`. To swap in [oj](https://github.com/ohler55/oj) for speed, monkey-patch it yourself before use:
+
+```ruby
+require 'oj'
+Oj.mimic_JSON
+```
+
+## TCP MD5 Signature (RFC2385)
+
+Both clients accept `tcp_md5_pass:` to enable per-connection authentication via the
+[TCP MD5 Signature option](https://www.rfc-editor.org/rfc/rfc2385). The kernel signs and
+verifies every TCP segment with `MD5(key + segment + addresses/ports)`; a peer with a
+mismatched or absent key has its segments silently dropped, so the handshake never
+completes.
+
+```ruby
+client = JRPC::SimpleClient.new("10.0.0.2:1234", tcp_md5_pass: "shared-secret")
+```
+
+- **Linux-only.** It relies on the `TCP_MD5SIG` socket option (and a kernel built with
+  `CONFIG_TCP_MD5SIG`). When `tcp_md5_pass` is set on a platform/kernel without it, the
+  first connect raises `ConnectionError` — the option never silently no-ops.
+- **The server must be configured with the same key for this client's address.** JRPC
+  only sets the client side; the peer (e.g. a router/BGP-style endpoint, or another
+  socket with a matching `TCP_MD5SIG`) must agree on the key.
+- **Key length is capped at 80 bytes** (`TCP_MD5SIG_MAXKEYLEN`); a longer key raises
+  `ConnectionError`.
+- The key is installed on the socket **before** connect, so it also protects the
+  handshake itself. It survives reconnects (reaping, connection drops) transparently.
+
+## Testing
+
+`JRPC::Transport::Test` is an in-process transport double for testing code that
+talks to a JSON-RPC server, without standing up a real one. It is **not** loaded
+by default — require it explicitly from your test setup:
+
+```ruby
+require 'jrpc/transport/test'
+
+transport = JRPC::Transport::Test.new
+transport.on('sum') { |params| params['a'] + params['b'] }
+
+client = JRPC::SimpleClient.new('test', transport: transport)
+client.request('sum', { 'a' => 1, 'b' => 2 }) # => 3
+
+transport.last_request # => { "jsonrpc" => "2.0", "method" => "sum", "params" => {...}, "id" => "..." }
+```
+
+Inject it through the `transport:` option of either `SimpleClient` or `SharedClient`.
+
+**Handlers** are the high-level API. A handler's return value is encoded as a result
+response echoing the request id. Raise to produce other outcomes:
+
+```ruby
+# JSON-RPC error response (mapped back to the matching JRPC::Errors class on the caller):
+transport.on('lookup') { raise JRPC::Errors::MethodNotFound, 'no such method' }
+
+# Simulated socket-level failure, raised when the client reads the response:
+transport.on('flaky') { raise JRPC::Transport::Base::ConnectionError, 'peer reset' }
+```
+
+In **strict mode (the default)** a request for a method with no handler raises
+`JRPC::Transport::Test::UnexpectedRequest` at write time, so a missing stub fails
+loudly instead of hanging. Pass `strict: false` to drive reads entirely with the
+raw escape hatch:
+
+```ruby
+transport = JRPC::Transport::Test.new(strict: false)
+# Feed literal response frames — for malformed responses, id mismatches, orphans:
+transport.push_response({ 'jsonrpc' => '2.0', 'id' => 'abc', 'result' => 42 })
+transport.push_raise(JRPC::Transport::Base::MalformedFrame.new('garbage'))
+```
+
+Other helpers: `fail_connect(error)` arms `connect` to raise; `requests`,
+`notifications`, and `sent` expose recordings for assertions; `reset` clears
+recordings and queued frames (keeping handlers). The transport opens a Unix
+socketpair so `SharedClient`'s `IO.select` loop works — call `shutdown` (e.g. in an
+`after` hook) for deterministic FD cleanup, or let the GC finalizer reclaim it.
+
+## CLI tools
+
+Two executables ship with the gem:
+
+- `jrpc` — one-shot request/notification from the shell (`jrpc --help`).
+- `jrpc-shell` — an interactive REPL (`connect`, `request`, `notification`, `disconnect`).
+
+Both use `SimpleClient`.
+
+## Upgrading from 1.x
+
+2.0 is a full rewrite with many breaking changes (`JRPC::TcpClient`/`BaseClient` removed, error constants moved under `JRPC::Errors::*`, `method_missing`/`namespace:` dropped, no eager connect, and more). See the [CHANGELOG](CHANGELOG.md) for the complete list.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/didww/jrpc.
+
+## License
 
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'jrpc'