feat(pubsub): integrate publish hedging into MessageQueue

[feywind]

Overview

This PR is Layer 5 of 7 in Stack #9467, which implements Publish Hedging for @google-cloud/pubsub to mitigate high-percentile (p99/p99.9) publish tail latencies by sending backup (hedged) publish RPCs when an in-flight batch takes longer than a configurable hedgeDelay threshold.

Stack Structure

1. feat(gax): support cancelling API calls via CallOptions.signal #9462 - feat(gax): support AbortSignal cancellation in CallOptions and createApiCall
2. feat(pubsub): add HedgingOptions validation and token bucket #9463 - feat(pubsub): add HedgingOptions validation and HedgingTokenBucket
3. feat(pubsub): add CancellationSharer and HedgingScheduler #9464 - feat(pubsub): add CancellationSharer and HedgingScheduler
4. feat(pubsub): add OpenTelemetry events and logging for hedged publish #9465 - feat(pubsub): add OpenTelemetry events and logging for hedged publish
5. feat(pubsub): integrate publish hedging into MessageQueue #9466 - feat(pubsub): integrate publish hedging into MessageQueue (this PR)
6. test(pubsub): add unit tests for publish hedging queue integration #9635 - test(pubsub): add unit tests for publish hedging queue integration
7. test(pubsub): add publish hedging system tests #9636 - test(pubsub): add publish hedging system tests

---

Summary of Changes in This PR

This layer wires CancellationSharer, HedgingScheduler, AbortSignal cancellation, and OpenTelemetry/logging into Publisher, MessageQueue._publish, and PubSub.prototype.request:

• PubSub.prototype.request (handwritten/pubsub/src/pubsub.ts):
  • Checks config.gaxOpts?.signal?.aborted before and after this.getClient_, immediately invoking the callback with a CANCELLED ServiceError if aborted before the GAPIC method is called.
• Publisher Lifecycle (handwritten/pubsub/src/publisher/index.ts):
  • Instantiates HedgingScheduler in setOptions when hedging is configured (logging 'Hedging rate limited due to lack of tokens.' at debug level when rate-limited) and clears any pending timer on flush().
• MessageQueue._publish & OrderedQueue (handwritten/pubsub/src/publisher/message-queues.ts):
  • Ensures OrderedQueue never hedges (allowsHedging() returns false).
  • When hedging is enabled on an unordered Queue:
    • Dispatches attempt 0 with its own AbortController and full GAX retry settings.
    • Schedules hedged attempts via hedgingScheduler.scheduleFirstHedge: each hedged attempt logs 'Publishing hedged attempt %i', records PubsubEvents.publishStartHedged, and dispatches a non-retrying (retry: null) publish RPC with timeout: attemptTimeout.milliseconds and its own AbortController.
    • Records PubsubEvents.publishEndHedged when a hedged attempt wins (or PubsubEvents.publishEnd otherwise) and resolves message callbacks with the winning attempt's messageIds.

[gemini-code-assist]

Code Review

This pull request implements publish hedging support in the Pub/Sub publisher, integrating a hedging scheduler, token bucket, and cancellation coordinator into the message queues, while ensuring ordered queues do not use hedging. It also adds support for abort signals in API requests to handle cancellations immediately. The review feedback suggests replacing shallow copies of gaxOpts with deep copies using extend to prevent accidental mutation of nested configuration options by underlying libraries.