docs(ADR): extends the fractional operator to support up to .001% distributions

[beeme1mr]

This PR

• extends the fractional operator to support up to .001% distributions.
• defines the expected behavior of several edge cases.

Notes

Addresses a limitation of the current fractional operator that prevents sub-percent traffic allocations. In high-throughput services, 1% of traffic may represent a significant number of requests.

Related issues

#1788

[netlify]

✅ Deploy Preview for polite-licorice-3db33c ready!

Name	Link
🔨 Latest commit	069853d
🔍 Latest deploy log	https://app.netlify.com/projects/polite-licorice-3db33c/deploys/6985e3b69430b90007e0125f
😎 Deploy Preview	https://deploy-preview-1800--polite-licorice-3db33c.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gemini-code-assist]

Summary of Changes

Hello @beeme1mr, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to the fractional traffic allocation mechanism. It aims to provide much finer-grained control over traffic distribution, enabling precise sub-percent allocations critical for high-throughput environments, A/B testing, and canary deployments. The changes are designed to be backward-compatible with the existing API while improving reliability through robust error handling and validation.

Highlights

• Enhanced Fractional Operator Precision: The fractional operator now supports traffic allocation down to 0.001% granularity, achieved by increasing the internal bucket count from 100 to 100,000.
• API Compatibility Maintained: The existing weight-based API remains unchanged, ensuring backwards compatibility for current configurations.
• Robust Edge Case Handling: New logic addresses various edge cases, including minimum allocation guarantees for variants with positive weights, management of excess buckets, and validation for weight sum overflows.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is a well-written and thorough ADR that clearly outlines the proposal to enhance the fractional operator. The move to a 100,000-bucket system with a minimum allocation guarantee is a great improvement for fine-grained traffic control. My review includes a few suggestions to address potential issues with implementation details, particularly around ensuring deterministic behavior and handling all allocation scenarios correctly. These points focus on preventing bucket deficits and ensuring cross-language consistency in sorting and arithmetic.

[toddbaert]

I'm open to this solution, but I would like to understand why you think this is inferior, as it seems like an obvious choice (but maybe I'm missing something). If I am, can we record why we wouldn't be interested in that approach?

[toddbaert]

I've significantly amended this proposal after some discussions with @chrfwow . I think this new proposed solution gives us the power we want while keeping things very simple and sidestepping a lot of complexity. Please have a look.

Here is the diff, if you're interested in the change from the last proposal.

[jonathannorris]

Looks good to me, but let's keep using percentiles mainly in the examples / docs, as it can be a bit hard to understand the max int at first.

[toddbaert]

Looks good to me, but let's keep using percentiles mainly in the examples / docs, as it can be a bit hard to understand the max int at first.

Fully agree. I think if people want more granularity they will ask or dig deeper, but let's not confuse basic use-cases by exposing these details unnecessarily.

[toddbaert]

@tangenti @cupofcat any points against this proposal? Please see my most recent updates here, I think this is a fairly elegant solution.

[tangenti]

@cupofcat Could you take another look of the proposal and ensure it's compatible with the changes that will be introduced by the non-string fractional?

[cupofcat]

Hi, I have two main suggestions:

1. To make this proposal compatible with the non-string fractional and consistent hashing, we should explicitly mention it and the examples should not rely on string anymore, and string hashing.
2. I think we can completely sidestep any floating point shenanigans by working in uInt64 space and using multiplication?

So, the main example from the ADR, assuming the above, would look like this:

// distributeValue accepts the hash calculated by the "Harden Hashing" ADR logic.
// It relies purely on integer math.
func distributeValue(hashValue uint32, feDistribution *fractionalEvaluationDistribution) string {
    // 0. Validation: Handle empty distribution
    if feDistribution.totalWeight == 0 {
        return ""
    }

    // 1. Logic Integration: Use the hash provided by the non-fractional ADR.
    //    Do NOT call StringSum32(value).

    // 2. Projection: Map 32-bit hash to [0, totalWeight)
    //    We cast to uint64 to ensure the multiplication does not overflow.
    //    Shifting right by 32 bits is mathematically equivalent to dividing by 2^32.
    //    This logic is safe across major languages because it relies on fundamental binary operations.
    bucket := (uint64(hashValue) * uint64(feDistribution.totalWeight)) >> 32

    // 3. Selection: Find which variant range the bucket falls into
    var rangeEnd int64 = 0
    for _, variant := range feDistribution.weightedVariants {
        rangeEnd += int64(variant.weight)
        
        if int64(bucket) < rangeEnd {
            return variant.variant
        }
    }

    // Should be unreachable given strict validation of weights (no float, sum < MaxInt32)
    panic(...)
}

[toddbaert]

Hi, I have two main suggestions:

1. To make this proposal compatible with the non-string fractional and consistent hashing, we should explicitly mention it and the examples should not rely on string anymore, and string hashing.
2. I think we can completely sidestep any floating point shenanigans by working in uInt64 space and using multiplication?

So, the main example from the ADR, assuming the above, would look like this:

// distributeValue accepts the hash calculated by the "Harden Hashing" ADR logic.
// It relies purely on integer math.
func distributeValue(hashValue uint32, feDistribution *fractionalEvaluationDistribution) string {
    // 0. Validation: Handle empty distribution
    if feDistribution.totalWeight == 0 {
        return ""
    }

    // 1. Logic Integration: Use the hash provided by the non-fractional ADR.
    //    Do NOT call StringSum32(value).

    // 2. Projection: Map 32-bit hash to [0, totalWeight)
    //    We cast to uint64 to ensure the multiplication does not overflow.
    //    Shifting right by 32 bits is mathematically equivalent to dividing by 2^32.
    //    This logic is safe across major languages because it relies on fundamental binary operations.
    bucket := (uint64(hashValue) * uint64(feDistribution.totalWeight)) >> 32

    // 3. Selection: Find which variant range the bucket falls into
    var rangeEnd int64 = 0
    for _, variant := range feDistribution.weightedVariants {
        rangeEnd += int64(variant.weight)
        
        if int64(bucket) < rangeEnd {
            return variant.variant
        }
    }

    // Should be unreachable given strict validation of weights (no float, sum < MaxInt32)
    panic(...)
}

@cupofcat wow what a nice idea. I've updated the ADR to use this!

I think, though, that we should keep the "max weight sum" to MaxInt32 (2,147,483,647), not MaxUint32 (4,294,967,295). My reasoning for this is I believe it means we can use Java's long type to handle the intermediate product, avoiding any non-standard numeric types there (please check my math)

In either case, we will need a BigInt in JS, but they are de-factor standard now and I think we can all agree JS' numbers are lacking...

I am going to add this table to the ADR as a survey:

Language	64-bit Type	Max Value	Max Product Fits?
Go	uint64	1.8 × 10¹⁹	✅ Yes
Java	long (signed)	9.22 × 10¹⁸	✅ Yes
JavaScript	Number	9.0 × 10¹⁵ (safe)	❌ No — must use BigInt

Max product: MaxUint32 × MaxInt32 = 9.22 × 10¹⁸ (fits within Java's long with ~6 billion headroom)

@cupofcat I've added all your suggestions in this commit, with the exception of keeping the max weight as math.MaxInt32 so we can use Java long for the intermediate product.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud