@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/utils/public_utils.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate SDK for Node.js/TypeScript,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in file LICENSE in the root
+ * directory of this repository or package, or at
+ * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE
+ */
+
+/**
+ * Retry policy that decides how to delay between retries.
+ */
+export interface RetryPolicy {
+  computeNextDelay(previousDelayMs: number): number;
+}
+
+/**
+ * A {@link RetryPolicy} that keeps a fixed delay between retries.
+ */
+export const FIXED_DELAY: RetryPolicy = {
+  computeNextDelay(previousDelayMs: number): number {
+    return previousDelayMs;
+  },
+};
+
+/**
+ * A {@link RetryPolicy} that does an exponential backoff delay between retries.
+ * Each delay is twice as long as the previous delay.
+ */
+export const EXPONENTIAL_BACKOFF: RetryPolicy = {
+  computeNextDelay(previousDelayMs: number): number {
+    return 2 * previousDelayMs;
+  },
+};
+
+/**
+ * All properties related to retrying, like the policy (exponential, fixed, ...), the
+ * initial delay, the maximum number of retries.
+ */
+export interface RetrySettings {
+  /**
+   * The initial delay between retries. As more retries happen, the delay may change per the policy.
+   */
+  initialDelayMs?: number;
+
+  /**
+   * Optionally, the maximum delay between retries. No matter what the policy says, this is the maximum time
+   * that Restate sleeps between retries.
+   * If not set, there is effectively no limit (internally the limit is Number.MAX_SAFE_INTEGER).
+   */
+  maxDelayMs?: number;
+
+  /**
+   * Optionally, the maximum number of retries before this function fails with an exception.
+   * If not set, there is effectively no limit (internally the limit is Number.MAX_SAFE_INTEGER).
+   */
+  maxRetries?: number;
+
+  /**
+   * Optionally, the {@link RetryPolicy} to use. Defaults to {@link EXPONENTIAL_BACKOFF}.
+   */
+  policy?: RetryPolicy;
+
+  /**
+   * Optionally, the name of side effect action that is used in error- and log messages around retries.
+   */
+  name?: string;
+}
+
+/**
+ * The default initial delay between retries: 10 milliseconds.
+ */
+export const DEFAULT_INITIAL_DELAY_MS = 10;
+
+/**
+ * Default retry policy that retries an infinite number of times, with exponential backoff
+ * and a starting delay of 10 milliseconds.
+ */
+export const DEFAULT_INFINITE_EXPONENTIAL_BACKOFF: RetrySettings = {
+  initialDelayMs: DEFAULT_INITIAL_DELAY_MS,
+  maxDelayMs: Number.MAX_SAFE_INTEGER,
+  maxRetries: Number.MAX_SAFE_INTEGER,
+  policy: EXPONENTIAL_BACKOFF,
+};
+
+/**
+ * Retry policy that does no retries.
+ */
+export const NO_RETRIES: RetrySettings = { maxRetries: 0 };

