@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/types/router.ts

@@ -0,0 +1,118 @@
+/*
+ * 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 { CombineablePromise, Context, KeyedContext } from "../context";
+import { Event } from "./types";
+
+// ----------- generics -------------------------------------------------------
+
+type WithKeyArgument<F> = F extends () => infer R ? (key: string) => R : F;
+
+type WithoutRpcContext<F> = F extends (
+  ctx: infer C extends Context,
+  ...args: infer P
+) => infer R
+  ? (...args: P) => R
+  : never;
+
+export type Client<M> = {
+  [K in keyof M as M[K] extends never ? never : K]: M[K] extends (
+    ...args: infer P
+  ) => PromiseLike<infer O>
+    ? (...args: P) => CombineablePromise<O>
+    : never;
+};
+
+export type SendClient<M> = {
+  [K in keyof M as M[K] extends never ? never : K]: M[K] extends (
+    ...args: infer P
+  ) => any
+    ? (...args: P) => void
+    : never;
+};
+
+// ----------- unkeyed handlers ----------------------------------------------
+
+export type UnKeyedHandler<F> = F extends (ctx: Context) => Promise<any>
+  ? F
+  : F extends (ctx: Context, input: any) => Promise<any>
+  ? F
+  : never;
+
+export type UnKeyedRouterOpts<U> = {
+  [K in keyof U]: U[K] extends UnKeyedHandler<any> ? U[K] : never;
+};
+
+export type UnKeyedRouter<U> = {
+  [K in keyof U]: U[K] extends UnKeyedHandler<infer F>
+    ? WithoutRpcContext<F>
+    : never;
+};
+
+export const router = <M>(opts: UnKeyedRouterOpts<M>): UnKeyedRouter<M> => {
+  if (opts === undefined || opts === null) {
+    throw new Error("router must be defined");
+  }
+  return opts as UnKeyedRouter<M>;
+};
+
+// ----------- keyed handlers ----------------------------------------------
+
+export type KeyedHandler<F> = F extends (ctx: KeyedContext) => Promise<any>
+  ? F
+  : F extends (ctx: KeyedContext, key: string, value: any) => Promise<any>
+  ? F
+  : never;
+
+export type KeyedRouterOpts<U> = {
+  [K in keyof U]: U[K] extends KeyedHandler<U[K]> | KeyedEventHandler<U[K]>
+    ? U[K]
+    : never;
+};
+
+export type KeyedRouter<U> = {
+  [K in keyof U]: U[K] extends KeyedEventHandler<U[K]>
+    ? never
+    : U[K] extends KeyedHandler<infer F>
+    ? WithKeyArgument<WithoutRpcContext<F>>
+    : never;
+};
+
+export const keyedRouter = <M>(opts: KeyedRouterOpts<M>): KeyedRouter<M> => {
+  if (opts === undefined || opts === null) {
+    throw new Error("router must be defined");
+  }
+  return opts as KeyedRouter<M>;
+};
+
+// ----------- event handlers ----------------------------------------------
+
+export type KeyedEventHandler<U> = U extends () => Promise<void>
+  ? never
+  : U extends (ctx: KeyedContext) => Promise<void>
+  ? never
+  : U extends (ctx: KeyedContext, event: Event) => Promise<void>
+  ? U
+  : never;
+
+export const keyedEventHandler = <H>(handler: KeyedEventHandler<H>): H => {
+  return { eventHandler: true, handler: handler } as H;
+};
+
+export const isEventHandler = (
+  handler: any
+): handler is {
+  handler: (ctx: KeyedContext, event: Event) => Promise<void>;
+} => {
+  return typeof handler === "object" && handler["eventHandler"];
+};

package/src/types/types.ts

@@ -0,0 +1,160 @@
+/*
+ * 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 {
+  AWAKEABLE_ENTRY_MESSAGE_TYPE,
+  COMPLETION_MESSAGE_TYPE,
+  ENTRY_ACK_MESSAGE_TYPE,
+  ERROR_MESSAGE_TYPE,
+  formatMessageType,
+  GET_STATE_ENTRY_MESSAGE_TYPE,
+  GET_STATE_KEYS_ENTRY_MESSAGE_TYPE,
+  KNOWN_MESSAGE_TYPES,
+  POLL_INPUT_STREAM_ENTRY_MESSAGE_TYPE,
+  PROTOBUF_MESSAGE_BY_TYPE,
+  ProtocolMessage,
+  SLEEP_ENTRY_MESSAGE_TYPE,
+  START_MESSAGE_TYPE,
+  SUSPENSION_MESSAGE_TYPE,
+} from "./protocol";
+
+export class Message {
+  constructor(
+    readonly messageType: bigint,
+    readonly message: ProtocolMessage,
+    readonly completed?: boolean,
+    readonly protocolVersion?: number,
+    readonly requiresAck?: boolean
+  ) {}
+
+  // For debugging purposes
+  toJSON(): unknown {
+    const pbType = PROTOBUF_MESSAGE_BY_TYPE.get(this.messageType);
+    if (pbType === undefined) {
+      return this;
+    }
+    return {
+      messageType: formatMessageType(this.messageType),
+      message: pbType.toJSON(this.message),
+    };
+  }
+}
+
+class MessageType {
+  static assertValid(messageTypeId: bigint) {
+    if (KNOWN_MESSAGE_TYPES.has(messageTypeId)) {
+      return;
+    }
+    if ((messageTypeId & CUSTOM_MESSAGE_MASK) !== 0n) {
+      return;
+    }
+    throw new Error(`Unknown message type ${messageTypeId}`);
+  }
+
+  static hasCompletedFlag(messageType: bigint): boolean {
+    return (
+      messageType === POLL_INPUT_STREAM_ENTRY_MESSAGE_TYPE ||
+      messageType === GET_STATE_ENTRY_MESSAGE_TYPE ||
+      messageType === GET_STATE_KEYS_ENTRY_MESSAGE_TYPE ||
+      messageType === SLEEP_ENTRY_MESSAGE_TYPE ||
+      messageType === AWAKEABLE_ENTRY_MESSAGE_TYPE
+    );
+  }
+
+  static hasProtocolVersion(messageType: bigint): boolean {
+    return messageType == START_MESSAGE_TYPE;
+  }
+
+  static hasRequiresAckFlag(messageType: bigint): boolean {
+    return (
+      messageType !== START_MESSAGE_TYPE &&
+      messageType !== ERROR_MESSAGE_TYPE &&
+      messageType !== SUSPENSION_MESSAGE_TYPE &&
+      messageType !== ENTRY_ACK_MESSAGE_TYPE &&
+      messageType !== COMPLETION_MESSAGE_TYPE
+    );
+  }
+}
+
+const CUSTOM_MESSAGE_MASK = BigInt(0xfc00);
+const COMPLETED_MASK = BigInt(0x0001_0000_0000);
+const VERSION_MASK = BigInt(0x03ff_0000_0000);
+const REQUIRES_ACK_MASK = BigInt(0x8000_0000_0000);
+
+// The header is exported but only for tests.
+export class Header {
+  constructor(
+    readonly messageType: bigint,
+    readonly frameLength: number,
+    readonly completedFlag?: boolean,
+    readonly protocolVersion?: number,
+    readonly requiresAckFlag?: boolean,
+    readonly partialStateFlag?: boolean
+  ) {}
+
+  public static fromU64be(value: bigint): Header {
+    const messageType: bigint = (value >> 48n) & 0xffffn;
+    MessageType.assertValid(messageType);
+
+    const completedFlag =
+      MessageType.hasCompletedFlag(messageType) &&
+      (value & COMPLETED_MASK) !== 0n
+        ? true
+        : undefined;
+    const protocolVersion = MessageType.hasProtocolVersion(messageType)
+      ? Number(((value & VERSION_MASK) >> 32n) & 0xffffn)
+      : undefined;
+    const requiresAckFlag =
+      MessageType.hasRequiresAckFlag(messageType) &&
+      (value & REQUIRES_ACK_MASK) !== 0n
+        ? true
+        : undefined;
+    const frameLength = Number(value & 0xffffffffn);
+
+    return new Header(
+      messageType,
+      frameLength,
+      completedFlag,
+      protocolVersion,
+      requiresAckFlag
+    );
+  }
+
+  public toU64be(): bigint {
+    let res = (this.messageType << 48n) | BigInt(this.frameLength);
+    if (this.completedFlag) {
+      res = res | COMPLETED_MASK;
+    }
+    if (this.protocolVersion !== undefined) {
+      res = res | (BigInt(this.protocolVersion) << 32n);
+    }
+    if (this.requiresAckFlag) {
+      res = res | REQUIRES_ACK_MASK;
+    }
+    return res;
+  }
+}
+
+export class Event {
+  constructor(
+    readonly key: string,
+    readonly payload: Buffer,
+    readonly attributes: Record<string, string>
+  ) {}
+
+  public json<T>(): T {
+    return JSON.parse(this.payload.toString("utf-8")) as T;
+  }
+
+  public body(): Uint8Array {
+    return this.payload;
+  }
+}

package/src/utils/assumptions.ts

@@ -0,0 +1,131 @@
+/*
+ * 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 { RpcRequest } from "../generated/proto/dynrpc";
+import { TerminalError } from "../types/errors";
+
+const ASSUME_UNKEYED_SINCE_FIRST_PARAM_NOT_STRING = 1;
+const ASSUME_UNKEYED_SINCE_ZERO_ARGS = 2;
+const ASSUME_KEYED_SINCE_TWO_ARGS_STR_AND_ANY = 3;
+const ASSUME_EITHER_KEYED_OR_UNKEYED_ONE_STR_ARG = 4;
+
+export const requestFromArgs = (args: unknown[]): RpcRequest => {
+  switch (args.length) {
+    case 0: {
+      return RpcRequest.create({
+        senderAssumes: ASSUME_UNKEYED_SINCE_ZERO_ARGS,
+      });
+    }
+    case 1: {
+      if (typeof args[0] === "string") {
+        return RpcRequest.create({
+          key: args[0],
+          senderAssumes: ASSUME_EITHER_KEYED_OR_UNKEYED_ONE_STR_ARG,
+        });
+      } else {
+        return RpcRequest.create({
+          request: args[0],
+          senderAssumes: ASSUME_UNKEYED_SINCE_FIRST_PARAM_NOT_STRING,
+        });
+      }
+    }
+    case 2: {
+      if (typeof args[0] !== "string") {
+        throw new TerminalError(
+          `Two argument handlers are only possible for keyed handlers. Where the first argument must be of type 'string'.`
+        );
+      }
+      return RpcRequest.create({
+        key: args[0],
+        request: args[1],
+        senderAssumes: ASSUME_KEYED_SINCE_TWO_ARGS_STR_AND_ANY,
+      });
+    }
+    default: {
+      throw new TerminalError("wrong number of arguments " + args.length);
+    }
+  }
+};
+
+/* eslint-disable @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any */
+export type JsType =
+  | string
+  | number
+  | boolean
+  | Object
+  | null
+  | Array<any>
+  | undefined;
+/* eslint-enable @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any */
+
+const requireThat = (condition: boolean, errorMessage: string) => {
+  if (!condition) {
+    throw new TerminalError(errorMessage);
+  }
+};
+
+export const verifyAssumptions = (
+  isKeyed: boolean,
+  request: RpcRequest
+): { key?: string; request?: JsType } => {
+  const assumption = request.senderAssumes ?? 0;
+  switch (assumption) {
+    case 0: {
+      // no assumption: this comes from an ingress.
+      const hasKeyProperty =
+        typeof request.key === "string" && request.key.length > 0;
+      if (isKeyed) {
+        requireThat(
+          hasKeyProperty,
+          "Trying to call a keyed handler with a missing or empty 'key' property."
+        );
+      } else {
+        requireThat(
+          !hasKeyProperty,
+          "Trying to call a an unkeyed handler with a 'key' property. Did you mean using the 'request' property instead?"
+        );
+      }
+      return { key: request.key, request: request.request };
+    }
+    case ASSUME_UNKEYED_SINCE_FIRST_PARAM_NOT_STRING: {
+      requireThat(
+        !isKeyed,
+        "Trying to call a keyed handler with a missing key. This could happen if the first argument passed is not a 'string'."
+      );
+      return { request: request.request };
+    }
+    case ASSUME_UNKEYED_SINCE_ZERO_ARGS: {
+      requireThat(
+        !isKeyed,
+        "A keyed handler must at least be invoked with a single non empty string argument, that represents the key. 0 arguments given."
+      );
+      return { request: request.request };
+    }
+    case ASSUME_KEYED_SINCE_TWO_ARGS_STR_AND_ANY: {
+      requireThat(
+        isKeyed,
+        "An unkeyed handler must have at most 1 argument. two given."
+      );
+      return { key: request.key, request: request.request };
+    }
+    case ASSUME_EITHER_KEYED_OR_UNKEYED_ONE_STR_ARG: {
+      if (isKeyed) {
+        return { key: request.key };
+      }
+      return { request: request.key };
+    }
+    default: {
+      throw new TerminalError(
+        `Unknown assumption id ${assumption}. This indicates an incorrect (or involuntary) setting of the assumption property at the ingress request, or an SDK bug.`
+      );
+    }
+  }
+};

