feat!: fractional bucketing improvements

[leakonvalinka]

High-precision and nested fractional

This is a coordinated feature across flagd and all flagd providers.

• fractional now supports up to max-int32 total weight and 1/max-int32 resolution as described in the high-precision fractional bucketing ADR
• fractional now supports computed (nested JSONLogic) variants and weights as described in the fractional ADR
• Includes e2e tests from the flagd-testbed v3.1.0...v3.4.0 to validate consistent fractional bucketing across all provider implementations
• ⚠️ Pseudorandom hash assignments will change with this release due to changes in the hashing algorithm; update flagd and your providers to ensure fractional assignment is consistent across all workloads

Related PRs

Component	PR
flagd	open-feature/flagd#1909
java-sdk-contrib	open-feature/java-sdk-contrib#1740
js-sdk-contrib	#1501
python-sdk-contrib	open-feature/python-sdk-contrib#373
dotnet-sdk-contrib	open-feature/dotnet-sdk-contrib#622
flagd-schemas	open-feature/flagd-schemas#207

Warning
@toddbaert will coordinate the release across flagd and all providers. Do not merge without coordination.
@toddbaert will update the RPC mode tests accordingly once the associated flagd PR is merged and an up-to-date flagd-testbed image is available.

---

Original PR description

• allows bucketing weights summing up to MaxInt32 (=2,147,483,647)
• allows nesting of and within the fractional operator
• allows all primitives as bucket variants

Related Issues

#1493 and #1492

Follow-up Tasks

Remove the exclusion of @fractional-v2 and fractional-nested from RPC e2e tests once flagd supports these changes

How to test

New unit tests and gherkin (e2e) tests

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly enhances the fractional targeting operator by expanding its capabilities to handle larger bucketing weights, support a wider range of variant types, and allow for more complex, nested expressions within its configuration. These changes improve the flexibility and robustness of feature flag rollouts, enabling more granular control and dynamic variant assignments.

Highlights

• Fractional Weight Capacity: Increased the maximum sum of bucketing weights to Math.MaxInt32 (2,147,483,647) by utilizing BigInt for calculations, preventing overflow issues with large integer weights.
• Nested Fractional Operators: Enabled the nesting of 'if' and 'var' expressions within the fractional operator for dynamic variant assignment and computed weights.
• Primitive Variant Support: Extended support for bucket variants to include all primitive types (string, number, boolean, and null), enhancing flexibility in flag configurations.
• Single-Bucket Fractional Lists: Allowed fractional rules to be configured with a single bucket, simplifying 100% traffic allocation scenarios.
• Weight Validation and Clamping: Introduced validation to ensure weights are integers and total weight does not exceed MaxInt32, and negative computed weights are now clamped to 0.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request 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.

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 pull request significantly enhances the fractional targeting rule in flagd-core. Key improvements include expanded variant type support (now allowing strings, numbers, booleans, and null), improved weight handling with validation for integer weights, clamping of negative weights to zero, and a check to prevent total weight overflow using Math.MaxInt32. The bucketing calculation now uses BigInt for enhanced precision with large integer weights, enabling sub-percent granularity. Additionally, the rule now supports single-bucket configurations. Extensive new test cases have been added to cover these new capabilities and edge cases. E2E tests have been updated to temporarily exclude new fractional features, indicating ongoing development. The flagd-core test harness subproject has also been updated. There is no feedback to provide.