package/src/utils/rand.ts

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate SDK for Node.js/TypeScript,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in file LICENSE in the root
+ * directory of this repository or package, or at
+ * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE
+ */
+
+//! Some parts copied from https://github.com/uuidjs/uuid/blob/main/src/stringify.js
+//! License MIT
+
+import { Rand } from "../context";
+import { ErrorCodes, TerminalError } from "../types/errors";
+import { CallContexType, ContextImpl } from "../context_impl";
+import { createHash } from "crypto";
+
+export class RandImpl implements Rand {
+  private randstate256: [bigint, bigint, bigint, bigint];
+
+  constructor(id: Buffer | [bigint, bigint, bigint, bigint]) {
+    if (id instanceof Buffer) {
+      // hash the invocation ID, which is known to contain 74 bits of entropy
+      const hash = createHash("sha256").update(id).digest();
+
+      this.randstate256 = [
+        hash.readBigUInt64LE(0),
+        hash.readBigUInt64LE(8),
+        hash.readBigUInt64LE(16),
+        hash.readBigUInt64LE(24),
+      ];
+    } else {
+      this.randstate256 = id;
+    }
+  }
+
+  static U64_MASK = (1n << 64n) - 1n;
+
+  // xoshiro256++
+  // https://prng.di.unimi.it/xoshiro256plusplus.c - public domain
+  u64(): bigint {
+    const result: bigint =
+      (RandImpl.rotl(
+        (this.randstate256[0] + this.randstate256[3]) & RandImpl.U64_MASK,
+        23n
+      ) +
+        this.randstate256[0]) &
+      RandImpl.U64_MASK;
+
+    const t: bigint = (this.randstate256[1] << 17n) & RandImpl.U64_MASK;
+
+    this.randstate256[2] ^= this.randstate256[0];
+    this.randstate256[3] ^= this.randstate256[1];
+    this.randstate256[1] ^= this.randstate256[2];
+    this.randstate256[0] ^= this.randstate256[3];
+
+    this.randstate256[2] ^= t;
+
+    this.randstate256[3] = RandImpl.rotl(this.randstate256[3], 45n);
+
+    return result;
+  }
+
+  static rotl(x: bigint, k: bigint): bigint {
+    return ((x << k) & RandImpl.U64_MASK) | (x >> (64n - k));
+  }
+
+  checkContext() {
+    const context = ContextImpl.callContext.getStore();
+    if (context && context.type === CallContexType.SideEffect) {
+      throw new TerminalError(
+        `You may not call methods on Rand from within a side effect.`,
+        { errorCode: ErrorCodes.INTERNAL }
+      );
+    }
+  }
+
+  static U53_MASK = (1n << 53n) - 1n;
+
+  public random(): number {
+    this.checkContext();
+
+    // first generate a uint in range [0,2^53), which can be mapped 1:1 to a float64 in [0,1)
+    const u53 = this.u64() & RandImpl.U53_MASK;
+    // then divide by 2^53, which will simply update the exponent
+    return Number(u53) / 2 ** 53;
+  }
+
+  public uuidv4(): string {
+    this.checkContext();
+
+    const buf = Buffer.alloc(16);
+    buf.writeBigUInt64LE(this.u64(), 0);
+    buf.writeBigUInt64LE(this.u64(), 8);
+    // Per 4.4, set bits for version and `clock_seq_hi_and_reserved`
+    buf[6] = (buf[6] & 0x0f) | 0x40;
+    buf[8] = (buf[8] & 0x3f) | 0x80;
+    return uuidStringify(buf);
+  }
+}
+
+const byteToHex: string[] = [];
+
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 0x100).toString(16).slice(1));
+}
+
+/**
+ * Convert array of 16 byte values to UUID string format of the form:
+ * XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+ */
+function uuidStringify(arr: Buffer, offset = 0) {
+  // Note: Be careful editing this code!  It's been tuned for performance
+  // and works in ways you may not expect. See https://github.com/uuidjs/uuid/pull/434
+  //
+  // Note to future-self: No, you can't remove the `toLowerCase()` call.
+  // REF: https://github.com/uuidjs/uuid/pull/677#issuecomment-1757351351
+  return (
+    byteToHex[arr[offset + 0]] +
+    byteToHex[arr[offset + 1]] +
+    byteToHex[arr[offset + 2]] +
+    byteToHex[arr[offset + 3]] +
+    "-" +
+    byteToHex[arr[offset + 4]] +
+    byteToHex[arr[offset + 5]] +
+    "-" +
+    byteToHex[arr[offset + 6]] +
+    byteToHex[arr[offset + 7]] +
+    "-" +
+    byteToHex[arr[offset + 8]] +
+    byteToHex[arr[offset + 9]] +
+    "-" +
+    byteToHex[arr[offset + 10]] +
+    byteToHex[arr[offset + 11]] +
+    byteToHex[arr[offset + 12]] +
+    byteToHex[arr[offset + 13]] +
+    byteToHex[arr[offset + 14]] +
+    byteToHex[arr[offset + 15]]
+  ).toLowerCase();
+}

package/src/utils/utils.ts