package/src/utils/message_logger.ts

@@ -0,0 +1,112 @@
+/*
+ * 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 */
+/* eslint-disable no-console */
+
+import { formatMessageType } from "../types/protocol";
+import { formatMessageAsJson } from "./utils";
+import { createRestateConsole, LoggerContext } from "../logger";
+
+/**
+ * The environment variable which is read to determine the debug log settings.
+ */
+export const DEBUG_LOGGING_ENV = "RESTATE_DEBUG_LOGGING";
+
+/**
+ * The values for the {@link DEBUG_LOGGING_ENV} variable.
+ */
+export enum RestateDebugLogLevel {
+  /** No debug logging at all. Good for performance and avoid per-invocation log volume */
+  OFF,
+
+  /** Logs debug information for every Restate function invocation. */
+  INVOKE,
+
+  /** Logs debug information for every Restate effect (=journal event) inside an invocation,
+   *  like RPC, state access, sideEffect, ... */
+  JOURNAL,
+
+  /** Logs debug information for every Restate effect (=journal event) inside an invocation,
+   *  like RPC, state access, sideEffect, ... Additionally, this adds a JSON representation
+   *  of the journal message to the log. */
+  JOURNAL_VERBOSE,
+}
+
+const DEFAULT_DEBUG_LOG_LEVEL =
+  process.env["NODE_ENV"]?.toUpperCase() === "PRODUCTION"
+    ? RestateDebugLogLevel.OFF
+    : RestateDebugLogLevel.INVOKE;
+
+function readLogLevel(): RestateDebugLogLevel {
+  const env = process.env[DEBUG_LOGGING_ENV]?.toUpperCase();
+  if (env == undefined) {
+    return DEFAULT_DEBUG_LOG_LEVEL;
+  }
+  const idx = Object.keys(RestateDebugLogLevel)
+    .filter((t) =>
+      // Object.keys contains the numbers as well
+      // https://stackoverflow.com/questions/48768774/how-to-get-all-the-values-of-an-enum-with-typescript
+      isNaN(Number(t))
+    )
+    .findIndex((level) => level == env);
+  if (idx < 0) {
+    return DEFAULT_DEBUG_LOG_LEVEL;
+  }
+
+  return idx;
+}
+
+const log_level = readLogLevel();
+
+export type StateMachineConsole = Console & {
+  debugInvokeMessage: (msg: string) => void;
+
+  debugJournalMessage: (
+    logMessage: string,
+    messageType?: bigint,
+    message?: any
+  ) => void;
+};
+
+export function createStateMachineConsole(
+  context: LoggerContext
+): StateMachineConsole {
+  const console = createRestateConsole(context);
+
+  Object.defineProperties(console, {
+    debugInvokeMessage: {
+      value: (msg: string) => {
+        if (log_level >= RestateDebugLogLevel.INVOKE) {
+          console.debug(msg);
+        }
+      },
+    },
+    debugJournalMessage: {
+      value: (logMessage: string, messageType?: bigint, message?: any) => {
+        if (log_level >= RestateDebugLogLevel.JOURNAL) {
+          const type =
+            messageType !== undefined
+              ? " ; " + formatMessageType(messageType)
+              : "";
+          const journalEvent =
+            log_level >= RestateDebugLogLevel.JOURNAL_VERBOSE &&
+            message !== undefined
+              ? " : " + formatMessageAsJson(message)
+              : "";
+          console.debug(`${logMessage}${type}${journalEvent}`);
+        }
+      },
+    },
+  });
+
+  return console as StateMachineConsole;
+}

