fix(common): throttle post-engagement FDv1 retries with backoff

The previous bypass skipped backoff for any LDFlagDeliveryFallbackError, not
just the initial server-directed engagement. After _fdv1FallbackEngaged is
set, the FDv1 fallback synchronizer can still produce LDFlagDeliveryFallback-
Error (e.g. a server that echoes x-ld-fd-fallback on the FDv1 endpoint), and
those retries were being scheduled with no delay -- in deployments with
multiple FDv1 fallback factories the composite would cycle through them all
with zero throttling before exhausting and stopping.

Narrow the bypass to the unique case engageFDv1Fallback produces: a
'switchToSync' transition carrying an LDFlagDeliveryFallbackError. Subsequent
LDFlagDeliveryFallbackErrors resolve a 'fallback' transition and go through
the normal _backoff.fail() path.

Adds a regression test that drives one FDv2 sync (engagement) followed by
two FDv1 factories that each emit LDFlagDeliveryFallbackError on start,
using a tracking Backoff to assert fail() is called twice (once per
post-engagement retry).

Author: keelerm84

packages/shared/common/__tests__/subsystem/DataSystem/CompositeDataSource.test.ts

@@ -875,6 +875,98 @@ it('ignores subsequent FDv1 fallback signals once FDv1 fallback is engaged', asy
   expect(dataReceived).toContain(fdv1Data);
 });
 
+// The backoff bypass applies only to the initial engagement; subsequent
+// LDFlagDeliveryFallbackErrors from the FDv1 synchronizer must be throttled.
+it('throttles FDv1 retries with backoff after the initial engagement', async () => {
+  const mockFDv2Sync = {
+    start: jest
+      .fn()
+      .mockImplementation(
+        (
+          _dataCallback: (basis: boolean, data: any) => void,
+          _statusCallback: (status: DataSourceState, err?: any) => void,
+        ) => {
+          _statusCallback(DataSourceState.Initializing);
+          _statusCallback(
+            DataSourceState.Closed,
+            new LDFlagDeliveryFallbackError(
+              DataSourceErrorKind.ErrorResponse,
+              'fallback from FDv2',
+              500,
+            ),
+          );
+        },
+      ),
+    stop: jest.fn(),
+  };
+
+  // Two FDv1 factories so the composite cycles through 'fallback' transitions instead
+  // of stopping after the first cull -- each cycle is a chance to (incorrectly) skip
+  // backoff. The tracking Backoff below counts fail() calls as the observable proxy.
+  const makeFDv1Sync = () => ({
+    start: jest
+      .fn()
+      .mockImplementation(
+        (
+          _dataCallback: (basis: boolean, data: any) => void,
+          _statusCallback: (status: DataSourceState, err?: any) => void,
+        ) => {
+          _statusCallback(DataSourceState.Initializing);
+          _statusCallback(
+            DataSourceState.Closed,
+            new LDFlagDeliveryFallbackError(
+              DataSourceErrorKind.ErrorResponse,
+              'fallback from FDv1',
+              500,
+            ),
+          );
+        },
+      ),
+    stop: jest.fn(),
+  });
+  const mockFDv1Sync1 = makeFDv1Sync();
+  const mockFDv1Sync2 = makeFDv1Sync();
+
+  let failCalls = 0;
+  let successCalls = 0;
+  const trackingBackoff: Backoff = {
+    success() {
+      successCalls += 1;
+      return 0;
+    },
+    fail() {
+      failCalls += 1;
+      return 0;
+    },
+  };
+
+  const underTest = new CompositeDataSource(
+    [],
+    [makeDataSourceFactory(mockFDv2Sync)],
+    [makeDataSourceFactory(mockFDv1Sync1), makeDataSourceFactory(mockFDv1Sync2)],
+    undefined,
+    makeTestTransitionConditions(),
+    trackingBackoff,
+  );
+
+  const statusCallback = jest.fn();
+  await new Promise<void>((resolve) => {
+    statusCallback.mockImplementation((state: DataSourceState) => {
+      if (state === DataSourceState.Closed) {
+        resolve();
+      }
+    });
+    underTest.start(jest.fn(), statusCallback);
+  });
+
+  expect(mockFDv2Sync.start).toHaveBeenCalledTimes(1);
+  expect(mockFDv1Sync1.start).toHaveBeenCalledTimes(1);
+  expect(mockFDv1Sync2.start).toHaveBeenCalledTimes(1);
+  // One fail() per post-engagement retry; the initial engagement is not counted.
+  expect(failCalls).toBe(2);
+  expect(successCalls).toBe(0);
+});
+
 it('reports error when all initializers fail', async () => {
   const mockInitializer1Error = {
     name: 'Error',

packages/shared/common/src/datasource/CompositeDataSource.ts

@@ -246,12 +246,19 @@ export class CompositeDataSource implements DataSource {
       // stop the underlying datasource before transitioning to next state
       currentDS?.stop();
 
+      // Skip backoff only on the initial server-directed FDv1 engagement (a `switchToSync`
+      // transition resolved by `engageFDv1Fallback` carries an `LDFlagDeliveryFallbackError`).
+      // Any subsequent `LDFlagDeliveryFallbackError` is an ordinary retry from the FDv1
+      // synchronizer (or a follow-up FDv1 factory) and must be throttled like any other
+      // error retry.
+      const isInitialFDv1Engagement =
+        transitionRequest.transition === 'switchToSync' &&
+        transitionRequest.err instanceof LDFlagDeliveryFallbackError;
+
       if (
         transitionRequest.err &&
         transitionRequest.transition !== 'stop' &&
-        // The server-directed FDv1 fallback is not an error retry -- the directive should be
-        // honored immediately so the FDv1 synchronizer can take over without delay.
-        !(transitionRequest.err instanceof LDFlagDeliveryFallbackError)
+        !isInitialFDv1Engagement
       ) {
         // if the transition was due to an error we're not in the initializer phase, throttle the transition. Fallback between initializers is not throttled.
         const delay = this._initPhaseActive ? 0 : this._backoff.fail();