Skip to content

feat(pubsub): add HedgingOptions and fixed-point HedgingTokenBucket - #36639

Draft
feywind wants to merge 2 commits into
mainfrom
hedging/options-and-token-bucket
Draft

feywind wants to merge 2 commits into
mainfrom
hedging/options-and-token-bucket

Conversation

@feywind

@feywind feywind commented Oct 16, 2026 •

Copy link
Copy Markdown

Stack Structure (Stack #36644)

Layer Branch PR
1 hedging/options-and-token-bucket #36639 (this PR)
2 hedging/coordinator-and-scheduler #36640
3 hedging/queue-integration #36641
4 hedging/queue-unit-tests #36642
5 hedging/system-tests #36643

Summary

Implements Layer 1 of Cloud Pub/Sub Publish Hedging (go/sdk:pubsub-hedging) for google-cloud-pubsub:

  • AsyncPublisher::HedgingOptions (lib/google/cloud/pubsub/async_publisher/hedging_options.rb):
    • Opt-in configuration with defaults (enabled: true, hedge_delay: 1.0, max_tokens: 50, refill_ratio: 0.1, plus delay alias).
    • Validates parameter bounds (0.1 <= hedge_delay <= 10.0, integer 1 <= max_tokens <= 250, 0.001 <= refill_ratio <= 0.2), mutual exclusion with message_ordering, and hedge_delay < publish_timeout.
  • AsyncPublisher::HedgingTokenBucket (lib/google/cloud/pubsub/async_publisher/hedging_token_bucket.rb):
    • Thread-safe fixed-point token bucket rate limiter scaled by 1,000 (1.0 logical token = 1,000 scaled units) starting at 0 tokens on cold start.
  • Unit tests (test/google/cloud/pubsub/async_publisher/hedging_token_bucket_test.rb):
    • Covers bounds/ordering/timeout validation, fixed-point fractional refills without floating-point drift, capping at max_tokens, and multi-threaded concurrent stress testing.

@amanda-tarafa

Copy link
Copy Markdown

@quartzmo and @torreypayne I've left an internal message about what's expected from this.

attr_reader :max_tokens
attr_reader :refill_ratio

alias enabled? enabled

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Between these two lines and L53-55, the naming between attributes and aliases is pretty confusing. More so code smell than poor implementation


private

def Boolean value # rubocop:disable Naming/MethodName

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll need to modify this; capitalized Ruby methods are strongly discouraged (hence the rubocop:disable). It shouldn't be too difficult to modify this to a lowercased method.

# @return [Boolean] true if a token was acquired, false otherwise.
#
def try_acquire_hedge_token
@mutex.synchronize do

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this!

@feywind
feywind force-pushed the hedging/options-and-token-bucket branch from aef4598 to 4b454ae Compare October 28, 2026 18:55

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants