@player-ui/player 0.15.3 → 0.15.4--canary.881.37421

package/src/controllers/error/__tests__/middleware.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, beforeEach, expect, vitest } from "vitest";
+import { ERROR_BINDING_PREFIX, ErrorStateMiddleware } from "../middleware";
+import { BindingInstance, BindingParser } from "../../../binding";
+import type {
+  BatchSetTransaction,
+  DataModelImpl,
+  DataModelOptions,
+} from "../../../data";
+import { LocalModel } from "../../../data";
+import type { Logger } from "../../../logger";
+
+describe("ErrorStateMiddleware", () => {
+  let middleware: ErrorStateMiddleware;
+  let baseDataModel: DataModelImpl;
+  // Shortcut to using middleware with baseDataModel as "next"
+  let pipelineModel: DataModelImpl;
+  let mockLogger: Logger;
+  let parser: BindingParser;
+  let writeSymbol: symbol;
+
+  beforeEach(() => {
+    mockLogger = {
+      trace: vitest.fn(),
+      debug: vitest.fn(),
+      info: vitest.fn(),
+      warn: vitest.fn(),
+      error: vitest.fn(),
+    };
+
+    writeSymbol = Symbol("test-write");
+    middleware = new ErrorStateMiddleware({
+      logger: mockLogger,
+      writeSymbol,
+    });
+    baseDataModel = new LocalModel({ foo: "bar" });
+
+    parser = new BindingParser({
+      get: () => undefined,
+      set: () => undefined,
+      evaluate: () => undefined,
+    });
+
+    pipelineModel = {
+      get: (binding: BindingInstance, options?: DataModelOptions) =>
+        middleware.get(binding, options, baseDataModel),
+      set: (transaction: BatchSetTransaction, options?: DataModelOptions) =>
+        middleware.set(transaction, options, baseDataModel),
+      delete: (binding: BindingInstance, options?: DataModelOptions) =>
+        middleware.delete(binding, options, baseDataModel),
+    };
+  });
+
+  describe("set", () => {
+    it("should not write to the base data model", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+      pipelineModel.set([[binding, { message: "test" }]], {
+        writeSymbol,
+      });
+
+      expect(pipelineModel.get(binding)).toStrictEqual({ message: "test" });
+      expect(baseDataModel.get(binding)).toBeUndefined();
+    });
+    it("should block writes to errorState without writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+      const updates = pipelineModel.set([[binding, { message: "test" }]]);
+
+      // Should not write to base model
+      expect(pipelineModel.get(binding)).toBeUndefined();
+
+      // Should log warning
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("Blocked write to protected path: errorState"),
+      );
+
+      // Should return no-op update
+      expect(updates.length).toBe(1);
+      expect(updates[0]!.binding).toBe(binding);
+      expect(updates[0]!.newValue).toBeUndefined();
+      expect(updates[0]!.oldValue).toBeUndefined();
+    });
+
+    it("should block writes to nested errorState paths", () => {
+      const binding = parser.parse(`${ERROR_BINDING_PREFIX}.message`);
+      pipelineModel.set([[binding, "test message"]]);
+
+      expect(pipelineModel.get(binding)).toBeUndefined();
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Blocked write to protected path: errorState.message",
+        ),
+      );
+    });
+
+    it("should allow writes to other paths", () => {
+      const binding = parser.parse("foo");
+      const updates = pipelineModel.set([[binding, "newValue"]]);
+
+      expect(pipelineModel.get(binding)).toBe("newValue");
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+      expect(updates.length).toBe(1);
+      expect(updates[0]!.newValue).toBe("newValue");
+    });
+
+    it("should allow writes when authorized with writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+
+      const updates = pipelineModel.set([[binding, { message: "test" }]], {
+        writeSymbol: writeSymbol,
+      });
+
+      expect(pipelineModel.get(binding)).toEqual({ message: "test" });
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+      expect(updates.length).toBe(1);
+      expect(updates[0]!.newValue).toEqual({ message: "test" });
+    });
+
+    it("should block writes with wrong writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+      const wrongSymbol = Symbol("wrong-auth");
+
+      pipelineModel.set([[binding, { message: "test" }]], {
+        writeSymbol: wrongSymbol,
+      });
+
+      expect(pipelineModel.get(binding)).toBeUndefined();
+      expect(mockLogger.warn).toHaveBeenCalled();
+    });
+
+    it("should handle mixed transactions with blocked and allowed paths", () => {
+      const errorBinding = parser.parse(ERROR_BINDING_PREFIX);
+      const fooBinding = parser.parse("foo");
+
+      const updates = pipelineModel.set([
+        [errorBinding, { message: "blocked" }],
+        [fooBinding, "allowed"],
+      ]);
+
+      // foo should be updated
+      expect(pipelineModel.get(fooBinding)).toBe("allowed");
+
+      // errorState should not be updated
+      expect(pipelineModel.get(errorBinding)).toBeUndefined();
+
+      // Should have logged warning for errorState
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("Blocked write to protected path: errorState"),
+      );
+
+      // Should have updates for both paths
+      expect(updates.length).toBe(2);
+    });
+  });
+
+  describe("get", () => {
+    it("should not read error state from the base model", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+
+      // Set value directly on base model
+      baseDataModel.set([[binding, { message: "test" }]]);
+
+      expect(pipelineModel.get(binding)).toBeUndefined();
+    });
+
+    it("should read without needing any permissions", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+      pipelineModel.set([[binding, { message: "test" }]], { writeSymbol });
+
+      const value = pipelineModel.get(binding);
+      expect(value).toStrictEqual({ message: "test" });
+    });
+  });
+
+  describe("delete", () => {
+    it("should block deletes to errorState without writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+
+      // Set value first
+      pipelineModel.set([[binding, { message: "test" }]], { writeSymbol });
+
+      pipelineModel.delete(binding);
+
+      // Should still exist
+      expect(pipelineModel.get(binding)).toEqual({ message: "test" });
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("Blocked delete of protected path: errorState"),
+      );
+    });
+
+    it("should allow deletes when authorized with writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+
+      // Set value first
+      pipelineModel.set([[binding, { message: "test" }]], { writeSymbol });
+
+      pipelineModel.delete(binding, { writeSymbol: writeSymbol });
+
+      expect(pipelineModel.get(binding)).toBeUndefined();
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+    });
+
+    it("should block deletes with wrong writeSymbol", () => {
+      const binding = parser.parse(ERROR_BINDING_PREFIX);
+      const wrongSymbol = Symbol("wrong-auth");
+
+      // Set value first
+      pipelineModel.set([[binding, { message: "test" }]], { writeSymbol });
+
+      pipelineModel.delete(binding, { writeSymbol: wrongSymbol });
+
+      expect(pipelineModel.get(binding)).toEqual({ message: "test" });
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("Blocked delete of protected path: errorState"),
+      );
+    });
+
+    it("should allow deletes to other paths", () => {
+      const binding = parser.parse("foo");
+
+      pipelineModel.delete(binding);
+
+      expect(baseDataModel.get(binding)).toBeUndefined();
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+    });
+
+    it("should allow deletes to nested errorState paths when authorized", () => {
+      const binding = parser.parse(`${ERROR_BINDING_PREFIX}.nested.path`);
+
+      // Set value first
+      pipelineModel.set([[binding, "test"]], { writeSymbol });
+
+      pipelineModel.delete(binding, { writeSymbol: writeSymbol });
+
+      expect(pipelineModel.get(binding)).toBeUndefined();
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/controllers/error/__tests__/navigation.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, beforeEach, expect, vitest } from "vitest";
+import { ErrorController } from "../controller";
+import { FlowController } from "../../flow/controller";
+import { FlowInstance } from "../../flow/flow";
+import {
+  ErrorMetadata,
+  ErrorSeverity,
+  ErrorTypes,
+  PlayerErrorMetadata,
+} from "../types";
+import type { Logger } from "../../../logger";
+import type { DataController } from "../../data/controller";
+
+/** Test class to create an error with any additional properties */
+class ErrorWithProps extends Error implements PlayerErrorMetadata {
+  constructor(
+    message: string,
+    public type: string,
+    public severity?: ErrorSeverity,
+    public metadata?: ErrorMetadata,
+  ) {
+    super(message);
+  }
+}
+
+describe("ErrorController Navigation", () => {
+  let errorController: ErrorController;
+  let mockFlowController: FlowController;
+  let mockFlowInstance: FlowInstance;
+  let mockDataController: DataController;
+  let mockLogger: Logger;
+  let mockFail: ReturnType<typeof vitest.fn>;
+
+  beforeEach(() => {
+    mockLogger = {
+      trace: vitest.fn(),
+      debug: vitest.fn(),
+      info: vitest.fn(),
+      warn: vitest.fn(),
+      error: vitest.fn(),
+    };
+
+    mockDataController = {
+      set: vitest.fn(),
+      get: vitest.fn(),
+      delete: vitest.fn(),
+    } as any;
+
+    mockFail = vitest.fn();
+
+    // Mock FlowInstance
+    mockFlowInstance = {
+      currentState: {
+        name: "VIEW_Start",
+        value: {
+          state_type: "VIEW",
+          ref: "start-view",
+          transitions: {
+            next: "VIEW_Next",
+          },
+        },
+      },
+      errorTransition: vitest.fn(),
+      getErrorTransitionState: vitest.fn(() => true),
+    } as any;
+
+    // Mock FlowController
+    mockFlowController = {
+      current: mockFlowInstance,
+      reject: vitest.fn(),
+    } as any;
+
+    errorController = new ErrorController({
+      logger: mockLogger,
+      model: mockDataController,
+      flow: mockFlowController,
+      fail: mockFail,
+    });
+  });
+
+  describe("errorTransitions navigation", () => {
+    it("should navigate using errorTransition method", () => {
+      const error = new ErrorWithProps("Test error", ErrorTypes.VIEW);
+      errorController.captureError(error);
+
+      // Should call errorTransition with errorType
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith(
+        ErrorTypes.VIEW,
+      );
+      expect(mockFail).not.toHaveBeenCalled();
+    });
+
+    it("should navigate using a wildcard transition when no error type is available", () => {
+      const error = new Error("Test error");
+      errorController.captureError(error);
+
+      // Should call errorTransition with errorType
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith("*");
+      expect(mockFail).not.toHaveBeenCalled();
+    });
+
+    it("should reject flow when errorTransition throws", () => {
+      mockFlowInstance.errorTransition = vitest.fn().mockImplementation(() => {
+        throw new Error("No errorTransitions defined");
+      });
+
+      const error = new ErrorWithProps("Test error", ErrorTypes.NAVIGATION);
+      errorController.captureError(error);
+
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith(
+        ErrorTypes.NAVIGATION,
+      );
+      expect(mockFail).toHaveBeenCalledWith(error);
+    });
+
+    it("should pass correct errorType to errorTransition", () => {
+      const error = new ErrorWithProps("Binding failed", "binding");
+      errorController.captureError(error);
+
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith("binding");
+    });
+
+    it("should pass custom errorType to errorTransition", () => {
+      const error = new ErrorWithProps("Custom error", "custom_type");
+      errorController.captureError(error);
+
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith(
+        "custom_type",
+      );
+    });
+
+    it("should fail the player state when there is no available transition", () => {
+      vitest
+        .mocked(mockFlowController.current?.getErrorTransitionState)
+        ?.mockReturnValue(undefined);
+      const error = new ErrorWithProps("Test error", ErrorTypes.VIEW);
+      errorController.captureError(error);
+      expect(mockFail).toHaveBeenCalled();
+    });
+  });
+
+  describe("Hook integration", () => {
+    it("should skip navigation when plugin bails", () => {
+      errorController.hooks.onError.tap("test", () => true);
+
+      const error = new ErrorWithProps("Test error", ErrorTypes.NAVIGATION);
+      errorController.captureError(error);
+
+      // Should not navigate when bailed
+      expect(mockFlowInstance.errorTransition).not.toHaveBeenCalled();
+      expect(mockFail).not.toHaveBeenCalled();
+    });
+
+    it("should navigate when plugin does not bail", () => {
+      errorController.hooks.onError.tap("test", () => undefined);
+
+      const error = new ErrorWithProps("Test error", ErrorTypes.NAVIGATION);
+      errorController.captureError(error);
+
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith(
+        ErrorTypes.NAVIGATION,
+      );
+    });
+
+    it("should navigate when plugin returns false", () => {
+      errorController.hooks.onError.tap("test", () => false);
+
+      const error = new ErrorWithProps("Test error", ErrorTypes.VIEW);
+      errorController.captureError(error);
+
+      expect(mockFlowInstance.errorTransition).toHaveBeenCalledWith(
+        ErrorTypes.VIEW,
+      );
+    });
+  });
+
+  describe("No active flow", () => {
+    it("should warn and not navigate when no active flow", () => {
+      mockFlowController.current = undefined;
+
+      const error = new ErrorWithProps("Test error", ErrorTypes.VIEW);
+      errorController.captureError(error);
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        "[ErrorController] No active flow instance for error navigation",
+      );
+      expect(mockFail).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/controllers/error/controller.ts

@@ -0,0 +1,257 @@
+import { SyncBailHook } from "tapable-ts";
+import type { Logger } from "../../logger";
+import type { DataController } from "../data/controller";
+import type { FlowController } from "../flow/controller";
+import type { PlayerError } from "./types";
+import { ErrorStateMiddleware } from "./middleware";
+import { isErrorWithMetadata, makeJsonStringifyReplacer } from "./utils";
+
+/**
+ * Private symbol used to authorize ErrorController's writes to errorState
+ * Only ErrorController has access to this symbol
+ */
+const errorControllerWriteSymbol: unique symbol = Symbol(
+  "errorControllerWrite",
+);
+
+export interface ErrorControllerHooks {
+  /**
+   * Fired when any error is captured
+   * - Called in order for each tapped plugin
+   * - Return true to bail and prevent error state navigation
+   * - Return undefined/false to continue to next handler
+   * - Once true is returned, no further plugins are called
+   */
+  onError: SyncBailHook<[PlayerError], boolean | undefined>;
+}
+
+export interface ErrorControllerOptions {
+  /** Logger for error operations */
+  logger: Logger;
+  /** Flow controller for error navigation */
+  flow: FlowController;
+  /** Callback to fail/reject the flow */
+  fail: (error: Error) => void;
+  /** Data model for setting errorState (can be set later via setOptions) */
+  model?: DataController;
+}
+
+/** The orchestrator for player error handling */
+export class ErrorController {
+  public hooks: ErrorControllerHooks = {
+    onError: new SyncBailHook(),
+  };
+
+  private options: ErrorControllerOptions;
+  private readonly middleware: ErrorStateMiddleware;
+  /**
+   * Complete history of all captured errors in chronological order
+   * Newest errors are APPENDED to the end of the array
+   */
+  private errorHistory: PlayerError[] = [];
+  private currentError?: PlayerError;
+
+  constructor(options: ErrorControllerOptions) {
+    this.options = options;
+
+    this.middleware = new ErrorStateMiddleware({
+      logger: options.logger,
+      writeSymbol: errorControllerWriteSymbol,
+    });
+  }
+
+  /**
+   * Get the middleware for protecting errorState
+   * This should be added to DataController's middleware array
+   */
+  public getDataMiddleware(): ErrorStateMiddleware {
+    return this.middleware;
+  }
+
+  /**
+   * Set the DataController after initialization
+   */
+  public setOptions(options: Pick<ErrorControllerOptions, "model">): void {
+    this.options.model = options.model;
+  }
+
+  /**
+   * Capture an error and try to recover. Errors implementing the `PlayerErrorMetadata` interface will be added to history, fire hooks and update data model. As a fallback, all errors will try to trigger an errorTransition. If the error does not have a `type` property, it will default to only using the wildcard navigation.
+   */
+  public captureError(error: Error): boolean {
+    if (!isErrorWithMetadata(error)) {
+      this.options.logger.debug(
+        `[ErrorController] Captured error: ${error.message}\n`,
+        "Cannot determine optional error metadata, attempting default error navigation...",
+      );
+      return this.tryNavigateToErrorState(error, "*");
+    }
+
+    // Add to history
+    this.errorHistory.push(error);
+
+    // Set as current error
+    this.currentError = error;
+
+    this.options.logger.debug(
+      `[ErrorController] Captured error: ${error.message}`,
+      JSON.stringify(
+        {
+          errorType: error.type,
+          severity: error.severity,
+          metadata: error.metadata,
+        },
+        makeJsonStringifyReplacer(),
+      ),
+    );
+
+    // Notify listeners and check if navigation should be skipped
+    // Plugins can observe the error and optionally return true to bail
+    const shouldSkip = this.hooks.onError.call(error) ?? false;
+
+    if (shouldSkip) {
+      this.options.logger.debug(
+        "[ErrorController] Error state navigation skipped by plugin",
+      );
+      return true;
+    }
+
+    // Set error in data model
+    this.setErrorInDataModel(error);
+
+    // Navigate to error state
+    return this.tryNavigateToErrorState(error, error.type);
+  }
+
+  /**
+   * Navigate to error state using errorTransitions.
+   * Uses errorTransition() which handles node-level and flow-level fallback internally.
+   */
+  private tryNavigateToErrorState(error: Error, transition: string): boolean {
+    const flowInstance = this.options.flow.current;
+
+    if (!flowInstance) {
+      this.options.logger.warn(
+        "[ErrorController] No active flow instance for error navigation",
+      );
+      return false;
+    }
+
+    if (flowInstance.getErrorTransitionState(transition) === undefined) {
+      this.options.fail(error);
+      return false;
+    }
+
+    try {
+      flowInstance.errorTransition(transition);
+      return true;
+    } catch (e) {
+      this.options.logger.error(
+        `[ErrorController] Error transition failed with unexpected error: ${e}`,
+      );
+
+      // Fallback: Reject flow
+      this.options.logger.debug("[ErrorController] Rejecting flow with error");
+      this.options.fail(error);
+      return false;
+    }
+  }
+
+  /**
+   * Get most recent error
+   */
+  public getCurrentError(): PlayerError | undefined {
+    return this.currentError;
+  }
+
+  /**
+   * Get error history (read-only)
+   */
+  public getErrors(): ReadonlyArray<PlayerError> {
+    return this.errorHistory;
+  }
+
+  /**
+   * Clear all errors (history + current + data model)
+   */
+  public clearErrors(): void {
+    this.errorHistory = [];
+    this.currentError = undefined;
+    this.deleteErrorFromDataModel();
+    this.options.logger.debug("[ErrorController] All errors cleared");
+  }
+
+  /**
+   * Clear only current error and remove from data model, preserve history
+   */
+  public clearCurrentError(): void {
+    this.currentError = undefined;
+    this.deleteErrorFromDataModel();
+    this.options.logger.debug("[ErrorController] Current error cleared");
+  }
+
+  /**
+   * Write error to data model errorState
+   */
+  private setErrorInDataModel(playerError: PlayerError): void {
+    if (!this.options.model) {
+      this.options.logger.warn("[ErrorController] No DataController available");
+      return;
+    }
+
+    try {
+      const { type, severity, metadata, name, message } = playerError;
+
+      // Pass write symbol to authorize write through middleware
+      this.options.model.set(
+        [
+          [
+            "errorState",
+            {
+              message,
+              name,
+              errorType: type,
+              severity,
+              ...metadata,
+            },
+          ],
+        ],
+        { writeSymbol: errorControllerWriteSymbol },
+      );
+
+      this.options.logger.debug(
+        "[ErrorController] Error set in data model at 'data.errorState'",
+      );
+    } catch (e) {
+      this.options.logger.error(
+        "[ErrorController] Failed to set error in data model",
+        e,
+      );
+    }
+  }
+
+  /**
+   * Remove errorState from data model
+   */
+  private deleteErrorFromDataModel(): void {
+    if (!this.options.model) {
+      return;
+    }
+
+    try {
+      // Pass write symbol to authorize delete through middleware
+      this.options.model.delete("errorState", {
+        writeSymbol: errorControllerWriteSymbol,
+      });
+
+      this.options.logger.debug(
+        "[ErrorController] errorState deleted from data model",
+      );
+    } catch (e) {
+      this.options.logger.error(
+        "[ErrorController] Failed to delete errorState from data model",
+        e,
+      );
+    }
+  }
+}

package/src/controllers/error/index.ts

@@ -0,0 +1,3 @@
+export * from "./controller";
+export * from "./types";
+export * from "./middleware";