asTerminalError to provide an easy mapping between domain model errors and Restate TerminalError (#562)

* TerminalError.cause should not be exposed. This commit deprecates it.

* Add `asTerminalError` to let people map their domain model errors to `TerminalError`

* Wireup + add example

Author: slinkydeveloper

packages/restate-sdk-examples/package.json

@@ -29,7 +29,7 @@
     "verify": "npm run format-check && npm run lint && npm run build",
     "release": "",
     "object": "RESTATE_LOGGING=debug tsx ./src/object.ts",
-    "greeter": "RESTATE_LOGGING=debug tsx ./src/greeter.ts",
+    "greeter": "RESTATE_LOGGING=debug tsx ./src/greeter_with_options.ts",
     "zgreeter": "RESTATE_LOGGING=debug tsx ./src/zod_greeter.ts",
     "workflow": "RESTATE_LOGGING=debug tsx ./src/workflow.ts",
     "workflow_client": "RESTATE_LOGGING=debug tsx ./src/workflow_client.ts",

packages/restate-sdk-examples/src/greeter_with_options.ts

@@ -13,9 +13,12 @@ import {
   service,
   endpoint,
   handlers,
+  TerminalError,
   type Context,
 } from "@restatedev/restate-sdk";
 
+class MyValidationError extends Error {}
+
 const greeter = service({
   name: "greeter",
   handlers: {
@@ -24,12 +27,23 @@ const greeter = service({
         journalRetention: { days: 1 },
       },
       async (ctx: Context, name: string) => {
+        if (name.length === 0) {
+          throw new MyValidationError("Name length is 0");
+        }
         return `Hello ${name}`;
       }
     ),
   },
   options: {
     journalRetention: { days: 2 },
+    asTerminalError: (err) => {
+      if (err instanceof MyValidationError) {
+        // My validation error is terminal
+        return new TerminalError(err.message, { errorCode: 400 });
+      }
+
+      // Any other error is retryable
+    },
   },
 });
 

packages/restate-sdk/src/context_impl.ts

@@ -104,7 +104,8 @@ export class ContextImpl implements ObjectContext, WorkflowContext {
     private readonly invocationRequest: Request,
     private readonly invocationEndPromise: CompletablePromise<void>,
     inputReader: ReadableStreamDefaultReader<Uint8Array>,
-    outputWriter: WritableStreamDefaultWriter<Uint8Array>
+    outputWriter: WritableStreamDefaultWriter<Uint8Array>,
+    private readonly asTerminalError?: (error: any) => TerminalError | undefined
   ) {
     this.rand = new RandImpl(input.invocation_id, () => {
       // TODO reimplement this check with async context
@@ -422,7 +423,7 @@ export class ContextImpl implements ObjectContext, WorkflowContext {
       try {
         res = await action();
       } catch (e) {
-        err = ensureError(e);
+        err = ensureError(e, this.asTerminalError);
       }
       const attemptDuration = Date.now() - startTime;
 

packages/restate-sdk/src/endpoint/handlers/generic.ts

@@ -16,7 +16,7 @@ import {
   TerminalError,
 } from "../../types/errors.js";
 import type { ProtocolMode } from "../../types/discovery.js";
-import type { ComponentHandler } from "../../types/components.js";
+import type { Component, ComponentHandler } from "../../types/components.js";
 import { parseUrlComponents } from "../../types/components.js";
 import { X_RESTATE_SERVER } from "../../user_agent.js";
 import type { EndpointBuilder } from "../endpoint_builder.js";
@@ -168,13 +168,13 @@ export class GenericHandler implements RestateHandler {
       this.endpoint.rlog.warn(errorMessage);
       return this.toErrorResponse(415, errorMessage);
     }
-    const method = this.endpoint.componentByName(parsed.componentName);
-    if (!method) {
+    const service = this.endpoint.componentByName(parsed.componentName);
+    if (!service) {
       const msg = `No service found for URL: ${JSON.stringify(parsed)}`;
       this.endpoint.rlog.error(msg);
       return this.toErrorResponse(404, msg);
     }
-    const handler = method?.handlerMatching(parsed);
+    const handler = service?.handlerMatching(parsed);
     if (!handler) {
       const msg = `No service found for URL: ${JSON.stringify(parsed)}`;
       this.endpoint.rlog.error(msg);
@@ -187,6 +187,7 @@ export class GenericHandler implements RestateHandler {
     }
 
     return this.handleInvoke(
+      service,
       handler,
       request.body,
       request.headers,
@@ -225,6 +226,7 @@ export class GenericHandler implements RestateHandler {
   }
 
   private async handleInvoke(
+    service: Component,
     handler: ComponentHandler,
     body: ReadableStream<Uint8Array>,
     headers: Headers,
@@ -365,7 +367,8 @@ export class GenericHandler implements RestateHandler {
         invocationRequest,
         invocationEndPromise,
         inputReader,
-        outputWriter
+        outputWriter,
+        service.options?.asTerminalError
       );
 
       // Finally invoke user handler
@@ -377,7 +380,7 @@ export class GenericHandler implements RestateHandler {
           vmLogger.info("Invocation completed successfully.");
         })
         .catch((e) => {
-          const error = ensureError(e);
+          const error = ensureError(e, service.options?.asTerminalError);
           logError(vmLogger, error);
 
           if (error instanceof TerminalError) {

packages/restate-sdk/src/types/components.ts

@@ -30,6 +30,7 @@ export interface Component {
   name(): string;
   handlerMatching(url: InvokePathComponents): ComponentHandler | undefined;
   discovery(): d.Service;
+  options?: ServiceOptions | ObjectOptions | WorkflowOptions;
 }
 
 export interface ComponentHandler {

packages/restate-sdk/src/types/errors.ts

@@ -20,7 +20,19 @@ export const UNKNOWN_ERROR_CODE = 500;
 export const CLOSED_ERROR_CODE = 598;
 export const SUSPENDED_ERROR_CODE = 599;
 
-export function ensureError(e: unknown): Error {
+export function ensureError(
+  e: unknown,
+  asTerminalError?: (error: any) => TerminalError | undefined
+): Error {
+  if (e instanceof TerminalError) {
+    return e;
+  }
+  // Try convert to terminal error
+  const maybeTerminalError = asTerminalError ? asTerminalError(e) : undefined;
+  if (maybeTerminalError) {
+    return maybeTerminalError;
+  }
+
   if (e instanceof Error) {
     return e;
   }
@@ -31,6 +43,7 @@ export function ensureError(e: unknown): Error {
     });
   }
 
+  // None of the types we know
   let msg;
   try {
     msg = JSON.stringify(e);
@@ -70,16 +83,34 @@ export class RestateError extends Error {
   }
 }
 
-// Does not lead to Restate retries
-// Leads to an output message with a failure defined
+/**
+ * Does not lead to Restate retries.
+ *
+ * Leads to an output message with a failure defined.
+ */
 export class TerminalError extends RestateError {
   public name = "TerminalError";
 
-  constructor(message: string, options?: { errorCode?: number; cause?: any }) {
+  constructor(
+    message: string,
+    options?: {
+      /**
+       * Error code. This should be an HTTP status code, and in case the service was invoked from the ingress, this will be propagated back to the caller.
+       */
+      errorCode?: number;
+      /**
+       * @deprecated YOU MUST NOT USE THIS FIELD, AS IT WON'T BE RECORDED AND CAN LEAD TO NON-DETERMINISM! From the next SDK version, the constructor won't accept this field anymore.
+       */
+      cause?: any;
+    }
+  ) {
     super(message, options);
   }
 }
 
+/**
+ * Returned by `RestatePromise.withTimeout` when the timeout is reached.
+ */
 export class TimeoutError extends TerminalError {
   public name = "TimeoutError";
 
@@ -88,6 +119,9 @@ export class TimeoutError extends TerminalError {
   }
 }
 
+/**
+ * Returned when the invocation was cancelled.
+ */
 export class CancelledError extends TerminalError {
   public name = "CancelledError";
 

packages/restate-sdk/src/types/rpc.ts

@@ -38,7 +38,7 @@ import {
   type Duration,
   serde,
 } from "@restatedev/restate-sdk-core";
-import { TerminalError } from "./errors.js";
+import { ensureError, TerminalError } from "./errors.js";
 
 // ----------- rpc clients -------------------------------------------------------
 
@@ -452,7 +452,8 @@ export class HandlerWrapper {
     public readonly inactivityTimeout?: Duration | number,
     public readonly abortTimeout?: Duration | number,
     public readonly ingressPrivate?: boolean,
-    public readonly enableLazyState?: boolean
+    public readonly enableLazyState?: boolean,
+    public readonly asTerminalError?: (error: any) => TerminalError | undefined
   ) {
     this.accept = accept ? accept : inputSerde.contentType;
     this.contentType = outputSerde.contentType;
@@ -467,9 +468,9 @@ export class HandlerWrapper {
     try {
       req = this.inputSerde.deserialize(input);
     } catch (e) {
-      throw new TerminalError(`Failed to deserialize input.`, {
+      const error = ensureError(e);
+      throw new TerminalError(`Failed to deserialize input: ${error.message}`, {
         errorCode: 400,
-        cause: e,
       });
     }
     const res: unknown = await this.handler(context, req);
@@ -818,6 +819,43 @@ export type ServiceOptions = {
    * otherwise the service discovery will fail.
    */
   ingressPrivate?: boolean;
+
+  /**
+   * By default, Restate will consider any error terminal, that is non retryable, if it's an instance of `TerminalError`.
+   *
+   * By setting this field, you can provide a function to map specific errors in your domain to `TerminalError` (or undefined, if the error should be considered retryable). Once `TerminalError`, these errors won't be retried.
+   *
+   * Note: this will be used both for errors thrown by `ctx.run` closures and by errors thrown in restate handlers.
+   *
+   * Example:
+   *
+   * ```ts
+   * class MyValidationError extends Error {}
+   *
+   * const greeter = restate.service({
+   *   name: "greeter",
+   *   handlers: {
+   *     greet: async (ctx: restate.Context, name: string) => {
+   *       if (name.length === 0) {
+   *         throw new MyValidationError("Length too short");
+   *       }
+   *       return `Hello ${name}`;
+   *     }
+   *   },
+   *   options: {
+   *     asTerminalError: (err) => {
+   *       if (err instanceof MyValidationError) {
+   *         // My validation error is terminal
+   *         return new restate.TerminalError(err.message, {errorCode: 400})
+   *       }
+   *
+   *       // Any other error is retryable
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  asTerminalError?: (error: any) => TerminalError | undefined;
 };
 
 /**