feat(flags): add rules engine boundary

Author: btthomas

packages/core/src/flags/configuration/__tests__/__utils__/rulesTestUtils.ts

@@ -0,0 +1,82 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://github.com/DataDog).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+import { OperatorType } from '@datadog/flagging-core';
+import type { UniversalFlagConfigurationV1 } from '@datadog/flagging-core';
+
+import type {
+    RulesEngine,
+    RulesEvaluationDetails,
+    RulesEvaluationRequest,
+    RulesValueType
+} from '../../rules';
+
+export const buildRulesConfiguration = (): UniversalFlagConfigurationV1 => ({
+    createdAt: '2026-07-23T12:00:00.000Z',
+    format: 'SERVER',
+    environment: { name: 'test' },
+    flags: {
+        'dynamic-flag': {
+            key: 'dynamic-flag',
+            enabled: true,
+            variationType: 'BOOLEAN',
+            variations: {
+                enabled: { key: 'enabled', value: true },
+                disabled: { key: 'disabled', value: false }
+            },
+            allocations: [
+                {
+                    key: 'allocation-1',
+                    rules: [
+                        {
+                            conditions: [
+                                {
+                                    operator: OperatorType.ONE_OF,
+                                    attribute: 'country',
+                                    value: ['US']
+                                }
+                            ]
+                        }
+                    ],
+                    splits: [
+                        {
+                            variationKey: 'enabled',
+                            serialId: 7,
+                            extraLogging: { experiment: 'checkout' },
+                            shards: [
+                                {
+                                    salt: 'test-salt',
+                                    ranges: [{ start: 0, end: 100 }],
+                                    totalShards: 100
+                                }
+                            ]
+                        }
+                    ],
+                    doLog: false
+                }
+            ]
+        }
+    }
+});
+
+type FakeRulesEvaluation = RulesEvaluationDetails<unknown>;
+
+export interface FakeRulesEngine extends RulesEngine {
+    evaluate: jest.Mock<
+        FakeRulesEvaluation,
+        [RulesEvaluationRequest<RulesValueType>]
+    >;
+}
+
+// TODO(FFL-2837): Remove this fake after the upstream rules wire and engine
+// contract are published and the state-matrix tests can use canonical vectors.
+export const createFakeRulesEngine = (
+    result: FakeRulesEvaluation
+): FakeRulesEngine => {
+    return {
+        evaluate: jest.fn(() => result)
+    } as FakeRulesEngine;
+};

packages/core/src/flags/configuration/__tests__/rules.test.ts

