@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/embedded/api.ts

@@ -0,0 +1,57 @@
+/*
+ * 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 { Context } from "../context";
+import { doInvoke } from "./invocation";
+import { wrapHandler } from "./handler";
+import crypto from "crypto";
+import { RemoteContext } from "../generated/proto/services";
+import { bufConnectRemoteContext } from "./http2_remote";
+import { OutgoingHttpHeaders } from "http";
+
+export type RestateConnectionOptions = {
+  /**
+   * Additional headers attached to the requests sent to Restate.
+   */
+  headers: OutgoingHttpHeaders;
+};
+
+export type RestateInvocationOptions = {
+  /**
+   * Retention period for the response in seconds.
+   * After the invocation completes, the response will be persisted for the given duration.
+   * Afterward, the system will clean up the response and treats any subsequent invocation with same operation_id as new.
+   *
+   * If not set, 30 minutes will be used as retention period.
+   */
+  retain?: number;
+};
+
+export const connection = (
+  address: string,
+  opt?: RestateConnectionOptions
+): RestateConnection =>
+  new RestateConnection(bufConnectRemoteContext(address, opt));
+
+export class RestateConnection {
+  constructor(private readonly remote: RemoteContext) {}
+
+  public invoke<I, O>(
+    id: string,
+    input: I,
+    handler: (ctx: Context, input: I) => Promise<O>,
+    opt?: RestateInvocationOptions
+  ): Promise<O> {
+    const method = wrapHandler(handler);
+    const streamId = crypto.randomUUID();
+    return doInvoke<I, O>(this.remote, id, streamId, input, method, opt);
+  }
+}

package/src/embedded/handler.ts

