feat(js): add sticky assignment support through remote resolver fallback (#48)

Co-authored-by: Claude <[email protected]>

Author: nicklasl

.github/workflows/ci.yml

@@ -34,19 +34,21 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          target: all
           push: false
           cache-from: type=registry,ref=ghcr.io/${{ github.repository }}/cache:main
+          secrets: |
+            "js_e2e_test_env=${{ secrets.JS_E2E_TEST_ENV }}"
 
       - name: Build and test everything (Push - updates cache)
         if: github.event_name == 'push'
         uses: docker/build-push-action@v6
         with:
           context: .
-          target: all
           push: false
           cache-from: type=registry,ref=ghcr.io/${{ github.repository }}/cache:main
           cache-to: type=registry,ref=ghcr.io/${{ github.repository }}/cache:main,mode=max
+          secrets: |
+            "js_e2e_test_env=${{ secrets.JS_E2E_TEST_ENV }}"
 
       - name: Extract artifacts
         run: |

Dockerfile

@@ -394,11 +394,22 @@ COPY --from=wasm-rust-guest.artifact /confidence_resolver.wasm ../../../wasm/con
 # Test OpenFeature Provider
 # ==============================================================================
 FROM openfeature-provider-js-base AS openfeature-provider-js.test
+
 # Copy confidence-resolver protos (needed by some tests for proto parsing)
 COPY confidence-resolver/protos ../../../confidence-resolver/protos
 COPY wasm/resolver_state.pb ../../../wasm/resolver_state.pb
+
 RUN make test
 
+# ==============================================================================
+# E2E Test OpenFeature Provider (requires credentials)
+# ==============================================================================
+FROM openfeature-provider-js.test AS openfeature-provider-js.test_e2e
+
+# Run e2e tests with secrets mounted as .env.test file
+RUN --mount=type=secret,id=js_e2e_test_env,target=.env.test \
+    make test-e2e
+
 # ==============================================================================
 # Build OpenFeature Provider
 # ==============================================================================
@@ -466,6 +477,7 @@ COPY --from=wasm-rust-guest.artifact /confidence_resolver.wasm /artifacts/wasm/
 COPY --from=confidence-resolver.test /workspace/Cargo.toml /markers/test-resolver
 COPY --from=wasm-msg.test /workspace/Cargo.toml /markers/test-wasm-msg
 COPY --from=openfeature-provider-js.test /app/package.json /markers/test-openfeature-js
+COPY --from=openfeature-provider-js.test_e2e /app/package.json /markers/test-openfeature-js-e2e
 COPY --from=openfeature-provider-java.test /app/pom.xml /markers/test-openfeature-java
 
 # Force integration test stages to run (host examples)

README.md

@@ -28,6 +28,12 @@ The Confidence Flag Resolver implemented in Rust, plus example hosts and a Cloud
 docker build .                    # Build, test, lint everything
 make                              # Same, using Makefile
 
+# E2E tests require Confidence credentials passed as Docker secret
+# Create openfeature-provider/js/.env.test with your credentials, then:
+docker build \
+  --secret id=js_e2e_test_env,src=openfeature-provider/js/.env.test \
+  .
+
 # With local tools (fast iteration)
 make test                         # Run tests
 make lint                         # Run linting

openfeature-provider/js/Makefile

@@ -44,6 +44,9 @@ build: $(BUILD_STAMP)
 test: $(WASM_ARTIFACT) $(INSTALL_STAMP) $(GEN_TS)
 	yarn test --run --exclude='**/*.e2e.test.ts'
 
+test-e2e: $(WASM_ARTIFACT) $(INSTALL_STAMP) $(GEN_TS)
+	yarn test --run e2e.test
+
 clean:
 	rm -rf node_modules dist src/proto $(INSTALL_STAMP) $(BUILD_STAMP)
 

openfeature-provider/js/README.md

@@ -78,6 +78,44 @@ The provider periodically:
 
 ---
 
+## Sticky Assignments
+
+Confidence supports "sticky" flag assignments to ensure users receive consistent variant assignments even when their context changes or flag configurations are updated. This SDK falls back to a cloud resolve in these cases.
+
+> **ℹ️ Latency Considerations**
+>
+> When a sticky assignment is needed, the provider makes a **network call to Confidence's cloud resolvers**. This introduces additional latency (typically 50-200ms depending on your location) compared to local WASM evaluation.
+>
+> **Coming soon**: We're developing support for custom materialization storage (Redis, database, etc.) that will eliminate this network call and keep evaluation latency consistently low.
+
+### How it works
+
+When a flag is evaluated for a user, Confidence creates a "materialization" - a snapshot of which variant that user was assigned. On subsequent evaluations, the same variant is returned even if:
+- The user's context attributes change (e.g., different country, device type)
+- The flag's targeting rules are modified
+- New assignments are paused
+
+### Implementation
+
+The provider uses a **remote resolver fallback** for sticky assignments:
+- First, the local WASM resolver attempts to resolve the flag
+- If sticky assignment data is needed, the provider makes a network call to Confidence's cloud resolvers
+- Materializations are stored on Confidence servers with a **90-day TTL** (automatically renewed on access)
+- No local storage or database setup required
+
+### Benefits
+
+- **Zero configuration**: Works out of the box with no additional setup
+- **Managed storage**: Confidence handles all storage, TTL, and consistency
+- **Automatic renewal**: TTL is refreshed on each access
+- **Global availability**: Materializations are available across all your services
+
+### Coming Soon: Custom Materialization Storage
+
+We're working on support for connecting your own materialization storage repository (Redis, database, file system, etc.) to eliminate network calls for sticky assignments and have full control over storage. This feature is currently in development.
+
+---
+
 ## Logging (optional)
 
 Logging uses the `debug` library if present; otherwise, all log calls are no-ops.

openfeature-provider/js/proto/api.proto

@@ -90,3 +90,68 @@ message SetResolverStateRequest {
   bytes state = 1;
   string account_id = 2;
 }
+
+// Request for resolving flags with sticky (materialized) assignments
+message ResolveWithStickyRequest {
+  // The standard resolve request
+  ResolveFlagsRequest resolve_request = 1;
+
+  // Context about the materialization required for the resolve
+  // Map of targeting key (unit) to their materialization data
+  map<string, MaterializationMap> materializations_per_unit = 2;
+
+  // If a materialization info is missing, return to the caller immediately
+  bool fail_fast_on_sticky = 3;
+}
+
+// Map of materialization IDs to their info for a specific unit
+message MaterializationMap {
+  // Map of materialization name to info
+  map<string, MaterializationInfo> info_map = 1;
+}
+
+// Information about a materialization for a specific unit
+message MaterializationInfo {
+  // Whether the unit is in this materialization/rollout
+  bool unit_in_info = 1;
+
+  // Map of rule name to variant name for this unit
+  map<string, string> rule_to_variant = 2;
+}
+
+// Response from resolving with sticky assignments
+message ResolveWithStickyResponse {
+  oneof resolve_result {
+    Success success = 1;
+    MissingMaterializations missing_materializations = 2;
+  }
+
+  // Successful resolution with materialization updates
+  message Success {
+    // The resolved flags response
+    ResolveFlagsResponse response = 1;
+
+    // New assignments that should be stored
+    repeated MaterializationUpdate updates = 2;
+  }
+
+  // Information about missing materializations
+  message MissingMaterializations {
+    repeated MissingMaterializationItem items = 1;
+  }
+
+  // A missing materialization item
+  message MissingMaterializationItem {
+    string unit = 1;
+    string rule = 2;
+    string read_materialization = 3;
+  }
+
+  // A materialization update to be stored
+  message MaterializationUpdate {
+    string unit = 1;
+    string write_materialization = 2;
+    string rule = 3;
+    string variant = 4;
+  }
+}

openfeature-provider/js/src/ConfidenceServerProviderLocal.e2e.test.ts

@@ -5,17 +5,17 @@ import { readFileSync } from 'node:fs';
 import { WasmResolver } from './WasmResolver';
 
 const {
-  CONFIDENCE_API_CLIENT_ID,
-  CONFIDENCE_API_CLIENT_SECRET, 
-} = requireEnv('CONFIDENCE_API_CLIENT_ID', 'CONFIDENCE_API_CLIENT_SECRET');
+  JS_E2E_CONFIDENCE_API_CLIENT_ID,
+  JS_E2E_CONFIDENCE_API_CLIENT_SECRET,
+} = requireEnv('JS_E2E_CONFIDENCE_API_CLIENT_ID', 'JS_E2E_CONFIDENCE_API_CLIENT_SECRET');
 
 const moduleBytes = readFileSync(__dirname + '/../../../wasm/confidence_resolver.wasm');
 const module = new WebAssembly.Module(moduleBytes);
 const resolver = await WasmResolver.load(module);
 const confidenceProvider = new ConfidenceServerProviderLocal(resolver, {
   flagClientSecret: 'RxDVTrXvc6op1XxiQ4OaR31dKbJ39aYV',
-  apiClientId: CONFIDENCE_API_CLIENT_ID,
-  apiClientSecret: CONFIDENCE_API_CLIENT_SECRET
+  apiClientId: JS_E2E_CONFIDENCE_API_CLIENT_ID,
+  apiClientSecret: JS_E2E_CONFIDENCE_API_CLIENT_SECRET
 });
 
 describe('ConfidenceServerProvider E2E tests', () => {
@@ -84,6 +84,18 @@ describe('ConfidenceServerProvider E2E tests', () => {
 
     expect(await client.getNumberDetails('web-sdk-e2e-flag.obj.double', 1)).toEqual(expectedObject);
   });
+
+  it('should resolve a flag with a sticky resolve', async () => {
+    const client = OpenFeature.getClient();
+    const result = await client.getNumberDetails('web-sdk-e2e-flag.double', -1, { targetingKey: 'test-a', sticky: true });
+    
+    // The flag has a running experiment with a sticky assignment. The intake is paused but we should still get the sticky assignment.
+    // If this test breaks it could mean that the experiment was removed or that the bigtable materialization was cleaned out.
+    expect(result.value).toBe(99.99);
+    expect(result.variant).toBe('flags/web-sdk-e2e-flag/variants/sticky');
+    expect(result.reason).toBe('MATCH');
+    
+  });
 });
 
 function requireEnv<const N extends string[]>(...names:N): Record<N[number],string> {

openfeature-provider/js/src/ConfidenceServerProviderLocal.test.ts

@@ -3,11 +3,10 @@ import { LocalResolver } from './LocalResolver';
 import { ConfidenceServerProviderLocal, DEFAULT_FLUSH_INTERVAL, DEFAULT_STATE_INTERVAL } from './ConfidenceServerProviderLocal';
 import { abortableSleep, TimeUnit, timeoutSignal } from './util';
 import { advanceTimersUntil, NetworkMock } from './test-helpers';
-import { aD } from 'vitest/dist/chunks/reporters.d.BFLkQcL6.js';
 
 
 const mockedWasmResolver:MockedObject<LocalResolver> = {
-  resolveFlags: vi.fn(),
+  resolveWithSticky: vi.fn(),
   setResolverState: vi.fn(),
   flushLogs: vi.fn().mockReturnValue(new Uint8Array(100))
 }
@@ -430,4 +429,130 @@ describe('network error modes', () => {
     );
     expect(net.resolver.flagLogs.calls).toBeGreaterThan(1);
   });
