chore(davinci-client): refactor and improve polling

Author: ancheetah

.changeset/lucky-parts-own.md

@@ -0,0 +1,6 @@
+---
+'@forgerock/sdk-request-middleware': minor
+'@forgerock/davinci-client': minor
+---
+
+Support both challenge polling and continue polling in DaVinci

e2e/davinci-app/components/polling.ts

@@ -25,6 +25,8 @@ export default function pollingComponent(
   formEl.appendChild(button);
 
   button.onclick = async () => {
+    button.disabled = true;
+
     const p = document.createElement('p');
     p.innerText = 'Polling...';
     formEl?.appendChild(p);
@@ -54,5 +56,7 @@ export default function pollingComponent(
     formEl?.appendChild(resultEl);
 
     await submitForm();
+
+    button.disabled = false;
   };
 }

packages/davinci-client/src/lib/client.store.effects.ts

@@ -0,0 +1,256 @@
+/*
+ * Copyright (c) 2026 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { Micro } from 'effect';
+import { exitIsSuccess, exitIsFail } from 'effect/Micro';
+import { SerializedError } from '@reduxjs/toolkit/react';
+import { FetchBaseQueryError } from '@reduxjs/toolkit/query/react';
+
+import { isGenericError } from '@forgerock/sdk-utilities';
+import type { logger as loggerFn } from '@forgerock/sdk-logger';
+
+import type { ClientStore, RootState } from './client.store.utils.js';
+import type { PollingStatus, InternalErrorResponse } from './client.types.js';
+import type { PollingCollector } from './collector.types.js';
+import type { ContinueNode } from './node.types.js';
+
+import { createInternalError } from './client.store.utils.js';
+import { davinciApi } from './davinci.api.js';
+import { nodeSlice } from './node.slice.js';
+
+/**
+ * Shape returned by RTK Query's dispatch for the poll endpoint.
+ */
+export interface PollDispatchResult {
+  data?: unknown;
+  error?: FetchBaseQueryError | SerializedError;
+}
+
+/**
+ * Validated prerequisites needed to initiate challenge polling.
+ */
+interface PollingPrerequisites {
+  interactionId: string;
+  challengeEndpoint: string;
+}
+
+/**
+ * Type guard: determines if a value is a plain object (Record<string, unknown>).
+ */
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Selects and validates server is in continue state from root state.
+ * Narrows from the NodeStates server union to ContinueNode['server'].
+ * Throws InternalErrorResponse on validation failure.
+ */
+function selectContinueServer(rootState: RootState): ContinueNode['server'] {
+  const server = nodeSlice.selectors.selectServer(rootState);
+
+  if (server === null) {
+    throw createInternalError('No server info found for poll operation', 'state_error');
+  }
+
+  if (isGenericError(server)) {
+    throw createInternalError(
+      server.message ?? 'Failed to retrieve server info for poll operation',
+    );
+  }
+
+  if (server.status !== 'continue') {
+    throw createInternalError(
+      'Not in a continue node state, must be in a continue node to use poll method',
+      'state_error',
+    );
+  }
+
+  return server;
+}
+
+/**
+ * Extracts the self link href from server links.
+ * Throws InternalErrorResponse if self link is missing.
+ */
+function selectSelfLink(server: ContinueNode['server']): string {
+  const links = server._links;
+  if (!links || !('self' in links) || !('href' in links['self']) || !links['self'].href) {
+    throw createInternalError(
+      'No self link found in server info for challenge polling operation',
+      'state_error',
+    );
+  }
+  return links['self'].href;
+}
+
+/**
+ * Constructs the challenge polling endpoint from a self link URL.
+ * Throws InternalErrorResponse if URL cannot be parsed.
+ */
+function buildChallengeEndpoint(selfHref: string, challenge: string): string {
+  const url = new URL(selfHref);
+  const envId = url.pathname.split('/')[1];
+
+  if (!url.origin || !envId) {
+    throw createInternalError(
+      'Failed to construct challenge polling endpoint. Requires host and environment ID.',
+      'parse_error',
+    );
+  }
+
+  return `${url.origin}/${envId}/davinci/user/credentials/challenge/${challenge}/status`;
+}
+
+/**
+ * Pure function: validates all prerequisites for challenge polling and constructs the endpoint URL.
+ * Composes selectors that each extract and validate a piece of state.
+ * Throws InternalErrorResponse on any validation failure — designed to be caught by Micro.try.
+ */
+export function validatePollingPrerequisites(
+  rootState: RootState,
+  challenge: string,
+): PollingPrerequisites {
+  if (!challenge) {
+    throw createInternalError('No challenge found on collector for poll operation', 'state_error');
+  }
+
+  const server = selectContinueServer(rootState);
+  const selfHref = selectSelfLink(server);
+  const challengeEndpoint = buildChallengeEndpoint(selfHref, challenge);
+
+  if (!server.interactionId) {
+    throw createInternalError(
+      'Missing interactionId in server info for challenge polling',
+      'state_error',
+    );
+  }
+
+  return { interactionId: server.interactionId, challengeEndpoint };
+}
+
+/**
+ * Pure predicate: determines if challenge polling should continue.
+ * Returns true when the challenge has not yet completed and no error occurred.
+ */
+export function isChallengeStillPending(response: PollDispatchResult): boolean {
+  if (response.error) return false;
+
+  const data = isRecord(response.data) ? response.data : undefined;
+  if (data?.['isChallengeComplete']) return false;
+
+  return true;
+}
+
+export function interpretChallengeResponse(
+  response: PollDispatchResult,
+  log: ReturnType<typeof loggerFn>,
+): Micro.Micro<PollingStatus, InternalErrorResponse> {
+  const { data, error } = response;
+
+  if (error) {
+    // FetchBaseQueryError — has status field
+    if ('status' in error) {
+      const errorDetails = isRecord(error.data) ? error.data : undefined;
+      const serviceName = errorDetails?.['serviceName'];
+
+      // Expired challenge is an expected polling outcome, not a failure
+      if (error.status === 400 && serviceName === 'challengeExpired') {
+        log.debug('Challenge expired for polling');
+        return Micro.succeed('expired' as PollingStatus);
+      }
+
+      // Other HTTP errors are also expected outcomes (e.g. bad challenge returning 400 with code 4019)
+      log.debug('Unknown error occurred during polling');
+      return Micro.succeed('error' as PollingStatus);
+    }
+
+    // SerializedError — has message field
+    const message =
+      'message' in error && error.message
+        ? error.message
+        : 'An unknown error occurred while challenge polling';
+
+    return Micro.fail(createInternalError(message, 'unknown_error'));
+  }
+
+  if (!isRecord(data)) {
+    log.debug('Unable to parse polling response');
+    return Micro.succeed('error' as PollingStatus);
+  }
+  const pollResponse = data;
+
+  // Challenge completed — extract status
+  if (pollResponse['isChallengeComplete'] === true) {
+    const pollStatus = pollResponse['status'];
+    return pollStatus
+      ? Micro.succeed(pollStatus as PollingStatus)
+      : Micro.succeed('error' as PollingStatus);
+  }
+
+  // If we reach here, Micro.repeat exhausted its schedule without the challenge completing
+  log.debug('Challenge polling timed out');
+  return Micro.succeed('timedOut' as PollingStatus);
+}
+
+/**
+ * Orchestrates challenge polling using extracted pure functions.
+ * The shell: reads state, dispatches effects, runs the pipeline at the boundary.
+ */
+export async function handleChallengePolling({
+  collector,
+  challenge,
+  store,
+  log,
+}: {
+  collector: PollingCollector;
+  challenge: string;
+  store: ReturnType<ClientStore>;
+  log: ReturnType<typeof loggerFn>;
+}): Promise<PollingStatus | InternalErrorResponse> {
+  const maxRetries = collector.output.config.pollRetries ?? 60;
+  const pollInterval = collector.output.config.pollInterval ?? 2000;
+
+  // validate → query → repeat → interpret
+  const challengePollµ = Micro.try({
+    try: () => validatePollingPrerequisites(store.getState(), challenge),
+    catch: (error) => error as InternalErrorResponse,
+  }).pipe(
+    Micro.flatMap(({ interactionId, challengeEndpoint }) =>
+      Micro.promise(() =>
+        store.dispatch(
+          davinciApi.endpoints.poll.initiate({
+            endpoint: challengeEndpoint,
+            interactionId,
+          }),
+        ),
+      ).pipe(
+        Micro.repeat({
+          while: isChallengeStillPending,
+          // `times` - tracks repetitions automatically and stops when the threshold is reached
+          //         - counts the number of retries after the initial attempt so decrement by one
+          times: maxRetries - 1,
+          schedule: Micro.scheduleSpaced(pollInterval),
+        }),
+      ),
+    ),
+    Micro.flatMap((response) => interpretChallengeResponse(response, log)),
+    Micro.tapError(({ error }) => Micro.sync(() => log.error(error.message))),
+  );
+
+  const result = await Micro.runPromiseExit(challengePollµ);
+
+  if (exitIsSuccess(result)) {
+    return result.value;
+  } else if (exitIsFail(result)) {
+    return result.cause.error;
+  }
+
+  return {
+    error: { message: result.cause.message, type: 'unknown_error' },
+    type: 'internal_error',
+  };
+}