docs: new fractional features (#1923)

* update public facing JSON schema for rules:
https://flagd.dev/schema/v0/flags.json,
https://flagd.dev/schema/v0/targeting.json
* update fractional docs
*
https://deploy-preview-1923--polite-licorice-3db33c.netlify.app/reference/custom-operations/fractional-operation/#nested-conditional-variants
*
https://deploy-preview-1923--polite-licorice-3db33c.netlify.app/reference/custom-operations/fractional-operation/#computed-weights-with-jsonlogic
* new playground demo
*
https://deploy-preview-1923--polite-licorice-3db33c.netlify.app/playground/?scenario-name=Gradual+rollout
* minor improvements to playground (better button click feedback) and
fix bug with sharing scenarios (URL encoding) (NOTE: the schema
validation warning here will be fixed once the PR is merged and we
publish the schema update mentioned in point 1 above)

---------

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>

Author: toddbaert

docs/playground/playground.js

@@ -72,9 +72,9 @@ The bucketing value expression can be omitted, in which case a concatenation of
 The `fractional` operation is a custom JsonLogic operation which deterministically selects a variant based on
 the defined distribution of each variant (as a relative weight).
 This works by hashing ([murmur3](https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp))
-the given data point, converting it into an int in the range [0, 99].
-Whichever range this int falls in decides which variant
-is selected.
+the given data point and using an algorithm leveraging pure integer arithmetic, with `math.MaxInt32` (2,147,483,647) as the maximum weight sum.
+This provides consistent, efficient, sub-percent granularity (down to ~0.00000005%) for high-throughput environments.
+Whichever bucket this falls in decides which variant is selected.
 As hashing is deterministic we can be sure to get the same result every time for the same data point.
 
 The `fractional` operation can be added as part of a targeting definition.
@@ -86,7 +86,7 @@ The other elements in the array are nested arrays with the first element represe
 There is no limit to the number of elements.
 
 > [!NOTE]
-> Older versions of the `fractional` operation were percentage based, and required all variants weights to sum to 100.
+> Previous versions of the `fractional` operation used percentage-based weights that had to sum to 100 and were limited to 1% precision.
 
 ## Example
 
@@ -160,6 +160,117 @@ Result:
 Notice that rerunning either curl command will always return the same variant and value.
 The only way to get a different value is to change the email or update the `fractional` configuration.
 
+## Nested Fractional Evaluation
+
+The `fractional` operation supports nested JSONLogic expressions within its arguments, enabling advanced use cases.
+
+### Nested Conditional Variants
+
+Conditional logic within each bucket:
+
+```json
+"fractional": [
+  [
+    {
+      "if": [
+        { "in": [{ "var": "locale" }, ["us", "ca"]] },
+        "red",
+        "grey"
+      ]
+    },
+    25
+  ],
+  [
+    "blue",
+    25
+  ],
+  [
+    "green",
+    25
+  ],
+  [
+    "grey",
+    25
+  ]
+]
+```
+
+### Computed Weights with JSONLogic
+
+Weight values can be JSONLogic expressions, enabling progressive rollouts and dynamic traffic splitting without a dedicated operator.
+This allows you to use arbitrary JSONLogic expressions to compute weights at runtime.
+This is especially useful for time-based weight calculations.
+
+#### Time-Based Rollout Example
+
+Use flagd's built-in `$flagd.timestamp` variable to create time-based progressive rollouts.
+The timestamp is in Unix epoch seconds.
+
+```jsonc
+{
+  "fractional": [
+    ["on",  { "-": [{ "var": "$flagd.timestamp" }, 1743360000] }],
+    ["off", { "-": [1743964800, { "var": "$flagd.timestamp" }] }]
+  ]
+}
+```
+
+As time advances, the weight of `"on"` grows and `"off"` shrinks, producing a deterministic progressive rollout.
+This example:
+
+- Starts on Mar 30, 2025 (timestamp `1743360000`)
+- Completes on Apr 6, 2025 (timestamp `1743964800`, 7 days later)
+
+#### Environment-Based Rollout Example
+
+Roll out differently based on environment:
+
+```json
+"fractional": [
+  { "var": "email" },
+  ["new-feature", {
+    "if": [
+      { "==": [{ "var": "environment" }, "production"] },
+      10,
+      {
+        "if": [
+          { "==": [{ "var": "environment" }, "staging"] },
+          50,
+          100
+        ]
+      }
+    ]
+  }],
+  ["control", {
+    "if": [
+      { "==": [{ "var": "environment" }, "production"] },
+      90,
+      {
+        "if": [
+          { "==": [{ "var": "environment" }, "staging"] },
+          50,
+          0
+        ]
+      }
+    ]
+  }]
+]
+```
+
+#### High Precision Example
+
+Use large weight values for sub-percent granularity in high-traffic environments:
+
+```json
+"fractional": [
+  { "var": "user_id" },
+  ["canary", 1],
+  ["control", 1000000]
+]
+```
+
+This splits approximately 1/1,000,000 of traffic to `canary` and the remaining to `control`.
+
 ### Migrating from legacy "fractionalEvaluation"
 
 If you are using a legacy fractional evaluation (`fractionalEvaluation`), it's recommended you migrate to `fractional`.

docs/reference/custom-operations/fractional-operation.md

@@ -321,7 +321,9 @@ FetchAllFlagsRequest is the request to fetch all flags. Clients send this reques
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | provider_id | [string](#string) |  | Optional: A unique identifier for clients initiating the request. The server implementations may utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter flag configurations that it can expose to this request. This field is intended to be optional. However server implementations may enforce it. ex:- provider_id: flagd-weatherapp-sidecar |
-| selector | [string](#string) |  | Optional: A selector for the flag configuration request. The server implementation may utilize this to select flag configurations from a collection, select the source of the flag or combine this to any desired underlying filtering mechanism. ex:- selector: 'source=database,app=weatherapp' |
+| selector | [string](#string) |  | **Deprecated.** Optional: A selector for the flag configuration request. The server implementation may utilize this to select flag configurations from a collection, select the source of the flag or combine this to any desired underlying filtering mechanism. ex:- selector: 'source=database,app=weatherapp'
+
+Deprecated: Use the 'Flagd-Selector' header instead. Remember to reserve field number 2 if this is removed; |
 
 
 
@@ -379,7 +381,9 @@ Implementations of Flagd providers and Flagd itself send this request, acting as
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | provider_id | [string](#string) |  | Optional: A unique identifier for flagd(grpc client) initiating the request. The server implementations may utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter flag configurations that it can expose to this request. This field is intended to be optional. However server implementations may enforce it. ex:- provider_id: flagd-weatherapp-sidecar |
-| selector | [string](#string) |  | Optional: A selector for the flag configuration request. The server implementation may utilize this to select flag configurations from a collection, select the source of the flag or combine this to any desired underlying filtering mechanism. ex:- selector: 'source=database,app=weatherapp' |
+| selector | [string](#string) |  | **Deprecated.** Optional: A selector for the flag configuration request. The server implementation may utilize this to select flag configurations from a collection, select the source of the flag or combine this to any desired underlying filtering mechanism. ex:- selector: 'source=database,app=weatherapp'
+
+Deprecated: Use the 'Flagd-Selector' header instead. Remember to reserve field number 2 if this is removed; |
 
 
 

docs/reference/specifications/protos.md

@@ -35,7 +35,7 @@
           "type": "string"
         },
         {
-          "description": "When returned from rules, strings are used to as keys to retrieve the associated value from the \"variants\" object. Be sure that the returned string is present as a key in the variants!.",
+          "description": "When returned from rules, the behavior of arrays is not defined.",
           "type": "array"
         }
       ]
@@ -461,18 +461,26 @@
       "maxItems": 2,
       "items": [
         {
-          "description": "If this bucket is randomly selected, this string is used to as a key to retrieve the associated value from the \"variants\" object.",
-          "type": "string"
+          "description": "If this bucket is randomly selected, this JSONLogic will be evaluated, and the result will be used as the variant key to return from the variants map.",
+          "$ref": "#/definitions/args"
         },
         {
-          "description": "Weighted distribution for this variant key.",
-          "type": "number"
+          "description": "Weighted distribution for this variant key. Must be a non-negative integer. Can be a JSONLogic expression that evaluates to a number (e.g. for time-based progressive rollouts); computed negative weights are clamped to 0 at evaluation time. The total weight sum across all variants must not exceed 2,147,483,647.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "$ref": "#/definitions/anyRule"
+            }
+          ]
         }
       ]
     },
     "fractionalOp": {
       "type": "array",
-      "minItems": 3,
+      "minItems": 1,
       "$comment": "there seems to be a bug here, where ajv gives a warning (not an error) because maxItems doesn't equal the number of entries in items, though this is valid in this case",
       "items": [
         {
@@ -492,7 +500,7 @@
     },
     "fractionalShorthandOp": {
       "type": "array",
-      "minItems": 2,
+      "minItems": 1,
       "items": {
         "$ref": "#/definitions/fractionalWeightArg"
       }

docs/schema/v0/targeting.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@monaco-editor/react": "^4.7.0-rc.0",
-    "@openfeature/flagd-core": "^2.0.0",
+    "@openfeature/flagd-core": "^3.0.0",
     "js-yaml": "^4.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",