@@ -0,0 +1,178 @@
+/*
+ * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate SDK for Node.js/TypeScript,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in file LICENSE in the root
+ * directory of this repository or package, or at
+ * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  BackgroundInvokeEntryMessage,
+  ClearStateEntryMessage,
+  CompleteAwakeableEntryMessage,
+  GetStateEntryMessage,
+  InvokeEntryMessage,
+  OutputStreamEntryMessage,
+  SetStateEntryMessage,
+} from "../generated/proto/protocol";
+import {
+  AWAKEABLE_ENTRY_MESSAGE_TYPE,
+  BACKGROUND_INVOKE_ENTRY_MESSAGE_TYPE,
+  CLEAR_STATE_ENTRY_MESSAGE_TYPE,
+  COMPLETE_AWAKEABLE_ENTRY_MESSAGE_TYPE,
+  GET_STATE_ENTRY_MESSAGE_TYPE,
+  INVOKE_ENTRY_MESSAGE_TYPE,
+  OUTPUT_STREAM_ENTRY_MESSAGE_TYPE,
+  SET_STATE_ENTRY_MESSAGE_TYPE,
+  SIDE_EFFECT_ENTRY_MESSAGE_TYPE,
+  SLEEP_ENTRY_MESSAGE_TYPE,
+} from "../types/protocol";
+
+export function jsonSerialize(obj: any): string {
+  return JSON.stringify(obj, (_, v) =>
+    typeof v === "bigint" ? "BIGINT::" + v.toString() : v
+  );
+}
+
+export function jsonDeserialize<T>(json: string): T {
+  return JSON.parse(json, (_, v) =>
+    typeof v === "string" && v.startsWith("BIGINT::")
+      ? BigInt(v.substring(8))
+      : v
+  ) as T;
+}
+
+// When using google.protobuf.Value in RPC handler responses, we want to roughly match the behaviour of JSON.stringify
+// for example in converting Date objects to a UTC string
+export function jsonSafeAny(key: string, value: any): any {
+  if (
+    value !== undefined &&
+    value !== null &&
+    typeof value.toJSON == "function"
+  ) {
+    return value.toJSON(key) as any;
+  } else if (globalThis.Array.isArray(value)) {
+    // in place replace
+    value.forEach((_, i) => (value[i] = jsonSafeAny(i.toString(), value[i])));
+    return value;
+  } else if (typeof value === "object") {
+    Object.keys(value).forEach((key) => {
+      value[key] = jsonSafeAny(key, value[key]);
+    });
+    return value;
+  } else {
+    // primitive that doesn't have a toJSON method, with no children
+    return value;
+  }
+}
+
+export function formatMessageAsJson(obj: any): string {
+  const newObj = { ...(obj as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(newObj)) {
+    if (Buffer.isBuffer(value)) {
+      newObj[key] = value.toString().trim();
+    }
+  }
+  // Stringify object. Replace bigintToString serializer to prevent "BigInt not serializable" errors
+  return JSON.stringify(obj, (_, v) =>
+    typeof v === "bigint" ? v.toString() + "n" : v
+  );
+}
+
+/**
+ * Equality functions
+ * @param msg1 the current message from user code
+ * @param msg2 the replayed message
+ */
+// These functions are used to check whether a replayed message matches the current user code.
+// We check the fields which we can check
+// (the fields which do not contain results, because these might be filled in the result)
+
+const getStateMsgEquality = (
+  msg1: GetStateEntryMessage,
+  msg2: GetStateEntryMessage
+) => {
+  return msg1.key.equals(msg2.key);
+};
+
+const invokeMsgEquality = (
+  msg1: InvokeEntryMessage | BackgroundInvokeEntryMessage,
+  msg2: InvokeEntryMessage | BackgroundInvokeEntryMessage
+) => {
+  return (
+    msg1.serviceName === msg2.serviceName &&
+    msg1.methodName === msg2.methodName &&
+    msg1.parameter.equals(msg2.parameter)
+  );
+};
+
+const setStateMsgEquality = (
+  msg1: SetStateEntryMessage,
+  msg2: SetStateEntryMessage
+) => {
+  return msg1.key.equals(msg2.key) && msg1.value.equals(msg2.value);
+};
+
+const clearStateMsgEquality = (
+  msg1: ClearStateEntryMessage,
+  msg2: ClearStateEntryMessage
+) => {
+  return msg1.key.equals(msg2.key);
+};
+
+const completeAwakeableMsgEquality = (
+  msg1: CompleteAwakeableEntryMessage,
+  msg2: CompleteAwakeableEntryMessage
+) => {
+  if (!(msg1.id === msg2.id)) {
+    return false;
+  }
+
+  if (msg1.value && msg2.value) {
+    return msg1.value.equals(msg2.value);
+  } else if (msg1.failure && msg2.failure) {
+    return (
+      msg1.failure?.code === msg2.failure?.code &&
+      msg1.failure?.message === msg2.failure?.message
+    );
+  } else {
+    return false;
+  }
+};
+
+const outputMsgEquality = (
+  msg1: OutputStreamEntryMessage,
+  msg2: OutputStreamEntryMessage
+) => {
+  if (msg1.value && msg2.value) {
+    return msg1.value.equals(msg2.value);
+  } else if (msg1.failure && msg2.failure) {
+    return (
+      msg1.failure?.code === msg2.failure?.code &&
+      msg1.failure?.message === msg2.failure?.message
+    );
+  } else {
+    return false;
+  }
+};
+
+export const equalityCheckers = new Map<
+  bigint,
+  (msg1: any, msg2: any) => boolean
+>([
+  [GET_STATE_ENTRY_MESSAGE_TYPE, getStateMsgEquality],
+  [SET_STATE_ENTRY_MESSAGE_TYPE, setStateMsgEquality],
+  [CLEAR_STATE_ENTRY_MESSAGE_TYPE, clearStateMsgEquality],
+  [INVOKE_ENTRY_MESSAGE_TYPE, invokeMsgEquality],
+  [BACKGROUND_INVOKE_ENTRY_MESSAGE_TYPE, invokeMsgEquality],
+  [COMPLETE_AWAKEABLE_ENTRY_MESSAGE_TYPE, completeAwakeableMsgEquality],
+  [OUTPUT_STREAM_ENTRY_MESSAGE_TYPE, outputMsgEquality],
+  [AWAKEABLE_ENTRY_MESSAGE_TYPE, () => true],
+  [SIDE_EFFECT_ENTRY_MESSAGE_TYPE, () => true],
+  [SLEEP_ENTRY_MESSAGE_TYPE, () => true],
+]);

