jrpc 1.1.7 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67534bff4d06dfed8a49ddf71bb56356d65f9c119731b220e6490394a187f720
-  data.tar.gz: fd53da1804ddc60f54d549811b7d866541601dc4b3f58dc15de2a112c10039cf
+  metadata.gz: e9d76a4b0925e75829ba1a406594a0ef8f0c8045e38d6a06362c3eac2892affb
+  data.tar.gz: f6f28cf60f79bd9108f82299b8cac6ada99ae3a0a80bcc85baa3fa1b51c86560
 SHA512:
-  metadata.gz: c99a86b3b5a59ff431d5356604d4cfcd1803212a8e3be22819de4bbab9d826d985a47bec9fed72cc82f8adfa80f208b1823ab85566325fe3f7965db52d631911
-  data.tar.gz: d565e6cf0cd0afa20b935d1ca6e554d2aa6142dd46bfbefd1468f4910175f326656a6015fae7a160ef5ad8da41574e0c8c9d000ea8d624e5e989e5f8683ca262
+  metadata.gz: 365d4ab7d191d4853b48f9c05875afb11e4619bf4a8a733b66bf52f8dd79bcb702c4d91bdff561088bee4086dcda01af58c3ee4ce0e89d838c8490019c827aaa
+  data.tar.gz: cb74295dd00108aa5e2de6bf93584204e903a36aa523cb6ea44cc5f18bf787c3273969a8cb18d89efbed89db8757b65ad24a45ba5ba66cd49aa2518413f989b8

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/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.rake_tasks~

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

@@ -0,0 +1,84 @@
+# Changelog
+
+### Unreleased
+
+### 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)
+
+### 1.1.7
+* connect ot socket in nonblock mode
+
+### 1.1.6
+* update oj version to ~> 3.0
+
+### 1.1.5
+* update oj version to ~> 2.0
+
+### 1.1.4
+* handle EOF on read
+* fix jrpc error require
+* use JRPC::Error as base class for JRPC::Transport::SocketBase::Error
+
+### 1.1.3
+* close socket when clearing socket if it's not closed
+
+### 1.1.2
+* reset socket when broken pipe error appears
+
+### 1.1.1
+* fix rescuing error in TcpClient initializer
+
+### 1.1.0
+* use own socket wrapper
+
+### 1.0.1
+* Net::TCPClient#read method process data with buffer variable
+
+### 1.0.0
+* stable release

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,183 @@
 # JRPC
 
-JSON RPC TCP client
+A JSON-RPC 2.0 client for Ruby, over TCP, with netstring framing.
 
-## Installation
+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 |
+
+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.
 
-Add this line to your application's Gemfile:
+## 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
+  logger:              nil
+)
+
+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)
+
+client.close      # terminal; the instance cannot be reused
+client.closed?    # => true
+client.server     # => "127.0.0.1:1234"
+```
 
-## Usage
+Behavior:
 
-TODO: Write usage instructions here
+- 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.
 
-## Contributing
+## SharedClient
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jrpc.
+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,
+  logger:                 nil
+)
+
+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
+```
 
-## License
+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
+
+`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
+```
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+## 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

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'jrpc'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)