feat: add retry logic to FDv2 polling initializer (#1230)

## Summary

- The FDv2 polling initializer now retries up to 3 times on recoverable
errors (5xx, 400, 408, 429, network errors) with a 1-second delay
between attempts, matching FDv1 behavior
- Uses a `SHUTDOWN` symbol for clean race discrimination between poll
results and shutdown signals
- Removes the `oneShot` parameter from `poll()` / `processEvents()`
since retry logic now lives at the initializer level

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it changes FDv2 initialization behavior by adding
retry/delay loops and altering how polling errors are classified, which
can affect startup latency and failure modes.
> 
> **Overview**
> Adds retry behavior to the FDv2 polling initializer: it now retries up
to 3 times with a 1s delay on recoverable `interrupted` results,
converts an exhausted retry sequence into `terminal_error`, and supports
shutdown during both an in-flight poll and the retry sleep via a
sentinel `SHUTDOWN` symbol.
> 
> Simplifies `fdv2` polling by removing the `oneShot`/initializer-mode
branching from `PollingBase`/`processEvents` and updating all call
sites/tests accordingly (including `SourceFactoryProvider` ping handling
and browser test mocks to return FDv2-style poll responses).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
1dd4150. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/sdk/browser/__tests__/BrowserClient.mocks.ts

@@ -15,7 +15,7 @@ function mockResponse(value: string, statusCode: number) {
     // @ts-ignore
     headers: {
       // @ts-ignore
-      get: jest.fn(),
+      get: jest.fn(() => null),
       // @ts-ignore
       keys: jest.fn(),
       // @ts-ignore
@@ -61,6 +61,34 @@ export function makeRequests(): Requests {
           200,
         )();
       }
+      if (url.includes('/sdk/poll/eval')) {
+        return mockFetch(
+          JSON.stringify({
+            events: [
+              {
+                event: 'server-intent',
+                data: {
+                  payloads: [{ id: 'mock', target: 1, intentCode: 'xfer-full', reason: 'mock' }],
+                },
+              },
+              {
+                event: 'put-object',
+                data: {
+                  kind: 'flag-eval',
+                  key: 'flagA',
+                  version: 1,
+                  object: { value: true, trackEvents: false },
+                },
+              },
+              {
+                event: 'payload-transferred',
+                data: { state: 'mock-state', version: 1, id: 'mock' },
+              },
+            ],
+          }),
+          200,
+        )();
+      }
       return mockFetch('{ "flagA": true }', 200)();
     }),
     // @ts-ignore

packages/shared/sdk-client/__tests__/datasource/SourceFactoryProvider.test.ts