package/src/utils/promises.ts

@@ -0,0 +1,118 @@
+/*
+ * 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
+ */
+
+// -- Wrapped promise
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type WrappedPromise<T> = Promise<T> & {
+  // The reason for this transform is that we want to retain the wrapping.
+  // When working with WrappedPromise you MUST use this method instead of then for mapping the promise results.
+  transform: <TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined
+  ) => WrappedPromise<TResult1 | TResult2>;
+};
+
+export function wrapDeeply<T>(
+  promise: Promise<T>,
+  onThen?: () => void
+): WrappedPromise<T> {
+  // We need this to support nesting of WrappedPromise
+  let transform: <TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined
+  ) => WrappedPromise<TResult1 | TResult2>;
+  if (Object.hasOwn(promise, "transform")) {
+    const wrappedPromise = promise as WrappedPromise<T>;
+    transform = (onfulfilled, onrejected) =>
+      wrapDeeply(wrappedPromise.transform(onfulfilled, onrejected), onThen);
+  } else {
+    transform = (onfulfilled, onrejected) =>
+      wrapDeeply(promise.then(onfulfilled, onrejected), onThen);
+  }
+
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  return {
+    transform,
+
+    then: function <TResult1 = T, TResult2 = never>(
+      onfulfilled?:
+        | ((value: T) => TResult1 | PromiseLike<TResult1>)
+        | null
+        | undefined,
+      onrejected?:
+        | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+        | null
+        | undefined
+    ): Promise<TResult1 | TResult2> {
+      if (onThen !== undefined) {
+        onThen();
+      }
+      return promise.then(onfulfilled, onrejected);
+    },
+    catch: function <TResult = never>(
+      onrejected?:
+        | ((reason: any) => TResult | PromiseLike<TResult>)
+        | null
+        | undefined
+    ): Promise<T | TResult> {
+      return wrapDeeply(promise.catch(onrejected), onThen);
+    },
+    finally: function (
+      onfinally?: (() => void) | null | undefined
+    ): Promise<T> {
+      return wrapDeeply(promise.finally(onfinally), onThen);
+    },
+    [Symbol.toStringTag]: "",
+  };
+}
+
+// Like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
+// (not yet available in node)
+export class CompletablePromise<T> {
+  private success!: (value: T | PromiseLike<T>) => void;
+  private failure!: (reason?: any) => void;
+
+  public readonly promise: Promise<T>;
+
+  constructor() {
+    this.promise = new Promise((resolve, reject) => {
+      this.success = resolve;
+      this.failure = reject;
+    });
+  }
+
+  public resolve(value: T) {
+    this.success(value);
+  }
+
+  public reject(reason?: any) {
+    this.failure(reason);
+  }
+}
+
+// A promise that is never completed
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export const PROMISE_PENDING: Promise<any> = new Promise<any>(() => {});
+export const WRAPPED_PROMISE_PENDING: Promise<any> =
+  wrapDeeply(PROMISE_PENDING);