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 +4 -4
- data/README.md +2 -0
- data/docs/design.md +11 -1
- data/docs/development.md +45 -4
- data/docs/rbs.md +34 -6
- data/docs/streaming.md +3 -0
- data/docs/unary.md +12 -1
- data/lib/connectrpc/deadline.rb +6 -0
- data/lib/connectrpc/version.rb +1 -1
- data/sig/connectrpc.rbs +1 -0
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 960d7fe077e5d30a2ce6185ad49727509df129e76f4b385acb2a82870df995f2
|
|
4
|
+
data.tar.gz: a19ba6644570e7aa0027478c384523c037c82fdafba57eea8d943e0d0b8672a8
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
|
353
|
-
because
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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
|
data/lib/connectrpc/deadline.rb
CHANGED
|
@@ -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
|
data/lib/connectrpc/version.rb
CHANGED
data/sig/connectrpc.rbs
CHANGED