@@ -0,0 +1,36 @@
+/*
+ * 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 { Context, useContext } from "../context";
+import { GrpcServiceMethod, HostedGrpcServiceMethod } from "../types/grpc";
+
+export function wrapHandler<I, O>(
+  handler: (ctx: Context, input: I) => Promise<O>
+): HostedGrpcServiceMethod<I, O> {
+  const localMethod = (instance: unknown, input: I): Promise<O> => {
+    return handler(useContext(instance), input);
+  };
+
+  const encoder = (output: O): Uint8Array =>
+    Buffer.from(JSON.stringify(output));
+  const decoder = (buf: Uint8Array): I => JSON.parse(buf.toString());
+
+  const method = new GrpcServiceMethod<I, O>(
+    "",
+    "",
+    false,
+    localMethod,
+    decoder,
+    encoder
+  );
+
+  return new HostedGrpcServiceMethod<I, O>({}, "", "", method);
+}

package/src/embedded/http2_remote.ts

@@ -0,0 +1,103 @@
+/*
+ * 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 http2 from "node:http2";
+import { once } from "events";
+import {
+  RemoteContext,
+  RemoteContextClientImpl,
+} from "../generated/proto/services";
+import { RestateConnectionOptions } from "./api";
+import { OutgoingHttpHeaders } from "http";
+
+export class RequestError extends Error {
+  constructor(
+    public readonly url: string,
+    public readonly status: number,
+    public readonly statusText?: string
+  ) {
+    super(`${status} ${statusText ?? ""}`);
+  }
+
+  precondtionFailed(): boolean {
+    return this.status === http2.constants.HTTP_STATUS_PRECONDITION_FAILED;
+  }
+}
+
+export const bufConnectRemoteContext = (
+  url: string,
+  opt?: RestateConnectionOptions
+): RemoteContext => {
+  const httpClient = new ProtobufHttp2Client(url, opt);
+
+  return new RemoteContextClientImpl({
+    request: (service: string, method: string, data: Uint8Array) =>
+      httpClient.post(`/${service}/${method}`, data),
+  });
+};
+
+class ProtobufHttp2Client {
+  private session?: http2.ClientHttp2Session;
+  private additionalHeaders: OutgoingHttpHeaders;
+
+  public constructor(
+    private readonly ingress: string,
+    opt?: RestateConnectionOptions
+  ) {
+    this.additionalHeaders = opt?.headers == undefined ? {} : opt?.headers;
+  }
+
+  private async client(): Promise<http2.ClientHttp2Session> {
+    if (this.session !== undefined) {
+      return this.session;
+    }
+    const client = http2.connect(this.ingress);
+    client.unref();
+
+    client.once("goaway", () => {
+      this.session = undefined;
+    });
+    client.once("close", () => {
+      this.session = undefined;
+    });
+    this.session = client;
+    return client;
+  }
+
+  public async post(path: string, body: Uint8Array): Promise<Uint8Array> {
+    const client = await this.client();
+
+    const req = client.request({
+      ...{
+        [http2.constants.HTTP2_HEADER_SCHEME]: "http",
+        [http2.constants.HTTP2_HEADER_METHOD]:
+          http2.constants.HTTP2_METHOD_POST,
+        [http2.constants.HTTP2_HEADER_PATH]: path,
+        [http2.constants.HTTP2_HEADER_CONTENT_TYPE]: "application/proto",
+        [http2.constants.HTTP2_HEADER_ACCEPT]: "application/proto",
+        [http2.constants.HTTP2_HEADER_CONTENT_LENGTH]: body.length,
+      },
+      ...this.additionalHeaders,
+    });
+    req.end(body);
+
+    const [headers] = await once(req, "response");
+    const status = headers[http2.constants.HTTP2_HEADER_STATUS] ?? 0;
+    if (status !== 200) {
+      throw new RequestError(path, status);
+    }
+    const chunks = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+}

package/src/embedded/invocation.ts

@@ -0,0 +1,126 @@
+/*
+ * 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 { decodeMessagesBuffer } from "../io/decoder";
+import { Message } from "../types/types";
+import {
+  GetResultResponse,
+  RemoteContext,
+  StartRequest,
+} from "../generated/proto/services";
+import { InvocationBuilder } from "../invocation";
+import { HostedGrpcServiceMethod } from "../types/grpc";
+import { StateMachine } from "../state_machine";
+import { ProtocolMode } from "../generated/proto/discovery";
+import {
+  EmbeddedConnection,
+  FencedOffError,
+} from "../connection/embedded_connection";
+import { RestateInvocationOptions } from "./api";
+
+export const doInvoke = async <I, O>(
+  remote: RemoteContext,
+  operationId: string,
+  streamId: string,
+  input: I,
+  method: HostedGrpcServiceMethod<I, O>,
+  opt?: RestateInvocationOptions
+): Promise<O> => {
+  //
+  // 1. ask to Start this execution.
+  //
+
+  const startRequest = StartRequest.fromPartial({
+    operationId,
+    streamId,
+    argument: Buffer.from(JSON.stringify(input)),
+  });
+  if (opt != undefined && opt.retain != undefined) {
+    startRequest.retentionPeriodSec = opt.retain;
+  }
+  const res = await remote.start(startRequest);
+
+  if (res.completed !== undefined) {
+    return unwrap(res.completed);
+  }
+
+  //
+  // 2. rebuild the previous execution state
+  //
+
+  const messages = decodeMessagesBuffer(res.executing ?? Buffer.alloc(0));
+  const journalBuilder = new InvocationBuilder(method);
+  messages.forEach((e: Message) => journalBuilder.handleMessage(e));
+  const journal = journalBuilder.build();
+
+  //
+  // 3. resume the execution state machine
+  //
+  const connection = new EmbeddedConnection(operationId, streamId, remote);
+
+  const stateMachine = new StateMachine(
+    connection,
+    journal,
+    ProtocolMode.BIDI_STREAM,
+    false,
+    journal.inferLoggerContext(),
+    -1
+  );
+
+  //
+  // 4. track the state machine execution result
+  //
+  let done = false;
+
+  const invocation = stateMachine.invoke().finally(() => (done = true));
+
+  //
+  // 5. keep pulling for input and feeding this to the fsm.
+  //
+  try {
+    while (!done) {
+      const recv = await remote.recv({
+        operationId,
+        streamId,
+      });
+      if (recv.invalidStream !== undefined) {
+        throw new FencedOffError();
+      }
+      if (recv.invocationCompleted !== undefined) {
+        break;
+      }
+      const buffer = recv.messages ?? Buffer.alloc(0);
+      const messages = decodeMessagesBuffer(buffer);
+      messages.forEach((m: Message) => stateMachine.handleMessage(m));
+    }
+  } catch (e) {
+    stateMachine.handleStreamError(e as Error);
+    throw e;
+  }
+
+  //
+  // 6. wait for the state machine to complete the invocation
+  //
+  const maybeResult = await invocation;
+  if (maybeResult instanceof Buffer) {
+    return JSON.parse(maybeResult.toString());
+  }
+
+  // TODO: no sure what to do here. The state machine has decided to be suspended?
+  throw new Error("suspended");
+};
+
+const unwrap = <O>(response: GetResultResponse): O => {
+  if (response.success === undefined) {
+    throw new Error(response.failure?.message ?? "");
+  }
+  return JSON.parse(response.success.toString()) as O;
+};