@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/clients/workflow_client.ts

@@ -0,0 +1,290 @@
+/*
+ * 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 { ensureError } from "../types/errors";
+
+/**
+ * A client to interact with running workflows.
+ */
+export interface WorkflowClient<R, U> {
+  /**
+   * Gets the ID of the workflow that this client talks to.
+   */
+  workflowId(): string;
+
+  /**
+   * Gets the status of the workflow, as a {@link restate.workflow.LifecycleStatus}.
+   * This will take on the values "NOT_STARTED", "RUNNING", "FINISHED", "FAILED".
+   */
+  status(): Promise<restate.workflow.LifecycleStatus>;
+
+  /**
+   * Returns a promise completed with the result. This will resolve successfully on successful
+   * termination of the workflow, and will be rejected if the workflow throws an Error.
+   */
+  result(): Promise<R>;
+
+  /**
+   * Gets the interface to the workflow through which all the workflow's additional methods
+   * can be called.
+   *
+   * To get the proper typed client, use the {@link WorkflowConnection.submitWorkflow} or
+   * {@link WorkflowConnection.connectToWorkflow} functions that accpet a typed ServiceApi
+   * object, as in the example below.
+   *
+   * @example
+   * In the workflow definition:
+   * ```
+   * const myWorkflow = restate.workflow.workflow("acme.myworkflow", { ... });
+   * export const myWorkflowApi = myworkflow.api;
+   * ```
+   * In the client code:
+   * ```
+   * import { myWorkflowApi } from "../server/myWorkflow"
+   * ...
+   * const restate = connectWorkflows("https://restatehost:8080");
+   * restate.submitWorkflow(myWorkflowApi, workflowId, args);
+   * restate.connectToWorkflow(myWorkflowApi, workflowId);
+   * ```
+   */
+  workflowInterface(): restate.Client<restate.workflow.WorkflowClientApi<U>>;
+}
+
+/**
+ * A connection to Restate that let's you submit workflows or connect to workflows.
+ * This is a typed client that internally makes HTTP calls to Restate to launch trigger
+ * an execution of a workflow service, or to connect to an existing execution.
+ */
+export interface RestateClient {
+  submitWorkflow<R, T>(
+    path: string,
+    workflowId: string,
+    params: T
+  ): Promise<{
+    status: restate.workflow.WorkflowStartResult;
+    client: WorkflowClient<R, unknown>;
+  }>;
+
+  submitWorkflow<R, T, U>(
+    workflowApi: restate.ServiceApi<
+      restate.workflow.WorkflowRestateRpcApi<R, T, U>
+    >,
+    workflowId: string,
+    params: T
+  ): Promise<{
+    status: restate.workflow.WorkflowStartResult;
+    client: WorkflowClient<R, U>;
+  }>;
+
+  connectToWorkflow<R = unknown>(
+    path: string,
+    workflowId: string
+  ): Promise<{
+    status: restate.workflow.LifecycleStatus;
+    client: WorkflowClient<R, unknown>;
+  }>;
+
+  connectToWorkflow<R, T, U>(
+    workflowApi: restate.ServiceApi<
+      restate.workflow.WorkflowRestateRpcApi<R, T, U>
+    >,
+    workflowId: string
+  ): Promise<{
+    status: restate.workflow.LifecycleStatus;
+    client: WorkflowClient<R, U>;
+  }>;
+}
+
+/**
+ * Creates a typed client to start and interact with workflow executions.
+ * The specifiec URI must point to the Restate request endpoint (ingress).
+ *
+ * This function doesn't immediately verify the connection, it will not fail
+ * if Restate is unreachable. Connection failures will only manifest when
+ * attempting to submit or connect a specific workflow.
+ */
+export function connect(restateUri: string): RestateClient {
+  return {
+    submitWorkflow: async <R, T, U>(
+      pathOrApi:
+        | string
+        | restate.ServiceApi<restate.workflow.WorkflowRestateRpcApi<R, T, U>>,
+      workflowId: string,
+      params: T
+    ): Promise<{
+      status: restate.workflow.WorkflowStartResult;
+      client: WorkflowClient<R, U>;
+    }> => {
+      const path = typeof pathOrApi === "string" ? pathOrApi : pathOrApi.path;
+
+      let result: restate.workflow.WorkflowStartResult;
+      try {
+        result = await makeCall(restateUri, path, "submit", workflowId, params);
+      } catch (err) {
+        const error = ensureError(err);
+        throw new Error("Cannot start workflow: " + error.message, {
+          cause: error,
+        });
+      }
+
+      return {
+        status: result,
+        client: new WorkflowClientImpl(restateUri, path, workflowId),
+      };
+    },
+
+    async connectToWorkflow<R, T, U>(
+      pathOrApi:
+        | string
+        | restate.ServiceApi<restate.workflow.WorkflowRestateRpcApi<R, T, U>>,
+      workflowId: string
+    ): Promise<{
+      status: restate.workflow.LifecycleStatus;
+      client: WorkflowClient<R, U>;
+    }> {
+      const path = typeof pathOrApi === "string" ? pathOrApi : pathOrApi.path;
+      const client: WorkflowClient<R, U> = new WorkflowClientImpl(
+        restateUri,
+        path,
+        workflowId
+      );
+      const status = await client.status();
+      if (status === restate.workflow.LifecycleStatus.NOT_STARTED) {
+        throw new Error(
+          "No workflow running/finished/failed with ID " + workflowId
+        );
+      }
+      return {
+        status,
+        client: new WorkflowClientImpl(restateUri, path, workflowId),
+      };
+    },
+  } satisfies RestateClient;
+}
+
+class WorkflowClientImpl<R, U> implements WorkflowClient<R, U> {
+  constructor(
+    private readonly restateUri: string,
+    private readonly serviceName: string,
+    private readonly wfId: string
+  ) {}
+
+  workflowId(): string {
+    return this.wfId;
+  }
+
+  status(): Promise<restate.workflow.LifecycleStatus> {
+    return this.makeCall("status", {});
+  }
+
+  result(): Promise<R> {
+    return this.makeCall("waitForResult", {});
+  }
+
+  workflowInterface(): restate.Client<restate.workflow.WorkflowClientApi<U>> {
+    const clientProxy = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          const method = prop as string;
+          return async (args: unknown) => {
+            return this.makeCall(method, args);
+          };
+        },
+      }
+    );
+
+    return clientProxy as restate.Client<restate.workflow.WorkflowClientApi<U>>;
+  }
+
+  private async makeCall<RR, TT>(method: string, args: TT): Promise<RR> {
+    return await makeCall(
+      this.restateUri,
+      this.serviceName,
+      method,
+      this.wfId,
+      args
+    );
+  }
+}
+
+// ----------------------------------------------------------------------------
+//                                 Utils
+// ----------------------------------------------------------------------------
+
+async function makeCall<R, T>(
+  restateUri: string,
+  serviceName: string,
+  method: string,
+  workflowId: string,
+  params: T
+): Promise<R> {
+  if (!workflowId || typeof workflowId !== "string") {
+    throw new Error("missing workflowId");
+  }
+  if (params === undefined) {
+    params = {} as T;
+  }
+  if (typeof params !== "object") {
+    throw new Error("invalid parameters: must be an object");
+  }
+
+  const url = `${restateUri}/${serviceName}/${method}`;
+  const data = {
+    request: {
+      workflowId,
+      ...params,
+    } satisfies restate.workflow.WorkflowRequest<T>,
+  };
+
+  let body: string;
+  try {
+    body = JSON.stringify(data);
+  } catch (err) {
+    throw new Error("Cannot encode request: " + err, { cause: err });
+  }
+
+  // eslint-disable-next-line no-console
+  console.debug(`Making call to Restate at ${url}`);
+
+  const httpResponse = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body,
+  });
+
+  const responseText = await httpResponse.text();
+  if (!httpResponse.ok) {
+    throw new Error(`Request failed: ${httpResponse.status}\n${responseText}`);
+  }
+
+  let response;
+  try {
+    response = JSON.parse(responseText);
+  } catch (err) {
+    throw new Error("Cannot parse response JSON: " + err, { cause: err });
+  }
+
+  if (response.error) {
+    throw new Error(response.error);
+  }
+  if (response.response) {
+    return response.response as R;
+  }
+  if (Object.keys(response).length === 0) {
+    return undefined as R;
+  }
+
+  throw new Error("Unrecognized response object: " + responseText);
+}

