Endpoint manifest v3 (#551)

* Discovery manifest V3.

I regenerated the discovery manifest using a generator, the documentation for that is in the README.

* Expose all the new service manifest configuration options.

* Make sure that setting the v3 fields will fail discovery when using an old runtime.

Author: slinkydeveloper

README.md

@@ -109,6 +109,12 @@ npm run -w packages/restate-sdk-examples workflow
 
 See https://github.com/restatedev/e2e/ for more details.
 
+### Re-generating the discovery manifest
+
+```shell
+npx --package=json-schema-to-typescript json2ts endpoint_manifest_schema.json packages/restate-sdk/src/types/discovery.ts
+```
+
 ## Releasing the package
 
 ### Releasing via release-it

packages/restate-sdk-examples/src/greeter_with_options.ts

@@ -0,0 +1,38 @@
+/*
+ * 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 {
+  service,
+  endpoint,
+  handlers,
+  type Context,
+} from "@restatedev/restate-sdk";
+
+const greeter = service({
+  name: "greeter",
+  handlers: {
+    greet: handlers.handler(
+      {
+        journalRetention: { days: 1 },
+      },
+      async (ctx: Context, name: string) => {
+        return `Hello ${name}`;
+      }
+    ),
+  },
+  options: {
+    journalRetention: { days: 2 },
+  },
+});
+
+export type Greeter = typeof greeter;
+
+endpoint().bind(greeter).listen();

packages/restate-sdk/src/common_api.ts

@@ -79,6 +79,9 @@ export type {
   ServiceOpts,
   ObjectOpts,
   WorkflowOpts,
+  ServiceOptions,
+  ObjectOptions,
+  WorkflowOptions,
 } from "./types/rpc.js";
 export {
   service,

packages/restate-sdk/src/endpoint/endpoint_builder.ts

@@ -18,6 +18,11 @@ import type {
   WorkflowDefinition,
 } from "@restatedev/restate-sdk-core";
 
+import type {
+  ObjectOptions,
+  ServiceOptions,
+  WorkflowOptions,
+} from "../types/rpc.js";
 import { HandlerWrapper } from "../types/rpc.js";
 import type { Component } from "../types/components.js";
 import {
@@ -59,6 +64,7 @@ function isWorkflowDefinition<P extends string, M>(
 type ServiceAuxInfo = {
   description?: string;
   metadata?: Record<string, any>;
+  options?: ServiceOptions | ObjectOptions | WorkflowOptions;
 };
 
 export class EndpointBuilder {
@@ -165,7 +171,8 @@ export class EndpointBuilder {
     const component = new ServiceComponent(
       name,
       definition.description,
-      definition.metadata
+      definition.metadata,
+      definition?.options as ServiceOptions
     );
 
     for (const [route, handler] of Object.entries(
@@ -193,7 +200,8 @@ export class EndpointBuilder {
     const component = new VirtualObjectComponent(
       name,
       definition.description,
-      definition.metadata
+      definition.metadata,
+      definition?.options as ObjectOptions
     );
 
     for (const [route, handler] of Object.entries(
@@ -220,7 +228,8 @@ export class EndpointBuilder {
     const component = new WorkflowComponent(
       name,
       definition.description,
-      definition.metadata
+      definition.metadata,
+      definition?.options as WorkflowOptions
     );
 
     for (const [route, handler] of Object.entries(

packages/restate-sdk/src/endpoint/fetch_endpoint.ts

@@ -19,8 +19,8 @@ import { EndpointBuilder } from "./endpoint_builder.js";
 import type { RestateEndpointBase } from "../endpoint.js";
 import { GenericHandler } from "./handlers/generic.js";
 import { fetcher } from "./handlers/fetch.js";
-import { ProtocolMode } from "../types/discovery.js";
 import type { LoggerTransport } from "../logging/logger_transport.js";
+import type { ProtocolMode } from "../types/discovery.js";
 
 /**
  * Generic Fetch encapsulates all the Restate services served by this endpoint.
@@ -90,9 +90,7 @@ export class FetchEndpointImpl implements FetchEndpoint {
   }
 
   public bidirectional(set: boolean = true): FetchEndpoint {
-    this.protocolMode = set
-      ? ProtocolMode.BIDI_STREAM
-      : ProtocolMode.REQUEST_RESPONSE;
+    this.protocolMode = set ? "BIDI_STREAM" : "REQUEST_RESPONSE";
     return this;
   }
 

packages/restate-sdk/src/endpoint/handlers/generic.ts

@@ -71,6 +71,9 @@ export interface RestateHandler {
   ): Promise<RestateResponse>;
 }
 
+const ENDPOINT_MANIFEST_V2 = "application/vnd.restate.endpointmanifest.v2+json";
+const ENDPOINT_MANIFEST_V3 = "application/vnd.restate.endpointmanifest.v3+json";
+
 /**
  * This is an internal API to support 'fetch' like handlers.
  * It supports both request-reply mode and bidirectional streaming mode.
@@ -429,11 +432,13 @@ export class GenericHandler implements RestateHandler {
       return this.toErrorResponse(415, errorMessage);
     }
 
-    if (
-      !acceptVersionsString.includes(
-        "application/vnd.restate.endpointmanifest.v1+json"
-      )
-    ) {
+    // Negotiate version to use
+    let manifestVersion;
+    if (acceptVersionsString.includes(ENDPOINT_MANIFEST_V3)) {
+      manifestVersion = 3;
+    } else if (acceptVersionsString.includes(ENDPOINT_MANIFEST_V2)) {
+      manifestVersion = 2;
+    } else {
       const errorMessage = `Unsupported service discovery protocol version '${acceptVersionsString}'`;
       this.endpoint.rlog.warn(errorMessage);
       return this.toErrorResponse(415, errorMessage);
@@ -442,9 +447,71 @@ export class GenericHandler implements RestateHandler {
     const discovery = this.endpoint.computeDiscovery(this.protocolMode);
     const body = JSON.stringify(discovery);
 
+    // type AllowedNames<T, U> = { [K in keyof T]: T[K] extends U ? K : never; }[keyof T];
+    //
+    // const checkUnsupportedFeature =  (obj: Record<string, unknown>, fields: Array<string>)=> {
+    //   for (const field of fields) {
+    //     if (field in obj && obj[field] !== undefined) {
+    //       return this.toErrorResponse(500, `The code uses the new discovery feature '${field}' but the runtime doesn't support it yet. Either remove the usage of this feature, or upgrade the runtime.`);
+    //     }
+    //   }
+    //   return;
+    // }
+
+    const checkUnsupportedFeature = <T extends object>(
+      obj: T,
+      ...fields: Array<keyof T>
+    ) => {
+      for (const field of fields) {
+        if (field in obj && obj[field] !== undefined) {
+          return this.toErrorResponse(
+            500,
+            `The code uses the new discovery feature '${String(
+              field
+            )}' but the runtime doesn't support it yet. Either remove the usage of this feature, or upgrade the runtime.`
+          );
+        }
+      }
+      return;
+    };
+
+    // Verify none of the manifest v3 configuration options are used.
+    if (manifestVersion < 3) {
+      for (const service of discovery.services) {
+        const error = checkUnsupportedFeature(
+          service,
+          "journalRetention",
+          "idempotencyRetention",
+          "inactivityTimeout",
+          "abortTimeout",
+          "enableLazyState",
+          "ingressPrivate"
+        );
+        if (error !== undefined) {
+          return error;
+        }
+        for (const handler of service.handlers) {
+          const error = checkUnsupportedFeature(
+            handler,
+            "journalRetention",
+            "idempotencyRetention",
+            "workflowCompletionRetention",
+            "inactivityTimeout",
+            "abortTimeout",
+            "enableLazyState",
+            "ingressPrivate"
+          );
+          if (error !== undefined) {
+            return error;
+          }
+        }
+      }
+    }
+
     return {
       headers: {
-        "content-type": "application/vnd.restate.endpointmanifest.v1+json",
+        "content-type":
+          manifestVersion === 2 ? ENDPOINT_MANIFEST_V2 : ENDPOINT_MANIFEST_V3,
         "x-restate-server": X_RESTATE_SERVER,
       },
       statusCode: 200,

packages/restate-sdk/src/endpoint/lambda_endpoint.ts

@@ -19,7 +19,6 @@ import { EndpointBuilder } from "./endpoint_builder.js";
 import type { RestateEndpointBase } from "../endpoint.js";
 import { GenericHandler } from "./handlers/generic.js";
 import { LambdaHandler } from "./handlers/lambda.js";
-import { ProtocolMode } from "../types/discovery.js";
 import type { LoggerTransport } from "../logging/logger_transport.js";
 
 /**
@@ -78,10 +77,7 @@ export class LambdaEndpointImpl implements LambdaEndpoint {
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   handler(): (event: any, ctx: any) => Promise<any> {
-    const genericHandler = new GenericHandler(
-      this.builder,
-      ProtocolMode.REQUEST_RESPONSE
-    );
+    const genericHandler = new GenericHandler(this.builder, "REQUEST_RESPONSE");
     const lambdaHandler = new LambdaHandler(genericHandler);
     return lambdaHandler.handleRequest.bind(lambdaHandler);
   }

packages/restate-sdk/src/endpoint/node_endpoint.ts

@@ -27,7 +27,6 @@ import { EndpointBuilder } from "./endpoint_builder.js";
 import { GenericHandler } from "./handlers/generic.js";
 import { Readable, Writable } from "node:stream";
 import type { WritableStream } from "node:stream/web";
-import { ProtocolMode } from "../types/discovery.js";
 import { ensureError } from "../types/errors.js";
 import type { LoggerTransport } from "../logging/logger_transport.js";
 
@@ -70,7 +69,7 @@ export class NodeEndpoint implements RestateEndpoint {
     request: Http2ServerRequest,
     response: Http2ServerResponse
   ) => void {
-    const handler = new GenericHandler(this.builder, ProtocolMode.BIDI_STREAM);
+    const handler = new GenericHandler(this.builder, "BIDI_STREAM");
 
     return (request, response) => {
       (async () => {
@@ -113,10 +112,7 @@ export class NodeEndpoint implements RestateEndpoint {
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   lambdaHandler(): (event: any, ctx: any) => Promise<any> {
-    const genericHandler = new GenericHandler(
-      this.builder,
-      ProtocolMode.REQUEST_RESPONSE
-    );
+    const genericHandler = new GenericHandler(this.builder, "REQUEST_RESPONSE");
     const handler = new LambdaHandler(genericHandler);
     return handler.handleRequest.bind(handler);
   }

packages/restate-sdk/src/fetch.ts

@@ -15,12 +15,11 @@ import {
   type FetchEndpoint,
   FetchEndpointImpl,
 } from "./endpoint/fetch_endpoint.js";
-import { ProtocolMode } from "./types/discovery.js";
 
 /**
  * Create a new {@link RestateEndpoint} in request response protocol mode.
  * Bidirectional mode (must be served over http2) can be enabled with .enableHttp2()
  */
 export function endpoint(): FetchEndpoint {
-  return new FetchEndpointImpl(ProtocolMode.REQUEST_RESPONSE);
+  return new FetchEndpointImpl("REQUEST_RESPONSE");
 }