connectrpc 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 379e6d135bdd12a72d18d016957cd9dfb7c092518c66f68606e7cb18c20c80ff
4
- data.tar.gz: a8b9fd0ea0dc0f97d29fe56ca4ded5bb149f015592f0ec9af0d6dd81e188ec1c
3
+ metadata.gz: 960d7fe077e5d30a2ce6185ad49727509df129e76f4b385acb2a82870df995f2
4
+ data.tar.gz: a19ba6644570e7aa0027478c384523c037c82fdafba57eea8d943e0d0b8672a8
5
5
  SHA512:
6
- metadata.gz: 929994af602735175fbda3e8abe35cf9335303303ac44fa949293a5c4cf1193dee8101d9e4893022c9eff9615c7768d8ae8fb11959e33e76f1154945a693296f
7
- data.tar.gz: 84000e8bf44f090321b370cd6e1ff2cc9098279c0795fb405323a6b1da6f733ccdd94378b2949b2b77513d5d4005b35fb79625e67ebcb317792b547ef0316e6c
6
+ metadata.gz: '08b7b932519d32a323bb5ee4894a05297523b289f761ea066b2ce221408107cd70b46bcb9dac5eb3d2c931b4444cccb707dbe30d724d6eebb341d854d196ae08'
7
+ data.tar.gz: 52118df88782ea804172fb9657467add65322106f07fe22158fb6729128a5b2aa5efdb9a672c142b26796e1f6b0af98cf99e7fc33a2eb90725122b79e863508f
data/README.md CHANGED
@@ -178,6 +178,8 @@ integrations you use:
178
178
  | [`connectrpc-otel`](gems/connectrpc-otel/README.md) | You want OpenTelemetry CLIENT and SERVER spans for each RPC | `connectrpc/otel` |
179
179
  | [`connectrpc-prometheus`](gems/connectrpc-prometheus/README.md) | You want go-grpc-prometheus compatible server, client and Async connection metrics in a prometheus-client registry | `connectrpc/prometheus` |
180
180
  | [`connectrpc-yabeda`](gems/connectrpc-yabeda/README.md) | You want the same metrics through Yabeda and any of its adapters | `connectrpc/yabeda` |
181
+ | [`connectrpc-health`](gems/connectrpc-health/README.md) | You want the standard `grpc.health.v1` service (Check, List and Watch) for Kubernetes probes, `grpc_health_probe` and load balancers | `connectrpc/health` |
182
+ | [`connectrpc-sentry`](gems/connectrpc-sentry/README.md) | You use the Sentry Ruby SDK and want one native Sentry transaction or span per RPC side, plus reports of unexpected handler exceptions | `connectrpc/sentry` |
181
183
 
182
184
  Use the same version of `connectrpc` and every ConnectRPC gem in an
183
185
  application. Their `~>` dependency ranges allow patch versions to differ, but the
data/docs/design.md CHANGED
@@ -220,7 +220,7 @@ content encoding/length; transports carry opaque encoded bytes.
220
220
  Server timeout validation creates a per-call monotonic deadline. Checks run
221
221
  around input, decoding, handler execution and encoding. `cancelled?` combines explicit cancellation and expiry;
222
222
  `cancellation_reason` identifies `:canceled` or `:deadline_exceeded`, and handlers
223
- can call `check!` cooperatively. No header means no server
223
+ can call `check!` cooperatively or register `on_cancel` listeners. No header means no server
224
224
  expiry. Synchronous Rack cannot interrupt blocked input, arbitrary handlers or
225
225
  codec work, or detect every disconnect. No hard server cancellation is claimed.
226
226
 
@@ -521,6 +521,16 @@ RPC exists remains outside this scope. See the
521
521
  [OTel guide](../gems/connectrpc-otel/README.md) for trace semantics, privacy,
522
522
  HTTP instrumentation nesting and synchronous processor costs.
523
523
 