package/src/connection/buffered_connection.ts

@@ -0,0 +1,47 @@
+import { encodeMessages } from "../io/encoder";
+import { Message } from "../types/types";
+import { Connection } from "./connection";
+
+export class BufferedConnection implements Connection {
+  private queue: Message[] = [];
+  private flushing: Promise<void> = Promise.resolve();
+
+  constructor(private readonly flushFn: (buffer: Buffer) => Promise<void>) {}
+
+  send(msg: Message): Promise<void> {
+    const len = this.queue.push(msg);
+    if (len === 1) {
+      // we are the first in line, therefore we schedule a flush,
+      // BUT we must wait for the previous flush to end.
+      this.flushing = this.flushing.then(() => this.scheduleFlush());
+    }
+    // we don't need to reschedule the `flush` here,
+    // because the flush happens anyway at the end of the current event loop iteration.
+    // tag along to the previously scheduled flush.
+    return this.flushing;
+  }
+
+  end(): Promise<void> {
+    this.flushing = this.flushing.then(() => this.flush());
+    return this.flushing;
+  }
+
+  private scheduleFlush(): Promise<void> {
+    // schedule a flush at the end of the current event loop iteration.
+    return new Promise((resolve, reject) =>
+      setImmediate(() => {
+        this.flush().then(resolve).catch(reject);
+      })
+    );
+  }
+
+  private async flush(): Promise<void> {
+    if (this.queue.length === 0) {
+      return Promise.resolve();
+    }
+    const buffer = encodeMessages(this.queue) as Buffer;
+    this.queue = [];
+
+    return this.flushFn(buffer);
+  }
+}