@@ -0,0 +1,175 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://github.com/DataDog).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+import {
+    flaggingCoreRulesEngine,
+    getNoopRulesLogger,
+    prepareRulesConfiguration,
+    toRulesEvaluationContext
+} from '../rules';
+
+import {
+    buildRulesConfiguration,
+    createFakeRulesEngine
+} from './__utils__/rulesTestUtils';
+
+describe('rules configuration', () => {
+    it('converts an SDK context to a flat rules context and reserves identifiers', () => {
+        expect(
+            toRulesEvaluationContext({
+                targetingKey: 'user-1',
+                attributes: {
+                    country: 'US',
+                    id: 'customer-id',
+                    targetingKey: 'attribute-key',
+                    enabled: true
+                }
+            })
+        ).toEqual({
+            targetingKey: 'user-1',
+            country: 'US',
+            enabled: true
+        });
+    });
+
+    it('clones and freezes a valid rules configuration', () => {
+        const source = buildRulesConfiguration();
+        const prepared = prepareRulesConfiguration(source);
+
+        expect(prepared.status).toBe('ready');
+        if (prepared.status !== 'ready') {
+            throw new Error(prepared.errorMessage);
+        }
+
+        source.flags['dynamic-flag'].enabled = false;
+
+        expect(prepared.configuration.flags['dynamic-flag'].enabled).toBe(true);
+        expect(Object.isFrozen(prepared.configuration)).toBe(true);
+        expect(
+            Object.isFrozen(
+                prepared.configuration.flags['dynamic-flag'].allocations[0]
+            )
+        ).toBe(true);
+    });
+
+    it('rejects an unsupported operator', () => {
+        const source = buildRulesConfiguration();
+        const condition =
+            source.flags['dynamic-flag'].allocations[0].rules?.[0]
+                .conditions[0];
+
+        if (!condition) {
+            throw new Error('The fixture has no condition.');
+        }
+        (condition as { operator: string }).operator = 'ONE_OF_SHA256';
+
+        expect(prepareRulesConfiguration(source)).toEqual({
+            status: 'error',
+            errorMessage:
+                'The rules configuration uses the unsupported operator "ONE_OF_SHA256".'
+        });
+    });
+
+    it('rejects an invalid regular expression', () => {
+        const source = buildRulesConfiguration();
+        const conditions =
+            source.flags['dynamic-flag'].allocations[0].rules?.[0].conditions;
+        if (!conditions) {
+            throw new Error('The fixture has no conditions.');
+        }
+        conditions[0] = {
+            operator: 'MATCHES',
+            attribute: 'country',
+            value: '['
+        } as typeof conditions[number];
+
+        expect(prepareRulesConfiguration(source)).toEqual({
+            status: 'error',
+            errorMessage: 'A regular expression condition is not valid.'
+        });
+    });
+
+    it('rejects a split that points to an absent variation', () => {
+        const source = buildRulesConfiguration();
+        source.flags['dynamic-flag'].allocations[0].splits[0].variationKey =
+            'absent';
+
+        expect(prepareRulesConfiguration(source)).toEqual({
+            status: 'error',
+            errorMessage: 'A split has an invalid variation key.'
+        });
+    });
+
+    it('normalizes a real flagging-core evaluation', () => {
+        const configuration = buildRulesConfiguration();
+
+        const result = flaggingCoreRulesEngine.evaluate({
+            configuration,
+            type: 'boolean',
+            flagKey: 'dynamic-flag',
+            defaultValue: false,
+            context: {
+                targetingKey: 'user-1',
+                country: 'US'
+            },
+            logger: getNoopRulesLogger()
+        });
+
+        expect(result).toMatchObject({
+            value: true,
+            variant: 'enabled',
+            reason: 'TARGETING_MATCH',
+            metadata: {
+                allocationKey: 'allocation-1',
+                variationType: 'boolean',
+                doLog: false,
+                extraLogging: { experiment: 'checkout' },
+                splitSerialId: 7
+            }
+        });
+        expect(result.metadata.evaluationTimestampMs).toEqual(
+            expect.any(Number)
+        );
+    });
+
+    it('checks own properties before it calls flagging-core', () => {
+        const result = flaggingCoreRulesEngine.evaluate({
+            configuration: buildRulesConfiguration(),
+            type: 'boolean',
+            flagKey: 'toString',
+            defaultValue: false,
+            context: { targetingKey: 'user-1' },
+            logger: getNoopRulesLogger()
+        });
+
+        expect(result).toEqual({
+            value: false,
+            reason: 'ERROR',
+            errorCode: 'FLAG_NOT_FOUND',
+            metadata: {}
+        });
+    });
+
+    it('provides a deterministic fake engine for client tests', () => {
+        const fake = createFakeRulesEngine({
+            value: true,
+            variant: 'fake',
+            reason: 'TARGETING_MATCH',
+            metadata: {}
+        });
+
+        expect(
+            fake.evaluate({
+                configuration: buildRulesConfiguration(),
+                type: 'boolean',
+                flagKey: 'dynamic-flag',
+                defaultValue: false,
+                context: { targetingKey: 'user-1' },
+                logger: getNoopRulesLogger()
+            })
+        ).toMatchObject({ value: true, variant: 'fake' });
+    });
+});

packages/core/src/flags/configuration/__tests__/wire.test.ts

@@ -7,6 +7,8 @@
 import type { ParsedFlagsConfiguration } from '../types';
 import { configurationFromString, configurationToString } from '../wire';
 
+import { buildRulesConfiguration } from './__utils__/rulesTestUtils';
+
 const buildResponse = () => ({
     data: {
         id: '2',
@@ -125,3 +127,60 @@ describe('configurationToString round-trip', () => {
         );
     });
 });
+
+describe('rules configuration wire compatibility', () => {
+    it('parses and serializes a rules configuration', () => {
+        const rulesBased = {
+            response: buildRulesConfiguration(),
+            fetchedAt: 123,
+            etag: 'rules-etag'
+        };
+        const wire = JSON.stringify({
+            version: 1,
+            rulesBased: {
+                ...rulesBased,
+                response: JSON.stringify(rulesBased.response)
+            }
+        });
+
+        const parsed = configurationFromString(wire) as {
+            rulesBased?: typeof rulesBased;
+        };
+
+        expect(parsed.rulesBased).toEqual(rulesBased);
+        expect(
+            configurationFromString(
+                configurationToString(
+                    (parsed as unknown) as ParsedFlagsConfiguration
+                )
+            )
+        ).toEqual(parsed);
+    });
+
+    it('keeps both branches in a mixed configuration', () => {
+        const mixedWire = buildWire({
+            rulesBased: {
+                response: JSON.stringify(buildRulesConfiguration())
+            }
+        });
+
+        const parsed = configurationFromString(mixedWire) as {
+            precomputed?: unknown;
+            rulesBased?: unknown;
+        };
+
+        expect(parsed.precomputed).toBeDefined();
+        expect(parsed.rulesBased).toBeDefined();
+    });
+
+    it('returns an empty configuration for malformed rules JSON', () => {
+        expect(
+            configurationFromString(
+                JSON.stringify({
+                    version: 1,
+                    rulesBased: { response: '{' }
+                })
+            )
+        ).toEqual({});
+    });
+});