@restatedev/restate-sdk 0.7.3-worker → 0.8.1

package/src/endpoint/http2_handler.ts

@@ -0,0 +1,151 @@
+/*
+ * 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 { pipeline, finished } from "stream/promises";
+import http2, { Http2ServerRequest, Http2ServerResponse } from "http2";
+import { parse as urlparse, Url } from "url";
+import {
+  ProtocolMode,
+  ServiceDiscoveryResponse,
+} from "../generated/proto/discovery";
+import { EndpointImpl } from "./endpoint_impl";
+import { RestateHttp2Connection } from "../connection/http_connection";
+import { HostedGrpcServiceMethod } from "../types/grpc";
+import { ensureError } from "../types/errors";
+import { InvocationBuilder } from "../invocation";
+import { StateMachine } from "../state_machine";
+import { rlog } from "../logger";
+
+export class Http2Handler {
+  private readonly discoveryResponse: ServiceDiscoveryResponse;
+  constructor(private readonly endpoint: EndpointImpl) {
+    this.discoveryResponse = ServiceDiscoveryResponse.fromPartial({
+      ...this.endpoint.discovery,
+      protocolMode: ProtocolMode.BIDI_STREAM,
+    });
+  }
+
+  acceptConnection(
+    request: Http2ServerRequest,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _response: Http2ServerResponse
+  ) {
+    const stream = request.stream;
+    const url: Url = urlparse(request.url ?? "/");
+
+    this.handleConnection(url, stream).catch((e) => {
+      const error = ensureError(e);
+      rlog.error(
+        "Error while handling connection: " + (error.stack ?? error.message)
+      );
+      stream.end();
+      stream.destroy();
+    });
+  }
+
+  private async handleConnection(
+    url: Url,
+    stream: http2.ServerHttp2Stream
+  ): Promise<void> {
+    const method = this.endpoint.methodByUrl(url.path);
+
+    if (method !== undefined) {
+      // valid connection, let's dispatch the invocation
+      stream.respond({
+        "content-type": "application/restate",
+        ":status": 200,
+      });
+
+      const restateStream = RestateHttp2Connection.from(stream);
+      await handleInvocation(method, restateStream);
+      return;
+    }
+
+    // no method under that name. might be a discovery request
+    if (url.path == "/discover") {
+      rlog.info(
+        "Answering discovery request. Announcing services: " +
+          JSON.stringify(this.discoveryResponse.services)
+      );
+      await respondDiscovery(this.discoveryResponse, stream);
+      return;
+    }
+
+    // no discovery, so unknown method: 404
+    rlog.error(`No service and function found for URL ${url.path}`);
+    await respondNotFound(stream);
+  }
+}
+
+async function respondDiscovery(
+  response: ServiceDiscoveryResponse,
+  http2Stream: http2.ServerHttp2Stream
+) {
+  const responseData = ServiceDiscoveryResponse.encode(response).finish();
+
+  http2Stream.respond({
+    ":status": 200,
+    "content-type": "application/proto",
+  });
+
+  await pipeline(stream.Readable.from(responseData), http2Stream, {
+    end: true,
+  });
+}
+
+async function respondNotFound(stream: http2.ServerHttp2Stream) {
+  stream.respond({
+    "content-type": "application/restate",
+    ":status": 404,
+  });
+  stream.end();
+  await finished(stream);
+}
+
+async function handleInvocation<I, O>(
+  func: HostedGrpcServiceMethod<I, O>,
+  connection: RestateHttp2Connection
+) {
+  // step 1: collect all journal events
+  const journalBuilder = new InvocationBuilder<I, O>(func);
+  connection.pipeToConsumer(journalBuilder);
+  try {
+    await journalBuilder.completion();
+  } finally {
+    // ensure GC friendliness, also in case of errors
+    connection.removeCurrentConsumer();
+  }
+
+  // step 2: create the state machine
+  const invocation = journalBuilder.build();
+  const stateMachine = new StateMachine<I, O>(
+    connection,
+    invocation,
+    ProtocolMode.BIDI_STREAM,
+    func.method.keyedContext,
+    invocation.inferLoggerContext()
+  );
+  connection.pipeToConsumer(stateMachine);
+
+  // step 3: invoke the function
+
+  // This call would propagate errors in the state machine logic, but not errors
+  // in the application function code. Ending a function with an error as well
+  // as failign an invocation and being retried are perfectly valid actions from the
+  // SDK's perspective.
+  try {
+    await stateMachine.invoke();
+  } finally {
+    // ensure GC friendliness, also in case of errors
+    connection.removeCurrentConsumer();
+  }
+}

package/src/endpoint/lambda_handler.ts

@@ -0,0 +1,181 @@
+/*
+ * 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 { rlog } from "../logger";
+import {
+  APIGatewayProxyEvent,
+  APIGatewayProxyEventV2,
+  APIGatewayProxyResult,
+  APIGatewayProxyResultV2,
+  Context,
+} from "aws-lambda";
+import {
+  ProtocolMode,
+  ServiceDiscoveryResponse,
+} from "../generated/proto/discovery";
+import { EndpointImpl } from "./endpoint_impl";
+import { LambdaConnection } from "../connection/lambda_connection";
+import { InvocationBuilder } from "../invocation";
+import { decodeLambdaBody } from "../io/decoder";
+import { Message } from "../types/types";
+import { StateMachine } from "../state_machine";
+import { ensureError } from "../types/errors";
+import { OUTPUT_STREAM_ENTRY_MESSAGE_TYPE } from "../types/protocol";
+
+export class LambdaHandler {
+  private readonly discoveryResponse: ServiceDiscoveryResponse;
+  constructor(private readonly endpoint: EndpointImpl) {
+    this.discoveryResponse = ServiceDiscoveryResponse.fromPartial({
+      ...this.endpoint.discovery,
+      protocolMode: ProtocolMode.REQUEST_RESPONSE,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * This is the main request handling method, effectively a typed variant of `create()`.
+   */
+  async handleRequest(
+    event: APIGatewayProxyEvent | APIGatewayProxyEventV2,
+    context: Context
+  ): Promise<APIGatewayProxyResult | APIGatewayProxyResultV2> {
+    let path;
+    if ("path" in event) {
+      // V1
+      path = event.path;
+    } else {
+      // V2
+      path = event.rawPath;
+    }
+    const pathSegments = path.split("/");
+
+    // API Gateway can add a prefix to the path based on the name of the Lambda function and deployment stage
+    // (e.g. /default)
+    // So we only check the ending of the path on correctness.
+    // Logic:
+    // 1. Check whether there are at least three segments in the path and whether the third-last one is "invoke".
+    // If that is the case, treat it as an invocation.
+    // 2. See if the last one is "discover", answer with discovery.
+    // 3. Else report "invalid path".
+    if (
+      pathSegments.length >= 3 &&
+      pathSegments[pathSegments.length - 3] === "invoke"
+    ) {
+      const url = "/" + pathSegments.slice(-3).join("/");
+      return await this.handleInvoke(url, event, context);
+    } else if (pathSegments[pathSegments.length - 1] === "discover") {
+      return this.handleDiscovery();
+    } else {
+      const msg = `Invalid path: path doesn't end in /invoke/SvcName/MethodName and also not in /discover: ${path}`;
+      rlog.trace(msg);
+      return this.toErrorResponse(500, msg);
+    }
+  }
+
+  private async handleInvoke(
+    url: string,
+    event: APIGatewayProxyEvent | APIGatewayProxyEventV2,
+    context: Context
+  ): Promise<APIGatewayProxyResult | APIGatewayProxyResultV2> {
+    try {
+      const method = this.endpoint.methodByUrl(url);
+      if (event.body == null) {
+        throw new Error("The incoming message body was null");
+      }
+
+      if (method === undefined) {
+        if (url.includes("?")) {
+          throw new Error(
+            `Invalid path: path URL seems to include query parameters: ${url}`
+          );
+        } else {
+          const msg = `No service found for URL: ${url}`;
+          rlog.error(msg);
+          return this.toErrorResponse(404, msg);
+        }
+      }
+
+      // build the previous journal from the events
+      let decodedEntries: Message[] | null = decodeLambdaBody(event.body);
+      const journalBuilder = new InvocationBuilder(method);
+      decodedEntries.forEach((e: Message) => journalBuilder.handleMessage(e));
+      const alreadyCompleted =
+        decodedEntries.find(
+          (e: Message) => e.messageType === OUTPUT_STREAM_ENTRY_MESSAGE_TYPE
+        ) !== undefined;
+      decodedEntries = null;
+
+      // set up and invoke the state machine
+      const connection = new LambdaConnection(alreadyCompleted);
+      const invocation = journalBuilder.build();
+      const stateMachine = new StateMachine(
+        connection,
+        invocation,
+        ProtocolMode.REQUEST_RESPONSE,
+        method.method.keyedContext,
+        invocation.inferLoggerContext({
+          AWSRequestId: context.awsRequestId,
+        })
+      );
+      await stateMachine.invoke();
+      const result = await connection.getResult();
+
+      return {
+        headers: {
+          "content-type": "application/restate",
+        },
+        statusCode: 200,
+        isBase64Encoded: true,
+        body: encodeResponse(result),
+      };
+    } catch (e) {
+      const error = ensureError(e);
+      rlog.error(error.message);
+      rlog.error(error.stack);
+      return this.toErrorResponse(500, error.message);
+    }
+  }
+
+  private handleDiscovery(): APIGatewayProxyResult | APIGatewayProxyResultV2 {
+    // return discovery information
+    rlog.info(
+      "Answering discovery request. Announcing services: " +
+        JSON.stringify(this.discoveryResponse.services)
+    );
+    return {
+      headers: {
+        "content-type": "application/proto",
+      },
+      statusCode: 200,
+      isBase64Encoded: true,
+      body: encodeResponse(
+        ServiceDiscoveryResponse.encode(this.discoveryResponse).finish()
+      ),
+    };
+  }
+
+  private toErrorResponse(code: number, message: string) {
+    return {
+      headers: {
+        "content-type": "application/restate",
+      },
+      statusCode: code,
+      isBase64Encoded: true,
+      body: encodeResponse(Buffer.from(JSON.stringify({ message }))),
+    };
+  }
+}
+
+function encodeResponse(data: Uint8Array): string {
+  const buffer = data instanceof Buffer ? data : Buffer.from(data);
+  return buffer.toString("base64");
+}

