feat(pubsub): add resilient parallel streaming pull

[sigurdm]

This is Part 2 of 2 in a stacked set of PRs:

1. feat(pubsub): add message and acknowledgment batching with retry infrastructure #292: Message and acknowledgment batching with retry infrastructure (pubsub-retry-batching)
2. feat(pubsub): add resilient parallel streaming pull #339 (this PR): Resilient parallel streaming pull (pubsub-streaming-pull)

---

Key Features

• Resilient Multi-Stream Streaming Pull:
  • Subscription.streamingPull with configurable maxConcurrentStreams for parallel streaming pull connections multiplexed into a single stream.
  • Automatic reconnection with exponential backoff on transient errors and disconnects.
  • Connection health tracking: backoff resets once messages are successfully received (hasReceivedItem).
  • Multi-stream failure isolation: failure on a single lane does not prematurely abort healthy peer streams under consumer await for loops.
• Batch Routing Over Active Streams:
  • Batched acknowledgments and deadline modifications from Subscription.acknowledge and modifyAckDeadline are automatically routed over active bidirectional streaming pull channels instead of separate unary RPCs.
  • Safe fallback to unary RPCs with exponential backoff retries when streams are reconnecting or unavailable.
• Low-Level Streaming Pull:
  • PubSub.streamingPullWithStream for streaming pull over an explicit request stream with bidirectional communication and clean controller teardown.
• Backpressure:
  • Pause and resume forwarding across all active parallel streams.
• Clean Teardown & Lifecycle:
  • In Subscription.close(), flushes batchers over active stream controllers and awaits request stream close before cancelling response stream subscriptions, guaranteeing flushed ACKs and deadline modifications are transmitted before stream termination.
  • Guarded requestController.add in client handlers against StateError during concurrent close.
  • Sessions registered in onListen to prevent leaks on unlistened streams.
• Documentation & Examples:
  • Added example/doc_examples.dart demonstrating long-lived streaming pull and graceful shutdown.
  • Updated README.md and CHANGELOG.md.

[sigurdm]

/gcbrun

[gemini-code-assist]

Code Review

This pull request introduces background batching and retrying of acknowledgments and deadline modifications for Pub/Sub subscriptions, along with support for parallel streaming pull connections and automatic reconnection handling. The review feedback highlights an improvement opportunity in Subscription.close(), advising against manually invoking StreamController.onCancel as it is a Dart anti-pattern, and suggests refactoring the teardown process to explicitly manage active teardown functions instead.

[sigurdm]

/gcbrun

[sigurdm]

/gcbrun

[sigurdm]

/gcbrun

[sigurdm]

/gcbrun