Replace chained endpoint API with unified createEndpointHandler (#574)

nikrooz · web-flow · commit 31cb8859ffe7 · 2025-07-30T12:30:38.000+01:00
---------

Signed-off-by: Nik Nasr &lt;nik@restate.dev&gt;
diff --git a/README.md b/README.md
@@ -23,9 +23,7 @@ const greeter = restate.service({
     },
 });
 
-restate.endpoint()
-    .bind(greeter)
-    .listen(9080);
+restate.serve({ services: [greeter], port: 9080 });
 ```
 
 ## Community
diff --git a/packages/restate-sdk-cloudflare-workers/patches/fetch.js b/packages/restate-sdk-cloudflare-workers/patches/fetch.js
diff --git a/packages/restate-sdk-examples/src/greeter.ts b/packages/restate-sdk-examples/src/greeter.ts
@@ -9,7 +9,7 @@
  * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE
  */
 
-import { service, endpoint, type Context } from "@restatedev/restate-sdk";
+import { service, serve, type Context } from "@restatedev/restate-sdk";
 
 const greeter = service({
   name: "greeter",
@@ -22,4 +22,4 @@ const greeter = service({
 
 export type Greeter = typeof greeter;
 
-endpoint().bind(greeter).listen();
+serve({ services: [greeter] });
diff --git a/packages/restate-sdk-examples/src/greeter_with_options.ts b/packages/restate-sdk-examples/src/greeter_with_options.ts
@@ -11,7 +11,7 @@
 
 import {
   service,
-  endpoint,
+  serve,
   handlers,
   TerminalError,
   type Context,
@@ -49,10 +49,10 @@ const greeter = service({
 
 export type Greeter = typeof greeter;
 
-endpoint()
-  .bind(greeter)
-  .defaultServiceOptions({
+serve({
+  services: [greeter],
+  defaultServiceOptions: {
     // You can configure default service options that will be applied to every service.
     journalRetention: { days: 10 },
-  })
-  .listen();
+  },
+});
diff --git a/packages/restate-sdk-examples/src/object.ts b/packages/restate-sdk-examples/src/object.ts
@@ -59,4 +59,4 @@ export const counter = restate.object({
 
 export type Counter = typeof counter;
 
-restate.endpoint().bind(counter).listen();
+restate.serve({ services: [counter] });
diff --git a/packages/restate-sdk-examples/src/workflow.ts b/packages/restate-sdk-examples/src/workflow.ts
@@ -120,4 +120,4 @@ const payment = restate.workflow({
 
 export type PaymentWorkflow = typeof payment;
 
-restate.endpoint().bind(payment).listen();
+restate.serve({ services: [payment] });
diff --git a/packages/restate-sdk-examples/src/zod_greeter.ts b/packages/restate-sdk-examples/src/zod_greeter.ts
@@ -34,4 +34,4 @@ const greeter = restate.service({
 
 export type Greeter = typeof greeter;
 
-restate.endpoint().bind(greeter).listen();
+restate.serve({ services: [greeter] });
diff --git a/packages/restate-sdk-examples/test/hello.test.ts b/packages/restate-sdk-examples/test/hello.test.ts
@@ -13,7 +13,7 @@ import * as restate from "@restatedev/restate-sdk";
 import { describe, it } from "vitest";
 
 describe("HelloGreeter", () => {
-  it("Demonstrates how to write a simple services", () => {
+  it("Demonstrates how we used to write a simple services", () => {
     const myservice = restate.service({
       name: "myservice",
       handlers: {
@@ -24,6 +24,22 @@ describe("HelloGreeter", () => {
     });
 
     restate.endpoint().bind(myservice);
+
+    //---> 	.listen();
+  });
+
+  it("Demonstrates how to write a simple services", () => {
+    const myservice = restate.service({
+      name: "myservice",
+      handlers: {
+        greet: async (ctx: restate.Context) => {
+          return await ctx.run("greet", () => "hi there!");
+        },
+      },
+    });
+
+    restate.createEndpointHandler({ services: [myservice] });
+
     //---> 	.listen();
   });
 });
diff --git a/packages/restate-sdk-examples/test/testcontainers.test.ts b/packages/restate-sdk-examples/test/testcontainers.test.ts
@@ -26,9 +26,9 @@ describe("ExampleObject", () => {
 
   // Deploy Restate and the Service endpoint once for all the tests in this suite
   beforeAll(async () => {
-    restateTestEnvironment = await RestateTestEnvironment.start(
-      (restateServer) => restateServer.bind(counter)
-    );
+    restateTestEnvironment = await RestateTestEnvironment.start({
+      services: [counter],
+    });
     rs = clients.connect({ url: restateTestEnvironment.baseUrl() });
   }, 20_000);
 
@@ -127,7 +127,7 @@ describe("Custom testcontainer config", () => {
   // Deploy Restate and the Service endpoint once for all the tests in this suite
   beforeAll(async () => {
     restateTestEnvironment = await RestateTestEnvironment.start(
-      (restateServer) => restateServer.bind(counter),
+      { services: [counter] },
       () =>
         new RestateContainer()
           .withEnvironment({ RESTATE_LOG_FORMAT: "json" })
diff --git a/packages/restate-sdk-testcontainers/src/public_api.ts b/packages/restate-sdk-testcontainers/src/public_api.ts
@@ -32,4 +32,5 @@ export type {
   WorkflowOptions,
   TerminalError,
   RestateError,
+  EndpointOptions,
 } from "@restatedev/restate-sdk";
diff --git a/packages/restate-sdk-testcontainers/src/restate_test_environment.ts b/packages/restate-sdk-testcontainers/src/restate_test_environment.ts
@@ -11,14 +11,19 @@
 
 /* eslint-disable no-console */
 
-import { endpoint, serde } from "@restatedev/restate-sdk";
+import {
+  endpoint,
+  createEndpointHandler,
+  serde,
+} from "@restatedev/restate-sdk";
 import type {
   TypedState,
   UntypedState,
   Serde,
   RestateEndpoint,
   VirtualObjectDefinition,
   WorkflowDefinition,
+  EndpointOptions,
 } from "@restatedev/restate-sdk";
 
 import {
@@ -33,14 +38,29 @@ import type * as net from "net";
 
 // Prepare the restate server
 async function prepareRestateEndpoint(
-  mountServicesFn: (server: RestateEndpoint) => void
+  param: (server: RestateEndpoint) => void
+): Promise<http2.Http2Server>;
+async function prepareRestateEndpoint(
+  param: EndpointOptions
+): Promise<http2.Http2Server>;
+async function prepareRestateEndpoint(
+  param: EndpointOptions | ((server: RestateEndpoint) => void)
 ): Promise<http2.Http2Server> {
   // Prepare RestateServer
-  const restateEndpoint = endpoint();
-  mountServicesFn(restateEndpoint);
+  let handler: (
+    request: http2.Http2ServerRequest,
+    response: http2.Http2ServerResponse
+  ) => void;
+  if (typeof param === "function") {
+    const restateEndpoint = endpoint();
+    param(restateEndpoint);
+    handler = restateEndpoint.http2Handler();
+  } else {
+    handler = createEndpointHandler(param);
+  }
 
   // Start HTTP2 server on random port
-  const restateHttpServer = http2.createServer(restateEndpoint.http2Handler());
+  const restateHttpServer = http2.createServer(handler);
   await new Promise((resolve, reject) => {
     restateHttpServer
       .listen(0)
@@ -151,14 +171,30 @@ export class RestateTestEnvironment {
     this.startedRestateHttpServer.close();
   }
 
+  /**
+   *
+   * @example
+   * ```
+   * RestateTestEnvironment.start({ services: [mysService] })
+   * ```
+   */
   public static async start(
     mountServicesFn: (server: RestateEndpoint) => void,
+    restateContainerFactory?: () => GenericContainer
+  ): Promise<RestateTestEnvironment>;
+  public static async start(
+    options: EndpointOptions,
+    restateContainerFactory?: () => GenericContainer
+  ): Promise<RestateTestEnvironment>;
+  public static async start(
+    param: EndpointOptions | ((server: RestateEndpoint) => void),
     restateContainerFactory: () => GenericContainer = () =>
       new RestateContainer()
   ): Promise<RestateTestEnvironment> {
-    const startedRestateHttpServer = await prepareRestateEndpoint(
-      mountServicesFn
-    );
+    const startedRestateHttpServer =
+      typeof param === "function"
+        ? await prepareRestateEndpoint(param)
+        : await prepareRestateEndpoint(param);
     const startedRestateContainer = await prepareRestateTestContainer(
       (startedRestateHttpServer.address() as net.AddressInfo).port,
       restateContainerFactory
diff --git a/packages/restate-sdk-zod/README.md b/packages/restate-sdk-zod/README.md
@@ -36,7 +36,7 @@ const greeter = restate.service({
 
 export type Greeter = typeof greeter;
 
-restate.endpoint().bind(greeter).listen();
+restate.serve({ services: [greeter], port: 9080 });
 ```
 
 For the SDK main package, checkout [`@restatedev/restate-sdk`](../restate-sdk).
