feat(pubsub): implement streaming keep-alive logic by torreypayne · Pull Request #34653 · googleapis/google-cloud-ruby

torreypayne · 2026-06-22T23:32:24Z

Overview

Implements proactive streaming keep-alive logic and connection health monitoring in Google::Cloud::PubSub::MessageListener::Stream, mirroring the design implemented in the .NET Pub/Sub client (dotnet#15649).

Long-running bi-directional gRPC streaming pull connections (StreamingPull) can experience silent TCP drops, intermediary network timeouts, or read deadlocks during periods of low message volume. This change introduces background timer tasks to push regular keep-alive requests and actively monitor server Pong timestamps.

Key Changes

Protocol Version Initialization: Explicitly initializes protocol_version = 1 on the initial StreamingPullRequest protobuf to enable bi-directional stream keep-alive support.
Unconditional Keep-Alive Pings: Configures a background timer task (@stream_keepalive_task) to dispatch empty StreamingPullRequest pings at regular intervals (default 30 seconds), regardless of current lease inventory volume.
Pong Monitoring & Automatic Reconnection: Introduces @pong_monitor_task to inspect timestamps (@last_ping_at, @last_pong_at). If a keep-alive response is overdue by more than pong_deadline seconds (default 15 seconds), the monitor raises RestartStream to safely recycle the connection and back off.
Concurrency Timestamp Guard: Guards ping timestamp updates (@last_ping_at = now if @last_pong_at >= @last_ping_at) to ensure consecutive un-ponged pings cannot overwrite the timestamp of an overdue request.

Testing & Validation

Unit Test Suite (keepalive_test.rb): Added targeted unit test coverage asserting protocol version flags, timer intervals, deadline timeouts, and non-disruptive Pong handling.
Resiliency & Robustness Suite: Validated against live GCP test instances (helical-zone-771) across simulated TCP socket hangs, sub-millisecond deadline starvation, and post-recovery downstream message delivery.

Fixes b/427319802

robertvoinescu-work

LGTM from a functional perspective. Just a few minor comments.

Implement bi-directional keep-alive pings and pong liveness monitoring for Cloud Pub/Sub StreamingPull streams in Ruby. - Set protocol_version = 1 in initial StreamingPullRequest to negotiate keep-alive support. - Extract KeepaliveMonitor collaborator class to manage keep-alive ping/pong timestamps, liveness checks, and timeout restarts cleanly. - Disable liveness monitor evaluation during reconnect backoff and handshake phases to prevent false-positive restarts. - Add unit, integration, and live acceptance test suites.

…undant check for '.is_a?(Stream)'

…st boilerplate and encapsulation

… semantics

…or user context per PR feedback

…PR review feedback

…meout

aandreassa

🚀

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from cf5df9b to b1acc8a Compare June 23, 2026 04:52

torreypayne marked this pull request as ready for review June 23, 2026 15:54

torreypayne requested review from a team and yoshi-approver as code owners June 23, 2026 15:54

torreypayne requested review from amanda-tarafa and robertvoinescu-work June 23, 2026 16:26

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from 94e9f14 to ad59cd2 Compare June 23, 2026 17:29

robertvoinescu-work reviewed Jun 24, 2026

View reviewed changes

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/stream.rb Outdated

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/stream.rb Outdated

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from ca925d3 to e53a9bd Compare June 26, 2026 20:41

This comment was marked as resolved.

Sign in to view

torreypayne force-pushed the pubsub-streaming-keepalive branch from 26bcbb1 to 24055fd Compare June 30, 2026 15:53

torreypayne added kokoro:run Add this label to force Kokoro to re-run the tests. kokoro:force-run Add this label to force Kokoro to re-run the tests. labels Jun 30, 2026

yoshi-kokoro removed kokoro:run Add this label to force Kokoro to re-run the tests. kokoro:force-run Add this label to force Kokoro to re-run the tests. labels Jun 30, 2026

This comment was marked as resolved.

Sign in to view

aandreassa requested changes Jul 1, 2026

View reviewed changes

quartzmo requested changes Jul 1, 2026

View reviewed changes

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/stream.rb Outdated

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/stream.rb Outdated

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from 2fa07a4 to cca4878 Compare July 7, 2026 15:36

torreypayne requested review from aandreassa and quartzmo July 7, 2026 15:41

quartzmo approved these changes Jul 7, 2026

View reviewed changes

torreypayne commented Jul 7, 2026

View reviewed changes

Comment thread google-cloud-pubsub/test/google/cloud/pubsub/message_listener/keepalive_test.rb Outdated

This comment was marked as resolved.

Sign in to view

quartzmo approved these changes Jul 8, 2026

View reviewed changes

torreypayne commented Jul 16, 2026

View reviewed changes

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/keepalive_monitor.rb

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from 43562dd to f4927d5 Compare July 16, 2026 18:43

aandreassa requested changes Jul 21, 2026

View reviewed changes

torreypayne force-pushed the pubsub-streaming-keepalive branch 3 times, most recently from 5bdc0a7 to d589b24 Compare July 22, 2026 21:53

torreypayne requested a review from aandreassa July 23, 2026 01:48

torreypayne force-pushed the pubsub-streaming-keepalive branch 2 times, most recently from 4e59244 to d998c4f Compare July 23, 2026 20:57

torreypayne force-pushed the pubsub-streaming-keepalive branch from 346a70c to 3d9d3d1 Compare July 23, 2026 21:19

aandreassa requested changes Jul 23, 2026

View reviewed changes

torreypayne added 8 commits July 23, 2026 17:11

fix(pubsub): reference 'pause_cond' instance var properly, remove red…

56554e5

…undant check for '.is_a?(Stream)'

refactor(pubsub): address PR review comments for KeepAlive monitor te…

b989378

…st boilerplate and encapsulation

fix(pubsub): strictly enforce KeepAlive encapsulation and concurrency…

4fa9380

… semantics

fix(pubsub): remove verify_keepalive.rb script and add KeepaliveMonit…

4fed850

…or user context per PR feedback

fix(pubsub): correct keepalive nil timestamp initialization

a5b01ef

docs(pubsub): add user context to KeepaliveMonitor documentation per …

f86d951

…PR review feedback

test(pubsub): verify keepalive backoff conditional variable separation

82aa8f0

test(pubsub): fix accessors in keepalive acceptance test

3360077

torreypayne requested a review from aandreassa July 27, 2026 18:57

robertvoinescu-work requested a review from a team July 27, 2026 19:06

torreypayne commented Jul 27, 2026

View reviewed changes

Comment thread google-cloud-pubsub/lib/google/cloud/pubsub/message_listener/stream.rb

torreypayne force-pushed the pubsub-streaming-keepalive branch 3 times, most recently from b90712f to 509de9d Compare July 27, 2026 23:35

test(pubsub): verify RestartStream explicit raise during keepalive ti…

1ad64d2

…meout

torreypayne force-pushed the pubsub-streaming-keepalive branch from 509de9d to 1ad64d2 Compare July 27, 2026 23:36

aandreassa approved these changes Jul 28, 2026

View reviewed changes

Uh oh!

Conversation

torreypayne commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Changes

Testing & Validation

Uh oh!

robertvoinescu-work left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aandreassa left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

torreypayne commented Jun 22, 2026 •

edited

Loading