package/src/connection/connection.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 { Message } from "../types/types";
+
+/**
+ * A connection from the service/SDK to Restate.
+ * Accepts messages to be sent and committed to the journal.
+ */
+export interface Connection {
+  send(msg: Message): Promise<void>;
+
+  end(): Promise<void>;
+}
+
+/**
+ * A consumer of a message stream from Restate.
+ * Messages include journal replay messages and completion messages.
+ */
+export interface RestateStreamConsumer {
+  handleMessage(m: Message): boolean;
+
+  handleStreamError(e: Error): void;
+
+  handleInputClosed(): void;
+}

package/src/connection/embedded_connection.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 { RemoteContext } from "../generated/proto/services";
+import { Message } from "../types/types";
+import { BufferedConnection } from "./buffered_connection";
+import { Connection } from "./connection";
+
+export class FencedOffError extends Error {
+  constructor() {
+    super("FencedOff");
+  }
+}
+
+export class InvocationAlreadyCompletedError extends Error {
+  constructor() {
+    super("Completed");
+  }
+}
+
+export class EmbeddedConnection implements Connection {
+  private buffered: BufferedConnection;
+
+  constructor(
+    private readonly operationId: string,
+    private readonly streamId: string,
+    private readonly remote: RemoteContext
+  ) {
+    this.buffered = new BufferedConnection((buffer) => this.sendBuffer(buffer));
+  }
+
+  send(msg: Message): Promise<void> {
+    return this.buffered.send(msg);
+  }
+
+  end(): Promise<void> {
+    return this.buffered.end();
+  }
+
+  private async sendBuffer(buffer: Buffer): Promise<void> {
+    const res = await this.remote.send({
+      operationId: this.operationId,
+      streamId: this.streamId,
+      messages: buffer,
+    });
+
+    if (res.invalidStream !== undefined) {
+      throw new FencedOffError();
+    }
+    if (res.invocationCompleted !== undefined) {
+      throw new InvocationAlreadyCompletedError();
+    }
+  }
+}