package/src/endpoint.ts

@@ -0,0 +1,187 @@
+/*
+ * 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 { KeyedRouter, UnKeyedRouter } from "./types/router";
+import { ProtoMetadata } from "./types/grpc";
+import { Http2ServerRequest, Http2ServerResponse } from "http2";
+import { EndpointImpl } from "./endpoint/endpoint_impl";
+
+/**
+ * Create a new {@link RestateEndpoint}.
+ */
+export function endpoint(): RestateEndpoint {
+  return new EndpointImpl();
+}
+
+/**
+ * The properties describing a gRPC service. Consisting of the name, the object holding the
+ * implementation, and the descriptor (metadata) describing the service and types.
+ */
+export interface ServiceOpts {
+  descriptor: ProtoMetadata;
+  service: string;
+  instance: unknown;
+}
+
+/**
+ * Utility interface for a bundle of one or more services belonging together
+ * and being registered together.
+ */
+export interface ServiceBundle {
+  /**
+   * Called to register the services at the endpoint.
+   */
+  registerServices(endpoint: RestateEndpoint): void;
+}
+
+/**
+ * RestateEndpoint encapsulates all the Restate services served by this endpoint.
+ *
+ * A RestateEndpoint can either be served either as HTTP2 server, using the methods {@link listen} or {@link http2Handler},
+ * or as Lambda, using the method {@link lambdaHandler}.
+ *
+ * @example
+ * A typical endpoint served as HTTP server would look like this:
+ * ```
+ * import * as restate from "@restatedev/restate-sdk";
+ *
+ * restate
+ *   .endpoint()
+ *   .bindService({
+ *      service: "MyService",
+ *      instance: new myService.MyServiceImpl(),
+ *      descriptor: myService.protoMetadata,
+ *    })
+ *   .listen(8000);
+ * ```
+ * @example
+ * A typical endpoint served as AWS Lambda would look like this:
+ * ```
+ * import * as restate from "@restatedev/restate-sdk";
+ *
+ * export const handler = restate
+ *   .endpoint()
+ *   .bindService({
+ *      service: "MyService",
+ *      instance: new myService.MyServiceImpl(),
+ *      descriptor: myService.protoMetadata,
+ *    })
+ *   .lambdaHandler();
+ * ```
+ */
+export interface RestateEndpoint {
+  /**
+   * Adds a gRPC service to be served from this endpoint.
+   *
+   * The {@link ServiceOpts} passed here need to describe the following properties:
+   *
+   *   - The 'service' name: the name of the gRPC service (as in the service definition proto file).
+   *   - The service 'instance': the implementation of the service logic (must implement the generated
+   *     gRPC service interface).
+   *   - The gRPC/protobuf 'descriptor': The protoMetadata descriptor that describes the service, methods,
+   *     and parameter types. It is usually found as the value 'protoMetadata' in the generated
+   *     file '(service-name).ts'
+   *
+   *     The descriptor is generated by the protobuf compiler and needed by Restate to reflectively discover
+   *     the service details, understand payload serialization, perform HTTP/JSON-to-gRPC transcoding, or
+   *     to proxy the service.
+   *
+   * If you define multiple services in the same '.proto' file, you may have only one descriptor that
+   * describes all services together. You can pass the same descriptor to multiple calls of '.bindService()'.
+   *
+   * If you don't find the gRPC/protobuf descriptor, make your you generated the gRPC/ProtoBuf code with
+   * the option to generate the descriptor. For example, using the 'ts-proto' plugin, make sure you pass
+   * the 'outputSchema=true' option. If you are using Restate's project templates, this should all be
+   * pre-configured for you.
+   *
+   * @example
+   * ```
+   * endpoint.bindService({
+   *   service: "MyService",
+   *   instance: new myService.MyServiceImpl(),
+   *   descriptor: myService.protoMetadata
+   * })
+   * ```
+   *
+   * @param serviceOpts The options describing the service to be bound. See above for a detailed description.
+   * @returns An instance of this LambdaRestateServer
+   */
+  bindService(serviceOpts: ServiceOpts): RestateEndpoint;
+
+  /**
+   * Binds a new durable RPC service to the given path. This method is for regular (stateless)
+   * durably executed RPC services.
+   *
+   * The service will expose all properties of the router that are functions as follows:
+   * If the path is 'acme.myservice' and the router has '{ foo, bar }' as properties, the
+   * Restate will expose the RPC paths '/acme.myservice/foo' and '/acme.myservice/bar'.
+   */
+  bindRouter<M>(path: string, router: UnKeyedRouter<M>): RestateEndpoint;
+
+  /**
+   * Binds a new stateful keyed durable RPC service to the given path.
+   * This method is services where each invocation is bound to a key and that may maintain
+   * state per key.
+   *
+   * The service will expose all properties of the router that are functions as follows:
+   * If the path is 'acme.myservice' and the router has '{ foo, bar }' as properties, the
+   * Restate will expose the RPC paths '/acme.myservice/foo' and '/acme.myservice/bar'.
+   */
+  bindKeyedRouter<M>(path: string, router: KeyedRouter<M>): RestateEndpoint;
+
+  /**
+   * Adds one or more services to this endpoint. This will call the
+   * {@link ServiceBundle.registerServices} function to register all services at this endpoint.
+   */
+  bind(services: ServiceBundle): RestateEndpoint;
+
+  /**
+   * Creates the invocation handler function to be called by AWS Lambda.
+   *
+   * The returned type of this function is `(event: APIGatewayProxyEvent | APIGatewayProxyEventV2) => Promise<APIGatewayProxyResult | APIGatewayProxyResultV2>`.
+   * We use `any` types here to avoid a dependency on the `@types/aws-lambda` dependency for consumers of this API.
+   *
+   * @returns The invocation handler function for to be called by AWS Lambda.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  lambdaHandler(): (event: any, ctx: any) => Promise<any>;
+
+  /**
+   * Serve this Restate Endpoint as HTTP2 server, listening to the given port.
+   *
+   * If the port is undefined, this method will use the port set in the `PORT`
+   * environment variable. If that variable is undefined as well, the method will
+   * default to port 9080.
+   *
+   * This method's result promise never completes.
+   *
+   * This method is a shorthand for:
+   *
+   * @example
+   * ```
+   * const httpServer = http2.createServer(endpoint.http2Handler());
+   * httpServer.listen(port);
+   * ```
+   *
+   * If you need to manually control the server lifecycle, we suggest to manually instantiate the http2 server and use {@link http2Handler}.
+   *
+   * @param port The port to listen at. May be undefined (see above).
+   */
+  listen(port?: number): Promise<void>;
+
+  /**
+   * Returns an http2 server handler. See {@link listen} for more details.
+   */
+  http2Handler(): (
+    request: Http2ServerRequest,
+    response: Http2ServerResponse
+  ) => void;
+}