package/src/workflows/workflow.ts

@@ -0,0 +1,178 @@
+/*
+ * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate SDK for Node.js/TypeScript,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in file LICENSE in the root
+ * directory of this repository or package, or at
+ * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE
+ */
+
+import * as restate from "../public_api";
+import * as wws from "./workflow_wrapper_service";
+import * as wss from "./workflow_state_service";
+
+const STATE_SERVICE_PATH_SUFFIX = "_state";
+
+// ----------------------------------------------------------------------------
+//                    workflow definition / registration
+// ----------------------------------------------------------------------------
+
+/**
+ * Creates a new workflow service that will be served under the given path.
+ *
+ * A workflow must consist of
+ *   - one run method: `run(ctx: WfContext, params: T) => Promise<R>`
+ *   - an arbitrary number of interaction methods: `foo(ctx: SharedWfContext, params: X) => Promise<Y>`
+ */
+export function workflow<R, T, U>(
+  path: string,
+  workflow: Workflow<R, T, U>
+): WorkflowServices<R, T, U> {
+  // the state service manages all state and promises for us
+  const stateServiceRouter = wss.workflowStateService;
+  const stateServiceApi: restate.ServiceApi<wss.api> = {
+    path: path + STATE_SERVICE_PATH_SUFFIX,
+  };
+
+  // the wrapper service manages life cycle, contexts, delegation to the state service
+  const wrapperServiceRouter = wws.createWrapperService(
+    workflow,
+    path,
+    stateServiceApi
+  );
+
+  return {
+    api: { path } as restate.ServiceApi<WorkflowRestateRpcApi<R, T, U>>,
+    registerServices: (endpoint: restate.RestateEndpoint) => {
+      endpoint.bindKeyedRouter(stateServiceApi.path, stateServiceRouter);
+      endpoint.bindRouter(path, wrapperServiceRouter);
+    },
+  } satisfies WorkflowServices<R, T, U>;
+}
+
+/**
+ * The type signature of a workflow.
+ * A workflow must consist of
+ *   - one run method: `run(ctx: WfContext, params: T) => Promise<R>`
+ *   - an arbitrary number of interaction methods: `foo(ctx: SharedWfContext, params: T) => Promise<R>`
+ */
+export type Workflow<R, T, U> = {
+  run: RunMethod<R, T>;
+} & WorkflowMethods<R, T, U>;
+
+type RunMethod<R, T> = (ctx: WfContext, params: T) => Promise<R>;
+type InteractionMethod<R, T> = (ctx: SharedWfContext, params: T) => Promise<R>;
+
+type WorkflowMethods<R, T, U> = {
+  [K in keyof U]: K extends "run"
+    ? U[K] extends RunMethod<R, T>
+      ? U[K]
+      : "The 'run' methods needs to follow the signature: (ctx: WfContext, params: any) => Promise<any> "
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    U[K] extends InteractionMethod<any, any>
+    ? U[K]
+    : "Methods other than 'run' are interaction methods and need to follow the signature: (ctx: SharedWfContext, params: any) => Promise<any>";
+};
+
+/**
+ * The workflow service(s) and API.
+ *
+ * Register at a Restate endpoint (HTTP/2, Lambda, etc.) as follows:
+ * ```
+ * const myWorkflow = restate.workflows.workflow("org.acme.myworkflow", {
+ * // workflow implementation
+ * })
+ * restate.createServer().bind(myWorkflow)
+ * ```
+ *
+ * The {@link WorkflowServices.api} can be used to create typed clients, both
+ * from other Restate-backed serviced (e.g., `ctx.rpc(api).triggerMySignal()`)
+ * or from external clients (`clients.connectWorkflows(restateUri).connectToWorkflow(api, id);`).
+ */
+export interface WorkflowServices<R, T, U> extends restate.ServiceBundle {
+  readonly api: restate.ServiceApi<WorkflowRestateRpcApi<R, T, U>>;
+}
+
+// ----------------------------------------------------------------------------
+//                workflow-specific types (promises, contexts)
+// ----------------------------------------------------------------------------
+
+export type DurablePromise<T> = restate.CombineablePromise<T> & {
+  peek(): Promise<T | null>;
+
+  resolve(value?: T): void;
+  reject(errorMsg: string): void;
+};
+
+/**
+ * The context for the workflow's interaction methods, which are all methods
+ * other than the 'run()' method.
+ *
+ * This gives primarily access to state reads and promises.
+ */
+export interface SharedWfContext {
+  workflowId(): string;
+
+  get<T>(stateName: string): Promise<T | null>;
+
+  promise<T = void>(name: string): DurablePromise<T>;
+}
+
+/**
+ * The context for the workflow's 'run()' function.
+ *
+ * This is a full context as for stateful durable keyed services, plus the
+ * workflow-specific bits, like workflowID and durable promises.
+ */
+export interface WfContext extends SharedWfContext, restate.KeyedContext {}
+
+export enum LifecycleStatus {
+  NOT_STARTED = "NOT_STARTED",
+  RUNNING = "RUNNING",
+  FINISHED = "FINISHED",
+  FAILED = "FAILED",
+}
+
+export enum WorkflowStartResult {
+  STARTED = "STARTED",
+  ALREADY_STARTED = "ALREADY_STARTED",
+  ALREADY_FINISHED = "ALREADY_FINISHED",
+}
+
+// ----------------------------------------------------------------------------
+//                    types and signatures for typed clients
+// ----------------------------------------------------------------------------
+
+/**
+ * The type of requests accepted by the workflow service.
+ * Must contain the 'workflowId' property.
+ */
+export type WorkflowRequest<T> = T & { workflowId: string };
+
+/**
+ * The API signature of the workflow for use with RPC operations from Restate services.
+ */
+export type WorkflowRestateRpcApi<R, T, U> = {
+  start: (param: WorkflowRequest<T>) => Promise<WorkflowStartResult>;
+  waitForResult: (request: WorkflowRequest<unknown>) => Promise<R>;
+  status: (request: WorkflowRequest<unknown>) => Promise<LifecycleStatus>;
+} & {
+  [K in keyof Omit<U, "run">]: U[K] extends InteractionMethod<infer R, infer T>
+    ? (request: WorkflowRequest<T>) => Promise<R>
+    : never;
+};
+
+/**
+ * The API signature of the workflow for external clients.
+ */
+export type WorkflowClientApi<U> = {
+  [K in keyof Omit<U, "run">]: U[K] extends (
+    ctx: SharedWfContext
+  ) => Promise<infer R>
+    ? () => Promise<R>
+    : U[K] extends (ctx: SharedWfContext, params: infer T) => Promise<infer R>
+    ? (request: T) => Promise<R>
+    : never;
+};