@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/logger.ts

@@ -0,0 +1,121 @@
+/*
+ * 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 */
+
+export class LoggerContext {
+  readonly fqMethodName: string;
+
+  constructor(
+    readonly invocationId: string,
+    packageName: string,
+    serviceName: string,
+    methodName: string,
+    readonly additionalContext?: { [name: string]: string }
+  ) {
+    this.fqMethodName = packageName
+      ? `${packageName}.${serviceName}/${methodName}`
+      : `${serviceName}/${methodName}`;
+  }
+}
+
+function formatLogPrefix(context?: LoggerContext): string {
+  if (context === undefined) {
+    return "[restate] ";
+  }
+  let prefix = `[restate] [${context.fqMethodName}][${context.invocationId}]`;
+  if (context.additionalContext !== undefined) {
+    for (const [k, v] of Object.entries(context.additionalContext)) {
+      prefix = prefix + `[${k}: ${v}]`;
+    }
+  }
+  return prefix;
+}
+
+export function createRestateConsole(
+  context?: LoggerContext,
+  filter?: () => boolean
+): Console {
+  const prefix = formatLogPrefix(context);
+  const restate_logger = Object.create(console);
+
+  const shouldLog: () => boolean = filter ?? (() => true);
+
+  restate_logger.log = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.log(
+      prefix + `[${new Date().toISOString()}] LOG: ` + message,
+      ...optionalParams
+    );
+  };
+
+  restate_logger.info = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.info(
+      prefix + `[${new Date().toISOString()}] INFO: ` + message,
+      ...optionalParams
+    );
+  };
+
+  restate_logger.warn = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.warn(
+      prefix + `[${new Date().toISOString()}] WARN: ` + message,
+      ...optionalParams
+    );
+  };
+
+  restate_logger.error = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.error(
+      prefix + `[${new Date().toISOString()}] ERROR: ` + message,
+      ...optionalParams
+    );
+  };
+
+  restate_logger.debug = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.debug(
+      prefix + `[${new Date().toISOString()}] DEBUG: ` + message,
+      ...optionalParams
+    );
+  };
+
+  restate_logger.trace = (message?: any, ...optionalParams: any[]) => {
+    if (!shouldLog()) {
+      return;
+    }
+    console.trace(
+      prefix + `[${new Date().toISOString()}] TRACE: ` + message,
+      ...optionalParams
+    );
+  };
+
+  return restate_logger;
+}
+
+/**
+ * This is a simple console without contextual info.
+ *
+ * This should be used only in cases where no contextual info is available.
+ */
+export const rlog = createRestateConsole();

package/src/promise_combinator_tracker.ts