524
+ The optional Sentry package uses the same callbacks without core changes. Its
525
+ server observation nests under an open host span and ends at
526
+ `processing_finished`, because Rack and Rails hosts send their request
527
+ transaction before delivery completes; without a host span it owns a
528
+ transaction finished at the terminal callback. Client unary processing and
529
+ terminal callbacks run after activation unwinds, native hosts hold processing
530
+ through cleanup, and admission rejection finishes without attach, so each of
531
+ its callbacks is independent of the executing context. See the
532
+ [Sentry guide](../gems/connectrpc-sentry/README.md).
533
+
524
534
  ## Explicit HTTP/1.1 client ownership
525
535
 
526
536
  The Async package's independent `HTTP1Transport` uses exclusive reactor-owned
data/docs/development.md CHANGED
@@ -86,7 +86,7 @@ for final handoff; moved middleware specs have their own canonical gate.
86
86
  [CI](https://github.com/jimeh/connectrpc-ruby/blob/main/docs/ci.md) splits the same
87
87
  canonical component tasks into nine core, three Rails, four optional HTTP/2,
88
88
  two optional Rack, two optional testing, two optional RBS and four optional Falcon
89
- checks, with syntax, specs, package isolation,
89
+ checks, plus the optional OTel, metrics, health and Sentry leaves, with syntax, specs, package isolation,
90
90
  interop and official conformance on both Rubies. Hosted clean-environment and
91
91
  matrix results remain CI evidence; a local pass cannot establish them.
92
92
 
@@ -343,14 +343,16 @@ mise run floors:rails # Rails 8.0 lane, directly under the wrapper bundle
343
343
  mise run floors:otel
344
344
  mise run floors:prometheus
345
345
  mise run floors:yabeda
346
- mise run floors # all seven
346
+ mise run floors:health
347
+ mise run floors:sentry
348
+ mise run floors # all nine
347
349
  ```
348
350
 
349
351
  Floors do not apply to development tools or transitive-only dependencies. A
350
352
  launcher can add a floors-only constraint on a transitive gem through
351
353
  `DependencyFloors.gemfile(..., constraints: { ... })`; the wrapper declares it,
352
- and real Gemfiles never do. The OTel launcher constrains `json` to `< 3`
353
- because its tools otherwise resolve json 3.x, which rejects the JSON
354
+ and real Gemfiles never do. The OTel and Sentry launchers constrain `json` to
355
+ `< 3` because their tools otherwise resolve json 3.x, which rejects the JSON
354
356
  `quirks_mode` option that the Action Pack floor's ActiveSupport (Rails 8.0)
355
357
  passes. The installed package checks expect the release RubyGems activates, which can be a
356
358
  newer Ruby default gem (for example Ruby 3.4's openssl 3.3.x) than the floor.
@@ -599,6 +601,45 @@ copied generated example. See the
599
601
  [Prometheus](../gems/connectrpc-prometheus/README.md) and
600
602
  [Yabeda](../gems/connectrpc-yabeda/README.md) guides for metric semantics.
601
603
 
604
+ ## Optional health development
605
+
606
+ `mise run health:setup` installs the health service bundle with the local Rack,
607
+ Async, Falcon and testing packages under `vendor/health`. Its discoverable
608
+ `test`, `check`, `build`, `package`, `interop` and `verify` leaves write
609
+ coverage under `coverage/health/<Ruby>/`, and `floors:health` repeats specs and
610
+ package checks at the gemspec floors. Use `health:test -- spec/registry_spec.rb`
611
+ for Watch concurrency with a controllable writer and `spec/async_host_spec.rb`
612
+ for cancellation, connection loss, retirement and drain on the real Async host.
613
+ `health:interop` builds the existing `interop/grpc` peer, whose `health.go`
614
+ drives grpc-go's standard health client, and runs it against the Async Host,
615
+ real Falcon workers and grpc-go's reference server. Core's `Context#on_cancel`
616
+ is covered by `mise run test -- spec/context_on_cancel_spec.rb`. The vendored
617
+ schema and generated files belong to `generation:build`/`generation:check`.
618
+ See the [health guide](../gems/connectrpc-health/README.md).
619
+
620
+ ## Optional Sentry development
621
+
622
+ `mise run sentry:setup` installs the independent Sentry bundle under
623
+ `vendor/sentry`: sentry-ruby, sentry-rails with Rails and in-memory SQLite
624
+ ActiveRecord, sentry-opentelemetry, the OpenTelemetry SDK and the local Rack,
625
+ Rails, Async, Falcon, testing and OTel packages. They float like runtime
626
+ dependencies; only tools are pinned. Every example initializes a real SDK with
627
+ `Sentry::DummyTransport`, no background worker threads and a `.invalid` DSN, and
628
+ closes it afterwards, so specs never send events. Use
629
+ `sentry:test -- spec/rails_spec.rb` for sentry-rails nesting and exception
630
+ reporting, `spec/native_spec.rb spec/threaded_spec.rb` for real Async, Falcon and
631
+ ThreadedTransport boundaries, and `spec/lifetime_spec.rb` for promotion and the
632
+ finish scope. `sentry:check`, `sentry:build`, `sentry:package`, `sentry:example`
633
+ and `sentry:verify` are discoverable leaves; repeat
634
+ `MISE_RUBY_VERSION=4.0.9 mise run sentry:verify` for the second pinned runtime.
635
+ Coverage lives under `coverage/sentry/<Ruby>/`. `floors:sentry` runs the same
636
+ specs and package checks with sentry-ruby 6.7.0 (sentry-rails and
637
+ sentry-opentelemetry follow it) and constrains `json` to `< 3` like the OTel
638
+ lane. Package checks install the archive offline into a fresh external
639
+ GEM_HOME, require it without Rails and run the copied generated example. See
640
+ the [package guide](../gems/connectrpc-sentry/README.md) for the lifetime model
641
+ and its limits.
642
+
602
643
  ## Native streaming verification
603
644
 
604
645
  `async:test` and `falcon:test` include the incremental shape/codec/coding/security
data/docs/rbs.md CHANGED
@@ -200,6 +200,8 @@ target :app do
200
200
  library "connectrpc-otel"
201
201
  library "connectrpc-prometheus"
202
202
  library "connectrpc-yabeda"
203
+ library "connectrpc-health"
204
+ library "connectrpc-sentry"
203
205
  check "app"
204
206
  configure_code_diagnostics(Steep::Diagnostic::Ruby.strict)
205
207
  end
@@ -209,7 +211,9 @@ Each optional manifest resolves only its dependency closure. Core declares no
209
211
  Google runtime or optional hosting/tracing namespace and has no runtime tool
210
212
  dependencies. Its GoogleProtobuf binding class signature is available without
211
213
  the explicit message-runtime bridge; the binding itself still requires the
212
- optional runtime require.
214
+ optional runtime require. `library "connectrpc-health"` covers the registry and
215
+ `SERVICE` only; its generated `grpc.health.v1` messages and client are an
216
+ explicit bridge described [below](#opt-in-framework-compatibility).
213
217
 
214
218
  | Owner | Supported API and extension SPI |
215
219
  | --- | --- |
@@ -225,6 +229,8 @@ optional runtime require.
225
229
  | OTel | Subscriber configuration and narrow tracer-provider/tracer/span/propagator capabilities; SDK and context implementation remain application owned |
226
230
  | Prometheus | Metrics configuration, readers and `connection_observer`; narrow structural registry/metric capabilities for prometheus-client |
227
231
  | Yabeda | Metrics configuration, readers and `connection_observer`; Yabeda itself remains untyped and application configured |
232
+ | Health | Registry constructor, status operations and handlers; `SERVICE`, plus the generated `grpc.health.v1` messages, client and handler factory through its opt-in bridge |
233
+ | Sentry | `Subscriber.new(capture_exceptions: bool)` and `Subscriber#start`; observers are private and the Sentry SDK remains untyped and application configured |
228
234
 
229
235
  `Async::Host#close`, `Async::ServerSession#close` and `Falcon::Server#close`
230
236
  return `bool?`. Nil means a nonjoining owned request or coordinator reentry is
@@ -320,19 +326,28 @@ namespace; static types do not prove valid id lengths or sampling policy.
320
326
  ### Opt-in framework compatibility
321
327
 
322
328
  Rails inheritance and Falcon's configuration DSL need declarations for upstream
323
- classes that currently ship no RBS. Each integration packages a finite bridge
329
+ classes that currently ship no RBS. The generated health messages subclass
330
+ Google protobuf runtime classes. Each integration packages a finite bridge
324
331
  outside its automatically loaded `sig/`:
325
332
 
326
333
  | Package | Explicit signature directory | Tested upstream versions |
327
334
  | --- | --- | --- |
328
335
  | `connectrpc-on-rails` | `rbs/action_controller_8` | Newest allowed actionpack in the selected Rails lane (8.0 or 8.1) |
329
336
  | `connectrpc-falcon` | `rbs/async_service_0_25` | Newest allowed Falcon and async-service (gemspec floors 0.57.0 and 0.25.0) |
337
+ | `connectrpc-health` | `rbs/grpc_health_v1` | Generated by protoc 36.2 and `rbs=true`; requires core's `rbs/google_protobuf_4_36` or equivalent protobuf runtime signatures |
330
338
 
331
339
  Add only the selected bridge paths to an application's Steep target, using the
332
340
  same gem-relative `Pathname` pattern as the Google bridge above. Omit these
333
341
  bridges when the application already supplies declarations for those upstream
334
- classes. Normal library discovery introduces neither `ActionController` nor
335
- `Async::Service` declarations.
342
+ classes. Normal library discovery introduces no `ActionController`,
343
+ `Async::Service`, `Google::Protobuf` or `Grpc` declarations.
344
+
345
+ The health bridge holds generated `grpc.health.v1` message, client and handler
346
+ factory signatures at schema-relative paths. Steep 2.1.0 builds `library`
347
+ signatures before project `signature` paths, so these subclasses of
348
+ `Google::Protobuf::AbstractMessage` cannot live in the discovered `sig/`
349
+ without forcing protobuf runtime declarations on every consumer. Add the health
350
+ and Google bridges together.
336
351
 
337
352
  The Rails bridge covers nominal `ActionController::API` and `Base` inheritance
338
353
  and `before_action` with named Symbol callbacks. It does not type the rest of
@@ -399,7 +414,9 @@ remain unchanged. Logs and capture bindings live under ignored `vendor/rbs/`.
399
414
 
400
415
  Client and generated unary methods accept `cancellation: CancellationToken?`.
401
416
  Pass `CancellationSource.new.token`; the source itself is rejected. Tokens expose
402
- only observation and listener registration. `CancellationRegistration#unregister`
417
+ only observation and listener registration. Server handlers register listeners
418
+ with `Context#on_cancel { }`, which returns a `CancellationRegistration`.
419
+ `CancellationRegistration#unregister`
403
420
  returns bool. Token reasons are `:canceled | nil`; Context's combined
404
421
  `cancellation_reason` also admits `:deadline_exceeded`.
405
422
 
@@ -426,7 +443,7 @@ includes bounded response-head/read/finish waits. Existing unary `_Transport`
426
443
  consumers need no new method. New core streaming files participate in the strict
427
444
  implementation target, with private declarations outside gem archives. Installed
428
445
  checks generate real mixed services and run native Async/Falcon streaming over
429
- localhost with all nine normally installed packages, both composition orders,
446
+ localhost with all eleven normally installed packages, both composition orders,
430
447
  codecs and codings. These remain separate from independent Go/official evidence.
431
448
  Custom server hosts may pass `capabilities: Array[:server_stream | :client_stream |
432
449
  :bidi_stream]?` to `Server#call_stream`. Nil preserves the legacy `http2:` behavior;
@@ -478,6 +495,17 @@ prometheus-client signatures. API callers cover a custom recorder, the
478
495
  connection observer, both sinks and the message observer capabilities, with
479
496
  exact negatives for a malformed recorder and wrong namespace/group types.
480
497
 
498
+ ## Sentry types
499
+
500
+ The Sentry package declares only its subscriber: `initialize(?capture_exceptions:
501
+ bool)` and `start(Instrumentation::Call) -> Object?`. Its private observers and
502
+ helpers are classified internal in the source inventory, and no `::Sentry`
503
+ declarations ship. API callers construct both forms and start a gRPC-Web server
504
+ call; the exact negative rejects a non-boolean `capture_exceptions`. The
505
+ installed runtime check requires the package in both composition orders and
506
+ proves an uninitialized SDK observes nothing and loads neither sentry-rails nor
507
+ sentry-opentelemetry.
508
+
481
509
  ## HTTP/1 client types
482
510
 
483
511
  The Async package owns the independent `HTTP1Transport` constructor, unary
data/docs/streaming.md CHANGED
@@ -168,6 +168,9 @@ prepared bytes. Successful HTTP EOF waits for original processor completion;
168
168
  late cleanup failure aborts/reset. Admission and graceful drain include processing,
169
169
  wire tail and cleanup. Only actual peer RST_STREAM(CANCEL) signals explicit server
170
170
  Context cancellation. EOF, half-close, other reset codes and host shutdown do not.
171
+ A long-lived handler that blocks on application state can register
172
+ `context.on_cancel { ... }` to wake itself on that signal; the
173
+ [health service](../gems/connectrpc-health/README.md) Watch uses it this way.
171
174
 
172
175
  ## Bounds and protocol
173
176
 
data/docs/unary.md CHANGED
@@ -408,7 +408,13 @@ connection-wide cleanup fallback. Neither backend retries or replays a cancelled
408
408
 
409
409
  Server contexts expose `deadline`, `cancelled?`, `cancellation_reason`
410
410
  (`:canceled`, `:deadline_exceeded`, or nil), and `check!`. Handlers cooperate at
411
- application boundaries. Low-level `Server#call(cancellation:)` and the Testing
411
+ application boundaries. `context.on_cancel { ... }` registers a listener with the
412
+ same semantics as a token listener and returns its registration; unregister it
413
+ when the work it guards ends. It runs when the call's cancellation is signaled,
414
+ or when a check observes an expired deadline. A blocked handler wakes on
415
+ cancellation without polling; deadline expiry runs the listener only after a
416
+ check, so a handler waiting past its deadline needs a wait bounded by
417
+ `deadline.remaining` and a check after waking. Low-level `Server#call(cancellation:)` and the Testing
412
418
  transport accept explicit cancellation. Native HTTP/2 publishes peer
413
419
  `RST_STREAM(CANCEL)` before input teardown; normal END_STREAM/half-close, other
414
420
  reset codes, connection loss and host shutdown do not manufacture explicit
@@ -440,6 +446,11 @@ fixed go-grpc-prometheus compatible metric set through a small recorder SPI.
440
446
  The [connectrpc-prometheus](../gems/connectrpc-prometheus/README.md) and
441
447
  [connectrpc-yabeda](../gems/connectrpc-yabeda/README.md) packages are its sinks.
442
448
 
449
+ The optional [connectrpc-sentry package](../gems/connectrpc-sentry/README.md)
450
+ records the same lifecycle as native Sentry transactions and spans, propagates
451
+ `sentry-trace`/`baggage` and reports unexpected server handler exceptions,
452
+ using an application-owned Sentry SDK. Core has no Sentry dependency.
453
+
443
454
  ## Runtime baseline and evidence
444
455
 
445
456
  CRuby >= 3.4 is the baseline; project verification targets Ruby 3.4.12 and
@@ -75,6 +75,12 @@ module ConnectRPC
75
75
 
76
76
  def cancellation_reason = @cancellation.reason
77
77
 
78
+ # Runs once when the call is cancelled or its deadline is observed expired:
79
+ # synchronously in the cancelling thread, or immediately when already
80
+ # cancelled. Listeners must be short and nonblocking; StandardError is
81
+ # isolated. Unregister the returned registration when no longer needed.
82
+ def on_cancel(&) = @cancellation.on_cancel(&)
83
+
78
84
  def commit! = @cancellation.commit!
79
85
  def close = @cancellation.close
80
86
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module ConnectRPC
4
- VERSION = "0.1.1"
4
+ VERSION = "0.1.2"
5
5
  end
data/sig/connectrpc.rbs CHANGED
@@ -461,6 +461,7 @@ module ConnectRPC
461
461
  def cancelled?: () -> bool
462
462
  def check!: () -> nil
463
463
  def cancellation_reason: () -> cancellation_reason?
464
+ def on_cancel: () { () -> void } -> CancellationRegistration
464
465
  end
465
466
 
466
467
  class CodecError < StandardError
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: connectrpc
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - jimeh