+});
+
+describe('remote resolver fallback for sticky assignments', () => {
+  const RESOLVE_REASON_MATCH = 1;
+
+  it('resolves locally when WASM has all materialization data', async () => {
+    await advanceTimersUntil(
+      expect(provider.initialize()).resolves.toBeUndefined()
+    );
+
+    // WASM resolver succeeds with local data
+    mockedWasmResolver.resolveWithSticky.mockReturnValue({
+      success: {
+        response: {
+          resolvedFlags: [{
+            flag: 'test-flag',
+            variant: 'variant-a',
+            value: { enabled: true },
+            reason: RESOLVE_REASON_MATCH
+          }],
+          resolveToken: new Uint8Array(),
+          resolveId: 'resolve-123'
+        },
+        updates: []
+      }
+    });
+
+    const result = await provider.resolveBooleanEvaluation('test-flag.enabled', false, {
+      targetingKey: 'user-123'
+    });
+
+    expect(result.value).toBe(true);
+    expect(result.variant).toBe('variant-a');
+
+    // Should use failFastOnSticky: true (fallback strategy)
+    expect(mockedWasmResolver.resolveWithSticky).toHaveBeenCalledWith({
+      resolveRequest: expect.objectContaining({
+        flags: ['flags/test-flag'],
+        clientSecret: 'flagClientSecret'
+      }),
+      materializationsPerUnit: {},
+      failFastOnSticky: true
+    });
+
+    // No remote call needed
+    expect(net.resolver.flagsResolve.calls).toBe(0);
+  });
+
+  it('falls back to remote resolver when WASM reports missing materializations', async () => {
+    await advanceTimersUntil(
+      expect(provider.initialize()).resolves.toBeUndefined()
+    );
+
+    // WASM resolver reports missing materialization
+    mockedWasmResolver.resolveWithSticky.mockReturnValue({
+      missingMaterializations: {
+        items: [
+          { unit: 'user-456', rule: 'rule-1', readMaterialization: 'mat-v1' }
+        ]
+      }
+    });
+
+    // Configure remote resolver response
+    net.resolver.flagsResolve.handler = () => {
+      return new Response(JSON.stringify({
+        resolvedFlags: [{
+          flag: 'flags/my-flag',
+          variant: 'flags/my-flag/variants/control',
+          value: { color: 'blue', size: 10 },
+          reason: 'RESOLVE_REASON_MATCH'
+        }],
+        resolveToken: '',
+        resolveId: 'remote-resolve-456'
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    };
+
+    const result = await provider.resolveObjectEvaluation('my-flag', { color: 'red' }, {
+      targetingKey: 'user-456',
+      country: 'SE'
+    });
+
+    expect(result.value).toEqual({ color: 'blue', size: 10 });
+    expect(result.variant).toBe('flags/my-flag/variants/control');
+
+    // Remote resolver should have been called
+    expect(net.resolver.flagsResolve.calls).toBe(1);
+
+    // Verify auth header was added
+    const lastRequest = net.resolver.flagsResolve.requests[0];
+    expect(lastRequest.method).toBe('POST');
+  });
+
+  it('retries remote resolve on transient errors', async () => {
+    await advanceTimersUntil(
+      expect(provider.initialize()).resolves.toBeUndefined()
+    );
+
+    mockedWasmResolver.resolveWithSticky.mockReturnValue({
+      missingMaterializations: {
+        items: [{ unit: 'user-1', rule: 'rule-1', readMaterialization: 'mat-1' }]
+      }
+    });
+
+    // First two calls fail, third succeeds
+    net.resolver.flagsResolve.status = 503;
+    setTimeout(() => {
+      net.resolver.flagsResolve.status = 200;
+      net.resolver.flagsResolve.handler = () => new Response(JSON.stringify({
+        resolvedFlags: [{ flag: 'test-flag', variant: 'v1', value: { ok: true }, reason: 'RESOLVE_REASON_MATCH' }],
+        resolveToken: '',
+        resolveId: 'resolved'
+      }), { status: 200 });
+    }, 300);
+
+    const result = await advanceTimersUntil(
+      provider.resolveBooleanEvaluation('test-flag.ok', false, { targetingKey: 'user-1' })
+    );
+
+    expect(result.value).toBe(true);
+    // Should have retried multiple times
+    expect(net.resolver.flagsResolve.calls).toBeGreaterThan(1);
+    expect(net.resolver.flagsResolve.calls).toBeLessThanOrEqual(3);
+  });
 });