@@ -339,7 +339,7 @@ it('ping handler uses the factory selector getter, not a stale reference', () =>
   pingHandler.handlePing();
 
   // The ping poll should use the fresh selector, not 'selector-v1'
-  expect(mockFdv2Poll).toHaveBeenCalledWith(expect.anything(), 'selector-v2', false, ctx.logger);
+  expect(mockFdv2Poll).toHaveBeenCalledWith(expect.anything(), 'selector-v2', ctx.logger);
 });
 
 it('ping handler uses per-entry endpoint-overridden requestor', () => {
@@ -361,5 +361,5 @@ it('ping handler uses per-entry endpoint-overridden requestor', () => {
 
   // The ping poll should use the overridden requestor, not ctx.requestor
   const overriddenRequestor = mockMakeFDv2Requestor.mock.results[0].value;
-  expect(mockFdv2Poll).toHaveBeenCalledWith(overriddenRequestor, undefined, false, ctx.logger);
+  expect(mockFdv2Poll).toHaveBeenCalledWith(overriddenRequestor, undefined, ctx.logger);
 });

packages/shared/sdk-client/__tests__/datasource/fdv2/PollingBase.test.ts

@@ -25,7 +25,7 @@ describe('given a successful FDv2 response', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('changeSet');
     if (result.type === 'changeSet') {
@@ -48,7 +48,7 @@ describe('given a successful FDv2 response', () => {
       body,
     });
 
-    await poll(requestor, 'my-basis', false, logger);
+    await poll(requestor, 'my-basis', logger);
 
     expect(requestor.poll).toHaveBeenCalledWith('my-basis');
   });
@@ -62,7 +62,7 @@ describe('given a 304 Not Modified response', () => {
       body: null,
     });
 
-    const result = await poll(requestor, 'some-basis', false, logger);
+    const result = await poll(requestor, 'some-basis', logger);
 
     expect(result.type).toBe('changeSet');
     if (result.type === 'changeSet') {
@@ -76,7 +76,7 @@ describe('given a network error', () => {
   it('returns interrupted for synchronizer mode', async () => {
     const requestor = makeErrorRequestor(new Error('connection reset'));
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -85,18 +85,6 @@ describe('given a network error', () => {
       expect(result.errorInfo?.message).toBe('connection reset');
     }
   });
-
-  it('returns terminal error for initializer mode', async () => {
-    const requestor = makeErrorRequestor(new Error('connection reset'));
-
-    const result = await poll(requestor, undefined, true, logger);
-
-    expect(result.type).toBe('status');
-    if (result.type === 'status') {
-      expect(result.state).toBe('terminal_error');
-      expect(result.errorInfo?.kind).toBe(DataSourceErrorKind.NetworkError);
-    }
-  });
 });
 
 describe('given an unrecoverable HTTP error', () => {
@@ -107,7 +95,7 @@ describe('given an unrecoverable HTTP error', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -123,7 +111,7 @@ describe('given an unrecoverable HTTP error', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     if (result.type === 'status') {
       expect(result.state).toBe('terminal_error');
@@ -139,7 +127,7 @@ describe('given a recoverable HTTP error', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -155,26 +143,12 @@ describe('given a recoverable HTTP error', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     if (result.type === 'status') {
       expect(result.state).toBe('interrupted');
     }
   });
-
-  it('returns terminal error for initializer mode on 500', async () => {
-    const requestor = makeRequestor({
-      status: 500,
-      headers: makeHeaders(),
-      body: null,
-    });
-
-    const result = await poll(requestor, undefined, true, logger);
-
-    if (result.type === 'status') {
-      expect(result.state).toBe('terminal_error');
-    }
-  });
 });
 
 describe('given x-ld-fd-fallback header', () => {
@@ -186,7 +160,7 @@ describe('given x-ld-fd-fallback header', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.fdv1Fallback).toBe(true);
   });
@@ -199,7 +173,7 @@ describe('given x-ld-fd-fallback header', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.fdv1Fallback).toBe(false);
   });
@@ -211,7 +185,7 @@ describe('given x-ld-fd-fallback header', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.fdv1Fallback).toBe(true);
   });
@@ -226,7 +200,7 @@ describe('given x-ld-envid header', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     if (result.type === 'changeSet') {
       expect(result.environmentId).toBe('env-abc-123');
@@ -240,7 +214,7 @@ describe('given x-ld-envid header', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     if (result.type === 'changeSet') {
       expect(result.environmentId).toBe('env-abc-123');
@@ -256,28 +230,13 @@ describe('given malformed JSON response', () => {
       body: '{invalid json',
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     if (result.type === 'status') {
       expect(result.state).toBe('interrupted');
       expect(result.errorInfo?.kind).toBe(DataSourceErrorKind.InvalidData);
     }
   });
-
-  it('returns terminal error for initializer mode', async () => {
-    const requestor = makeRequestor({
-      status: 200,
-      headers: makeHeaders(),
-      body: '{invalid json',
-    });
-
-    const result = await poll(requestor, undefined, true, logger);
-
-    if (result.type === 'status') {
-      expect(result.state).toBe('terminal_error');
-      expect(result.errorInfo?.kind).toBe(DataSourceErrorKind.InvalidData);
-    }
-  });
 });
 
 describe('given valid JSON without an events array', () => {
@@ -288,7 +247,7 @@ describe('given valid JSON without an events array', () => {
       body: '{"notEvents": true}',
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -297,22 +256,6 @@ describe('given valid JSON without an events array', () => {
       expect(result.errorInfo?.message).toContain('missing or invalid events array');
     }
   });
-
-  it('returns terminal error for initializer mode', async () => {
-    const requestor = makeRequestor({
-      status: 200,
-      headers: makeHeaders(),
-      body: '{"events": "not-an-array"}',
-    });
-
-    const result = await poll(requestor, undefined, true, logger);
-
-    expect(result.type).toBe('status');
-    if (result.type === 'status') {
-      expect(result.state).toBe('terminal_error');
-      expect(result.errorInfo?.kind).toBe(DataSourceErrorKind.InvalidData);
-    }
-  });
 });
 
 describe('given an empty response body', () => {
@@ -323,7 +266,7 @@ describe('given an empty response body', () => {
       body: null,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -352,7 +295,7 @@ describe('given a goodbye event in the response', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -382,7 +325,7 @@ describe('given a server error event in the response', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -408,7 +351,7 @@ describe('given a response with no payload-transferred event', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('status');
     if (result.type === 'status') {
@@ -433,7 +376,7 @@ describe('given an intent with code none', () => {
       body,
     });
 
-    const result = await poll(requestor, undefined, false, logger);
+    const result = await poll(requestor, undefined, logger);
 
     expect(result.type).toBe('changeSet');
     if (result.type === 'changeSet') {
@@ -473,7 +416,7 @@ describe('given a partial (changes) transfer', () => {
       body,
     });
 
-    const result = await poll(requestor, 'old-state', false, logger);
+    const result = await poll(requestor, 'old-state', logger);
 
     expect(result.type).toBe('changeSet');
     if (result.type === 'changeSet') {
@@ -515,7 +458,7 @@ describe('given a delete-object event', () => {
       body,
     });
 
-    const result = await poll(requestor, 'old-state', false, logger);
+    const result = await poll(requestor, 'old-state', logger);
 
     expect(result.type).toBe('changeSet');
     if (result.type === 'changeSet') {