diff --git a/packages/restate-sdk/README.md b/packages/restate-sdk/README.md
@@ -23,9 +23,7 @@ const greeter = restate.service({
     },
 });
 
-restate.endpoint()
-    .bind(greeter)
-    .listen(9080);
+restate.serve({ services: [greeter], port: 9080 });
 ```
 
 ## Community
diff --git a/packages/restate-sdk/package.json b/packages/restate-sdk/package.json
@@ -28,6 +28,16 @@
         "default": "./dist/cjs/src/public_api.js"
       }
     },
+    "./node": {
+      "import": {
+        "types": "./dist/esm/src/node.d.ts",
+        "default": "./dist/esm/src/node.js"
+      },
+      "require": {
+        "types": "./dist/cjs/src/node.d.ts",
+        "default": "./dist/cjs/src/node.js"
+      }
+    },
     "./fetch": {
       "import": {
         "types": "./dist/esm/src/fetch.d.ts",
@@ -51,6 +61,9 @@
   },
   "typesVersions": {
     "*": {
+      "node": [
+        "dist/cjs/src/node.d.ts"
+      ],
       "fetch": [
         "dist/cjs/src/fetch.d.ts"
       ],
diff --git a/packages/restate-sdk/src/common_api.ts b/packages/restate-sdk/src/common_api.ts
@@ -123,3 +123,4 @@ export type {
   LoggerContext,
   LogSource,
 } from "./logging/logger_transport.js";
+export type { EndpointOptions } from "./endpoint/types.js";
diff --git a/packages/restate-sdk/src/context.ts b/packages/restate-sdk/src/context.ts
@@ -463,7 +463,7 @@ export interface Context extends RestateContext {
    * export type Service = typeof service;
    *
    *
-   * restate.endpoint().bind(service).listen(9080);
+   * restate.serve({ services: [service], port: 9080 });
    * ```
    * *Client side:*
    * ```ts
@@ -540,7 +540,7 @@ export interface Context extends RestateContext {
    * // option 2: export the API definition with type and name (name)
    * const MyService: MyApi = { name: "myservice" };
    *
-   * restate.endpoint().bind(service).listen(9080);
+   * restate.serve({ services: [service], port: 9080 });
    * ```
    * *Client side:*
    * ```ts
diff --git a/packages/restate-sdk/src/endpoint/types.ts b/packages/restate-sdk/src/endpoint/types.ts
@@ -0,0 +1,58 @@
+import type {
+  DefaultServiceOptions,
+  LoggerTransport,
+  ServiceDefinition,
+  VirtualObjectDefinition,
+  WorkflowDefinition,
+} from "../common_api.js";
+
+/**
+ * Options for creating an endpoint handler for Node.js HTTP/2 servers.
+ */
+export interface EndpointOptions {
+  /**
+   * A list of Restate services, virtual objects, or workflows that will be exposed via the endpoint.
+   */
+  services: Array<
+    | ServiceDefinition<string, unknown>
+    | VirtualObjectDefinition<string, unknown>
+    | WorkflowDefinition<string, unknown>
+  >;
+  /**
+   * Provide a list of v1 request identity public keys eg `publickeyv1_2G8dCQhArfvGpzPw5Vx2ALciR4xCLHfS5YaT93XjNxX9` to validate
+   * incoming requests against, limiting requests to Restate clusters with the corresponding private keys. This public key format is
+   * logged by the Restate process at startup if a request identity private key is provided.
+   *
+   * If this function is called, all incoming requests irrelevant of endpoint type will be expected to have
+   * `x-restate-signature-scheme: v1` and `x-restate-jwt-v1: <valid jwt signed with one of these keys>`. If not called,
+   *
+   */
+  identityKeys?: string[];
+  /**
+   * Default service options that will be used by all services bind to this endpoint.
+   *
+   * Options can be overridden on each service/handler.
+   */
+  defaultServiceOptions?: DefaultServiceOptions;
+  /**
+   * Replace the default console-based {@link LoggerTransport}
+   * @example
+   * Using console:
+   * ```ts
+   * createEndpointHandler({ logger: (meta, message, ...o) => {console.log(`${meta.level}: `, message, ...o)}})
+   * ```
+   * @example
+   * Using winston:
+   * ```ts
+   * const logger = createLogger({ ... })
+   * createEndpointHandler({ logger: (meta, message, ...o) => {logger.log(meta.level, {invocationId: meta.context?.invocationId}, [message, ...o].join(' '))} })
+   * ```
+   * @example
+   * Using pino:
+   * ```ts
+   * const logger = pino()
+   * createEndpointHandler({ logger: (meta, message, ...o) => {logger[meta.level]({invocationId: meta.context?.invocationId}, [message, ...o].join(' '))}} )
+   * ```
+   */
+  logger?: LoggerTransport;
+}
diff --git a/packages/restate-sdk/src/endpoint/withOptions.ts b/packages/restate-sdk/src/endpoint/withOptions.ts
diff --git a/packages/restate-sdk/src/fetch.ts b/packages/restate-sdk/src/fetch.ts
diff --git a/packages/restate-sdk/src/lambda.ts b/packages/restate-sdk/src/lambda.ts
diff --git a/packages/restate-sdk/src/node.ts b/packages/restate-sdk/src/node.ts
diff --git a/packages/restate-sdk/src/public_api.ts b/packages/restate-sdk/src/public_api.ts

Original file line number	Diff line number	Diff line change
`@@ -59,4 +59,4 @@ export const counter = restate.object({`
`59`	`59`
`60`	`60`	`export type Counter = typeof counter;`
`61`	`61`
`62`		`-restate.endpoint().bind(counter).listen();`
	`62`	`+restate.serve({ services: [counter] });`
Original file line number	Diff line number	Diff line change
`@@ -120,4 +120,4 @@ const payment = restate.workflow({`
`120`	`120`
`121`	`121`	`export type PaymentWorkflow = typeof payment;`
`122`	`122`
`123`		`-restate.endpoint().bind(payment).listen();`
	`123`	`+restate.serve({ services: [payment] });`
Original file line number	Diff line number	Diff line change
`@@ -34,4 +34,4 @@ const greeter = restate.service({`
`34`	`34`
`35`	`35`	`export type Greeter = typeof greeter;`
`36`	`36`
`37`		`-restate.endpoint().bind(greeter).listen();`
	`37`	`+restate.serve({ services: [greeter] });`