package/src/connection/http_connection.ts

@@ -0,0 +1,228 @@
+/*
+ * 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 stream from "stream";
+import { streamDecoder } from "../io/decoder";
+import { Connection, RestateStreamConsumer } from "./connection";
+import { Message } from "../types/types";
+import { rlog } from "../logger";
+import { finished } from "stream/promises";
+import { BufferedConnection } from "./buffered_connection";
+
+// utility promise, for cases where we want to save allocation of an extra promise
+const RESOLVED: Promise<void> = Promise.resolve();
+
+/**
+ * A duplex stream with Restate Messages over HTTP2.
+ *
+ * This stream handles the following concerns:
+ *
+ * (1) encoding and decoding of messages from  and from raw bytes
+ *
+ * (2) buffering the outgoing messages, because the call sites that produce (potentially) large
+ *     messages might not await their transfer. Aside from the fact that we achieve better pipelining
+ *     that way, we also simply cannot guarantee that users of the Restate SDK actually await the
+ *     relevant async API methods.
+ *
+ *     This stream essentially buffers messages and, upon flush, sends them asynchronously, as the
+ *     stream has availability. Flush requests queue up, if new data gets flushed while the previous
+ *     data is still being sent.
+ *
+ * (3) Input messages can be pipelined to a sequence of consumers. For example, first to a journal,
+ *     and afterwards to the state machine.
+ *
+ * (4) Handling the relevant stream events for errors and consolidating them to one error handler, plus
+ *     notifications for cleanly closed input (to trigger suspension).
+ */
+export class RestateHttp2Connection implements Connection {
+  /**
+   * create a RestateDuplex stream from an http2 (duplex) stream.
+   */
+  public static from(http2stream: stream.Duplex): RestateHttp2Connection {
+    return new RestateHttp2Connection(http2stream);
+  }
+
+  // --------------------------------------------------------------------------
+
+  // input as decoded messages
+  private readonly sdkInput: stream.Readable;
+
+  // consumer handling
+  private currentConsumer: RestateStreamConsumer | null = null;
+  private inputBuffer: Message[] = [];
+  private consumerError?: Error;
+  private consumerInputClosed = false;
+
+  private outputBuffer: BufferedConnection;
+
+  constructor(private readonly rawStream: stream.Duplex) {
+    this.sdkInput = rawStream.pipe(streamDecoder());
+
+    this.outputBuffer = new BufferedConnection((buffer) => {
+      const hasMoreCapacity = rawStream.write(buffer);
+      if (hasMoreCapacity) {
+        return RESOLVED;
+      } else {
+        return new Promise((resolve) => rawStream.once("drain", resolve));
+      }
+    });
+
+    // remember and forward messages
+    this.sdkInput.on("data", (m: Message) => {
+      // deliver message, if we have a consumer. otherwise buffer the message.
+      if (this.currentConsumer) {
+        if (this.currentConsumer.handleMessage(m)) {
+          this.removeCurrentConsumer();
+        }
+      } else {
+        this.inputBuffer.push(m);
+      }
+    });
+
+    // remember and forward close events
+    this.sdkInput.on("end", () => {
+      this.consumerInputClosed = true;
+      if (this.currentConsumer) {
+        this.currentConsumer.handleInputClosed();
+      }
+    });
+
+    // --------- error handling --------
+    // - a.k.a. node event wrangling...
+
+    // the error handler for all sorts of errors coming from streams
+    const errorHandler = (e: Error) => {
+      // make sure we don't overwrite the initial error
+      if (this.consumerError !== undefined) {
+        return;
+      }
+      this.consumerError = e;
+      if (this.currentConsumer) {
+        this.currentConsumer.handleStreamError(e);
+      }
+    };
+
+    // those two event types should cover all types of connection losses
+    rawStream.on("aborted", () => {
+      rlog.error("Connection to Restate was lost");
+      errorHandler(new Error("Connection to Restate was lost"));
+    });
+
+    // this is both the raw http2 stream and the output SDK->Restate
+    rawStream.on("error", (e: Error) => {
+      rlog.error("Error in http2 stream to Restate: " + (e.stack ?? e.message));
+      errorHandler(e);
+    });
+
+    // these events notify of errors in the decoding pipeline
+    this.sdkInput.on("error", (e: Error) => {
+      rlog.error(
+        "Error in input stream (Restate to Service): " + (e.stack ?? e.message)
+      );
+      errorHandler(e);
+    });
+
+    // see if streams get torn down before they end cleanly
+    this.sdkInput.on("close", () => {
+      if (!this.consumerInputClosed) {
+        errorHandler(new Error("stream was destroyed before end"));
+      }
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  //  input stream handling
+  // --------------------------------------------------------------------------
+
+  /**
+   * Pipes the messages from this connection to the given consumer. The consumer
+   * will also receive error and stream closing notifications.
+   *
+   * Once the 'handleMessage()' method returns 'true', the consumer is immediately removed.
+   * That way, consumers can consume a bounded amount of messages (like just the initial journal).
+   *
+   * There can only be one consumer at a time.
+   */
+  public pipeToConsumer(consumer: RestateStreamConsumer): void {
+    if (this.currentConsumer !== null) {
+      throw new Error("Already piping to a consumer");
+    }
+
+    this.currentConsumer = consumer;
+
+    // propagate pre-existing information
+    if (this.consumerError) {
+      consumer.handleStreamError(this.consumerError);
+    }
+    if (this.consumerInputClosed) {
+      consumer.handleInputClosed();
+    }
+
+    // pipe the buffered input messages, if we buffered some before the consumer was registered
+    const input = this.inputBuffer;
+    if (input.length > 0) {
+      let i = 0;
+      while (i < input.length) {
+        const done = consumer.handleMessage(input[i]);
+        i++;
+        if (done) {
+          this.removeCurrentConsumer();
+          break;
+        }
+      }
+      this.inputBuffer = i === input.length ? [] : this.inputBuffer.slice(i);
+    }
+  }
+
+  /**
+   * Removes the current consumer, if there is one.
+   */
+  public removeCurrentConsumer(): void {
+    this.currentConsumer = null;
+  }
+
+  // --------------------------------------------------------------------------
+  //  output stream handling
+  // --------------------------------------------------------------------------
+
+  /**
+   * Adds a message to the output stream.
+   *
+   * This always puts the message into the node stream, but will return a promise that is resolved once
+   * further messages can be written.
+   *
+   * The reasoning is that some, but not all Restate operations return promises and are typically
+   * awaited. For example, rpc, sleep, side-effect have promises and are awaited, while one-way-sends and
+   * state updates don't return promises.
+   *
+   * As a pragmatic solution, we always accept messages, but return a promise for when the output has
+   * capacity again, so that at least the operations that await results will respect backpressure.
+   */
+  public send(msg: Message): Promise<void> {
+    return this.outputBuffer.send(msg);
+  }
+
+  /**
+   * Ends the stream, awaiting pending writes.
+   */
+  public async end(): Promise<void> {
+    await this.outputBuffer.end();
+
+    this.rawStream.end();
+
+    const options = {
+      error: true,
+      cleanup: true,
+    };
+
+    await finished(this.rawStream, options);
+  }
+}