@@ -0,0 +1,191 @@
+import {
+  CompletablePromise,
+  wrapDeeply,
+  WrappedPromise,
+} from "./utils/promises";
+
+export enum PromiseType {
+  JournalEntry,
+  // Combinator?,
+  // SideEffect?
+}
+
+export interface PromiseId {
+  type: PromiseType;
+  id: number;
+}
+
+export function newJournalEntryPromiseId(entryIndex: number): PromiseId {
+  return {
+    type: PromiseType.JournalEntry,
+    id: entryIndex,
+  };
+}
+
+/**
+ * Prepare a Promise combinator
+ *
+ * @param combinatorIndex the index of this combinator
+ * @param combinatorConstructor the function that creates the combinator promise, e.g. Promise.all/any/race/allSettled
+ * @param promises the promises given by the user, and the respective ids
+ * @param readReplayOrder the function to read the replay order
+ * @param onNewCompleted callback when a child entry is resolved
+ * @param onCombinatorResolved callback when the combinator is resolved
+ * @param onCombinatorReplayed callback when the combinator is replayed
+ */
+function preparePromiseCombinator(
+  combinatorIndex: number,
+  combinatorConstructor: (promises: PromiseLike<unknown>[]) => Promise<unknown>,
+  promises: Array<{ id: PromiseId; promise: Promise<unknown> }>,
+  readReplayOrder: (combinatorIndex: number) => PromiseId[] | undefined,
+  onNewCompleted: (combinatorIndex: number, promiseId: PromiseId) => void,
+  onCombinatorResolved: (combinatorIndex: number) => Promise<void>,
+  onCombinatorReplayed: (combinatorIndex: number) => void
+): WrappedPromise<unknown> {
+  // Create the proxy promises and index them
+  const promisesWithProxyPromise = promises.map((v) => ({
+    id: v.id,
+    originalPromise: v.promise,
+    proxyPromise: new CompletablePromise<unknown>(),
+  }));
+  const promisesMap = new Map(
+    promisesWithProxyPromise.map((v) => [
+      // We need to define a key format for this map...
+      v.id.type.toString() + "-" + v.id.id.toString(),
+      { originalPromise: v.originalPromise, proxyPromise: v.proxyPromise },
+    ])
+  );
+
+  // Create the combinator using the proxy promises
+  const combinator = combinatorConstructor(
+    promisesWithProxyPromise.map((v) => v.proxyPromise.promise)
+  ).finally(
+    async () =>
+      // Once the combinator is resolved, notify back.
+      await onCombinatorResolved(combinatorIndex)
+  );
+
+  return wrapDeeply(combinator, () => {
+    const replayOrder = readReplayOrder(combinatorIndex);
+
+    if (replayOrder === undefined) {
+      // We're in processing mode! We need to wire up original promises with proxy promises
+      for (const {
+        originalPromise,
+        proxyPromise,
+        id,
+      } of promisesWithProxyPromise) {
+        originalPromise
+          // This code works deterministically because the javascript runtime will enqueue
+          // the listeners of the proxy promise (which are mounted in Promise.all/any) in a single FIFO queue,
+          // so a subsequent resolve on another proxy promise can't overtake this one.
+          //
+          // Some resources:
+          // * https://stackoverflow.com/questions/38059284/why-does-javascript-promise-then-handler-run-after-other-code
+          // * https://262.ecma-international.org/6.0/#sec-jobs-and-job-queues
+          // * https://tr.javascript.info/microtask-queue
+          .then(
+            (v) => {
+              onNewCompleted(combinatorIndex, id);
+              proxyPromise.resolve(v);
+            },
+            (e) => {
+              onNewCompleted(combinatorIndex, id);
+              proxyPromise.reject(e);
+            }
+          );
+      }
+      return;
+    }
+
+    // We're in replay mode, Now follow the replayIndexes order.
+    onCombinatorReplayed(combinatorIndex);
+    for (const promiseId of replayOrder) {
+      // These are already completed, so once we set the then callback they will be immediately resolved.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const { originalPromise, proxyPromise } = promisesMap.get(
+        promiseId.type.toString() + "-" + promiseId.id.toString()
+      )!;
+
+      // Because this promise is already completed, promise.then will immediately enqueue in the promise microtask queue
+      // the handlers to execute.
+      // See the comment below for more details.
+      originalPromise.then(
+        (v) => proxyPromise.resolve(v),
+        (e) => proxyPromise.reject(e)
+      );
+    }
+  });
+}
+
+/**
+ * This class takes care of creating and managing deterministic promise combinators.
+ *
+ * It should be wired up to the journal/state machine methods to read and write entries.
+ */
+export class PromiseCombinatorTracker {
+  private nextCombinatorIndex = 0;
+  private pendingCombinators: Map<number, PromiseId[]> = new Map();
+
+  constructor(
+    private readonly readReplayOrder: (
+      combinatorIndex: number
+    ) => PromiseId[] | undefined,
+    private readonly onWriteCombinatorOrder: (
+      combinatorIndex: number,
+      order: PromiseId[]
+    ) => Promise<void>
+  ) {}
+
+  public createCombinator(
+    combinatorConstructor: (
+      promises: PromiseLike<unknown>[]
+    ) => Promise<unknown>,
+    promises: Array<{ id: PromiseId; promise: Promise<unknown> }>
+  ): WrappedPromise<unknown> {
+    const combinatorIndex = this.nextCombinatorIndex;
+    this.nextCombinatorIndex++;
+
+    // Prepare combinator order
+    this.pendingCombinators.set(combinatorIndex, []);
+
+    return preparePromiseCombinator(
+      combinatorIndex,
+      combinatorConstructor,
+      promises,
+      this.readReplayOrder,
+      this.appendOrder.bind(this),
+      this.onCombinatorResolved.bind(this),
+      this.onCombinatorReplayed.bind(this)
+    );
+  }
+
+  private appendOrder(idx: number, promiseId: PromiseId) {
+    const order = this.pendingCombinators.get(idx);
+    if (order === undefined) {
+      // The order was already published, nothing to do here.
+      return;
+    }
+
+    order.push(promiseId);
+  }
+
+  private onCombinatorReplayed(idx: number) {
+    // This avoids republishing the order
+    this.pendingCombinators.delete(idx);
+  }
+
+  private async onCombinatorResolved(idx: number) {
+    const order = this.pendingCombinators.get(idx);
+    if (order === undefined) {
+      // It was already published
+      return;
+    }
+
+    // We don't need this list anymore.
+    this.pendingCombinators.delete(idx);
+
+    // Publish the combinator order
+    await this.onWriteCombinatorOrder(idx, order);
+  }
+}

package/src/public_api.ts

@@ -0,0 +1,53 @@
+/*
+ * 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
+ */
+
+export {
+  RestateContext,
+  Context,
+  KeyedContext,
+  useContext,
+  useKeyedContext,
+  ServiceApi,
+  CombineablePromise,
+  Rand,
+  RestateGrpcChannel,
+} from "./context";
+export {
+  router,
+  keyedRouter,
+  keyedEventHandler,
+  UnKeyedRouter,
+  KeyedRouter,
+  KeyedEventHandler,
+  Client,
+  SendClient,
+} from "./types/router";
+export {
+  endpoint,
+  ServiceBundle,
+  ServiceOpts,
+  RestateEndpoint,
+} from "./endpoint";
+export * as RestateUtils from "./utils/public_utils";
+export {
+  ErrorCodes,
+  RestateError,
+  TerminalError,
+  TimeoutError,
+} from "./types/errors";
+export { Event } from "./types/types";
+export {
+  RestateConnection,
+  connection,
+  RestateConnectionOptions,
+} from "./embedded/api";
+export * as workflow from "./workflows/workflow";
+export * as clients from "./clients/workflow_client";