feat!: fractional bucketing improvements

[chrfwow]

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	#1740
js-sdk-contrib	open-feature/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

Adds high resolution fractional support

Related Issues

Fixes #1738

[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 mechanism by extending its compatibility to include Number and Boolean types as bucketing keys, in addition to the existing String support. The core change involves a refactored hashing and bucketing algorithm that utilizes a high-resolution approach, aiming to provide more precise and consistent fractional evaluations across diverse input types.

Highlights

• Expanded Input Types for Fractional Targeting: The fractional targeting mechanism now supports Number and Boolean types as bucketing keys, in addition to the existing String support. This allows for more flexible and diverse input values when determining fractional distributions.
• High-Resolution Fractional Bucketing: Implemented a new high-resolution fractional bucketing algorithm. This enhancement utilizes MurmurHash3 and bit shifting operations to provide more precise and consistent fractional evaluations, especially for large numbers.
• Robust Number to Byte Array Conversion: Introduced a utility method, numberToByteArray, to consistently convert various numeric types (including Integer, Double, Long, BigInteger, Byte, Short, Float, and BigDecimal) into byte arrays. This ensures uniform input for the hashing function, improving reliability across different number representations.

Changelog

• tools/flagd-core/src/main/java/dev/openfeature/contrib/tools/flagd/core/targeting/Fractional.java
  • Updated the bucketBy variable type from String to byte[] to accommodate various input types.
  • Added logic to convert Number and Boolean arguments into byte arrays for consistent hashing.
  • Introduced a numberToByteArray helper method to handle conversions for different numeric types.
  • Modified the distributeValue method to use a new high-resolution bucketing algorithm based on MurmurHash3 and bitwise operations.
  • Adjusted the FractionProperty constructor's error message formatting.
• tools/flagd-core/src/test/resources/fractional/boolean.json
  • Added a new test case for boolean input in fractional targeting.
• tools/flagd-core/src/test/resources/fractional/largeDouble.json
  • Added a new test case for large double input in fractional targeting.
• tools/flagd-core/src/test/resources/fractional/largeInt.json
  • Added a new test case for large integer input in fractional targeting.
• tools/flagd-core/src/test/resources/fractional/selfContainedFractionalB.json
  • Modified the expected result in a fractional targeting test case.
• tools/flagd-core/src/test/resources/fractional/string.json
  • Added a new test case for string input in fractional targeting.

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.

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. ↩

[chrfwow]

Do we want more tests for this? I stuck to the current test suite

[gemini-code-assist]

Code Review

The pull request refactors the fractional targeting logic to support various input types (numbers, booleans) for bucketing by converting them to byte arrays and introduces a new numberToByteArray helper. The core bucketing algorithm was also revised to use an integer-based bit shift operation. Review comments highlight two key areas for improvement: the numberToByteArray method has a potential precision loss issue for BigDecimal and could be made more concise using ByteBuffer, and the bucketing logic has a subtle bug related to handling signed vs. unsigned integers from the MurmurHash3 function, which requires a bitmask for correct range mapping.

[chrfwow]

Idk why there are PMD errors, but I think they are unrelated and false positives

[toddbaert]

@chrfwow there was some e2e test failures but I fixed them by updating to the latest git submodule in the testkit module, and adding the v1 exclusion to the file mode suite, and excluding v2 in the RPC suite (since flagd doesn't support this yet).

I will coordinate the release of flagd, then update the RPC suite here and release everything simultaneously.

[toddbaert]

Here's the flagd implementation: open-feature/flagd#1909

@chrfwow Up to you if you want to create a new PR based on this branch, but it's probably easier to do this and this in one go, as I did above.

[chrfwow]

@toddbaert I will implement the nested fractional evaluation in a different PR

[toddbaert]

This PR looks good. Leaving this unresolved conversation to block for now though until implementations are consistent: https://github.com/open-feature/java-sdk-contrib/pull/1740/changes#r2974095951

@chrfwow related:

open-feature/flagd#1909
open-feature/flagd-schemas#207

[toddbaert]

@chrfwow I've added the nested fractional support to this PR as well, since it's not much more effort and we've done these in tandem in the other languages: ffda346