@restatedev/restate-sdk 0.0.0-SNAPSHOT-20231025205407

package/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) 2023 - Restate Software, Inc., Restate GmbH
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -0,0 +1,157 @@
+# Restate Typescript SDK
+
+[Restate](https://restate.dev/) is a system for easily building resilient applications using *distributed durable async/await*. This repository contains the Restate SDK for writing services in **Node.js / Typescript**.
+
+Restate applications are composed of *durably executed, stateful RPC handlers* that can run either
+as part of long-running processes, or as FaaS (AWS Lambda).
+
+```typescript
+// note that there is no failure handling in this example, because the combination of durable execution,
+// communication, and state storage makes this unnecessary here.
+const addToCart = async (ctx: restate.RpcContext, cartId: string /* the key */, ticketId: string) => {
+  // RPC participates in durable execution, so guaranteed to eventually happend and
+  // will never get duplicated. would suspend if the other takes too long
+  const success = await ctx.rpc<ticketApi>({ path: "tickets" }).reserve(ticketId);
+
+  if (success) {
+    const cart = (await ctx.get<string[]>("cart")) || []; // gets state 'cart' bound to current cartId
+    cart.push(ticketId);
+    ctx.set("cart", cart);                                // writes state bound to current cartId
+
+    // reliable delayed call sent from Restate, which also participaes in durable execution
+    ctx.sendDelayed<cartApi>({path: "cart"}, minutes(15)).expireTicket(ticketId);
+  }
+  return success;
+}
+
+...
+
+restate
+  .createServer()
+  .bindKeyedRouter("cart", restate.keyedRouter({ addToCart, expireTicket }))
+  .listen(9080);
+```
+
+Restate takes care of:
+  - **reliable execution:** handlers will always run to completion. Intermediate failures result in re-tries
+    that use the *durable execution* mechanism to recover partial progress and not duplicate already executed
+    steps.
+  - **suspending handlers:** long-running handlers suspend when awaiting on a promise (or when explicitly
+    sleeping) and resume when that promise is resolved. Lambdas finish, services may scale down.
+  - **reliable communication:** handlers communicate with *exactly-once semantics*. Restate reliably delivers
+    messages and anchors both sender and receiver in the durable execution to ensure no losses or duplicates
+    can happen.
+  - **durable timers:** handlers can sleep (and suspend) or schedule calls for later.
+  - **isolation:** handlers can be keyed, which makes Restate scheduled them to obey single-writer-per-key
+    semantics.
+  - **state:** keyed handlers can attach key/value state, which is eagerly pushed into handlers during
+    invocation, and written back upon completion. This is particularly efficient for FaaS deployments
+    (stateful serverless, yay!).
+  - **observability & introspection:** Restate automatically generates Open Telemetry traces for the
+    interactions between handlers and gives you a SQL shell to query the distributed state of the application.
+  - **gRPC support:** Handlers may optionally be defined as gRPC services, and Restate will act as the transport
+    layer for the services/clients in that case.
+
+Check [Restate GitHub](https://github.com/restatedev/) or the [docs](https://docs.restate.dev/) for further details.
+
+# Using the SDK
+
+To use this SDK, simply add the dependency to your project:
+```shell
+npm install @restatedev/restate-sdk
+```
+
+For brand-new projects, we recommend using the [Restate Node Template](https://github.com/restatedev/node-template-generator):
+```shell
+npx -y @restatedev/create-app
+```
+
+# Contributing to the SDK
+
+### Prerequisites
+- [NodeJS (and npm)](https://nodejs.org) installed
+
+### Building the SDK
+
+Install the dependencies, build the Restate protocol types (from ProtoBuf), and transpile the TypeScript code:
+```shell
+npm install
+npm run proto
+npm run build
+```
+
+If everything goes well, the artifact would be created at `dist/`.
+
+### Testing Changes
+
+Run the tests via
+```shell
+npm run test
+```
+
+Run the formatter and linter via
+```shell
+npm run format
+npm run lint
+```
+
+Launch a sample program (requires no build)
+```shell
+npm run example
+```
+
+### Testing end-to-end with Restate Runtime
+
+This requires the [Docker Engine](https://docs.docker.com/engine/install/) to launch the Restate runtime for testing.
+
+Start the runtime in a Docker container and tell Restate about the example service. This requires the example to be running, to make the discovery succeed!
+ - On Linux:
+    ```shell
+    docker run --name restate_dev --rm --network=host ghcr.io/restatedev/restate-dist:latest
+
+    curl -X POST http://localhost:9070/endpoints -H 'content-type: application/json' -d '{"uri": "http://localhost:9080"}'
+    ```
+- On macOS:
+    ```shell
+    docker run --name restate_dev --rm -p 9070:9070 -p 8080:8080 ghcr.io/restatedev/restate-dist:latest
+
+    curl -X POST http://localhost:9070/endpoints -H 'content-type: application/json' -d '{"uri": "http://host.docker.internal:9080"}'
+    ```
+
+
+Invoke the example service from the command line:
+```shell
+curl -X POST http://localhost:8080/greeter/greet -H 'content-type: application/json' -d '{"name": "Pete"}'
+```
+
+# Releasing the package
+
+## Releasing via release-it
+
+Releasing a new npm package from this repo requires:
+
+* [SSH access configured for Github](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) in order to push commits and tags to GitHub
+* A GitHub personal access token with access to https://github.com/restatedev/sdk-typescript in your environment as `GITHUB_TOKEN` in order to create a Github release
+
+
+```bash
+npm run release
+# now select what type of release you want to do and say yes to the rest of the options
+```
+
+The actual `npm publish` is run by GitHub actions once a GitHub release is created.
+
+## Releasing manually
+
+1. Bump the version field in package.json to `X.Y.Z`
+2. Create and push a tag of the form `vX.Y.Z` to the upstream repository
+3. [Create a new GitHub release](https://github.com/restatedev/sdk-typescript/releases)
+
+Creating the GitHub release will trigger `npm publish` via GitHub actions.
+
+After having created a new SDK release, you need to:
+
+1. [Update and release the tour of Restate](https://github.com/restatedev/tour-of-restate-typescript#upgrading-typescript-sdk)
+2. [Update the Typescript SDK and Tour version in the documentation and release it](https://github.com/restatedev/documentation#upgrading-typescript-sdk-version)
+3. [Update and release the Node template generator](https://github.com/restatedev/node-template-generator#upgrading-typescript-sdk)
+4. [Update the examples](https://github.com/restatedev/examples#upgrading-the-sdk-dependency-for-restate-developers)

package/dist/connection/connection.d.ts

@@ -0,0 +1,19 @@
+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;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection/connection.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAEnC,iBAAiB,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAElC,iBAAiB,IAAI,IAAI,CAAC;CAC3B"}

package/dist/connection/connection.js

@@ -0,0 +1,13 @@
+"use strict";
+/*
+ * Copyright (c) 2023 - 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=connection.js.map

package/dist/connection/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/connection/connection.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/connection/embedded_connection.d.ts

@@ -0,0 +1,22 @@
+import { RemoteContext } from "../generated/proto/services";
+import { Message } from "../types/types";
+import { Connection } from "./connection";
+export declare class FencedOffError extends Error {
+    constructor();
+}
+export declare class InvocationAlreadyCompletedError extends Error {
+    constructor();
+}
+export declare class EmbeddedConnection implements Connection {
+    private readonly operationId;
+    private readonly streamId;
+    private readonly remote;
+    private queue;
+    private flushing;
+    constructor(operationId: string, streamId: string, remote: RemoteContext);
+    send(msg: Message): Promise<void>;
+    end(): Promise<void>;
+    private scheduleFlush;
+    private flush;
+}
+//# sourceMappingURL=embedded_connection.d.ts.map

package/dist/connection/embedded_connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded_connection.d.ts","sourceRoot":"","sources":["../../src/connection/embedded_connection.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,qBAAa,cAAe,SAAQ,KAAK;;CAIxC;AAED,qBAAa,+BAAgC,SAAQ,KAAK;;CAIzD;AAED,qBAAa,kBAAmB,YAAW,UAAU;IAKjD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAoC;gBAGjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa;IAGxC,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAKpB,OAAO,CAAC,aAAa;YASP,KAAK;CAoBpB"}

package/dist/connection/embedded_connection.js

@@ -0,0 +1,78 @@
+"use strict";
+/*
+ * Copyright (c) 2023 - 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbeddedConnection = exports.InvocationAlreadyCompletedError = exports.FencedOffError = void 0;
+const encoder_1 = require("../io/encoder");
+class FencedOffError extends Error {
+    constructor() {
+        super("FencedOff");
+    }
+}
+exports.FencedOffError = FencedOffError;
+class InvocationAlreadyCompletedError extends Error {
+    constructor() {
+        super("Completed");
+    }
+}
+exports.InvocationAlreadyCompletedError = InvocationAlreadyCompletedError;
+class EmbeddedConnection {
+    operationId;
+    streamId;
+    remote;
+    queue = [];
+    flushing = Promise.resolve();
+    constructor(operationId, streamId, remote) {
+        this.operationId = operationId;
+        this.streamId = streamId;
+        this.remote = remote;
+    }
+    send(msg) {
+        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());
+        }
+        // tag along to the previously scheduled flush.
+        return this.flushing;
+    }
+    end() {
+        this.flushing = this.flushing.then(() => this.flush());
+        return this.flushing;
+    }
+    scheduleFlush() {
+        // schedule a flush at the end of the current event loop iteration.
+        return new Promise((resolve, reject) => setImmediate(() => {
+            this.flush().then(resolve).catch(reject);
+        }));
+    }
+    async flush() {
+        if (this.queue.length === 0) {
+            return Promise.resolve();
+        }
+        const buffer = (0, encoder_1.encodeMessages)(this.queue);
+        this.queue = [];
+        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();
+        }
+    }
+}
+exports.EmbeddedConnection = EmbeddedConnection;
+//# sourceMappingURL=embedded_connection.js.map

package/dist/connection/embedded_connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded_connection.js","sourceRoot":"","sources":["../../src/connection/embedded_connection.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAGH,2CAA+C;AAI/C,MAAa,cAAe,SAAQ,KAAK;IACvC;QACE,KAAK,CAAC,WAAW,CAAC,CAAC;IACrB,CAAC;CACF;AAJD,wCAIC;AAED,MAAa,+BAAgC,SAAQ,KAAK;IACxD;QACE,KAAK,CAAC,WAAW,CAAC,CAAC;IACrB,CAAC;CACF;AAJD,0EAIC;AAED,MAAa,kBAAkB;IAKV;IACA;IACA;IANX,KAAK,GAAc,EAAE,CAAC;IACtB,QAAQ,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEpD,YACmB,WAAmB,EACnB,QAAgB,EAChB,MAAqB;QAFrB,gBAAW,GAAX,WAAW,CAAQ;QACnB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAe;IACrC,CAAC;IAEJ,IAAI,CAAC,GAAY;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,CAAC,EAAE;YACb,2DAA2D;YAC3D,kDAAkD;YAClD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;SAChE;QACD,+CAA+C;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,aAAa;QACnB,mEAAmE;QACnE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CACrC,YAAY,CAAC,GAAG,EAAE;YAChB,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3C,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;YAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;SAC1B;QACD,MAAM,MAAM,GAAG,IAAA,wBAAc,EAAC,IAAI,CAAC,KAAK,CAAW,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAEhB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACjC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QAEH,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS,EAAE;YACnC,MAAM,IAAI,cAAc,EAAE,CAAC;SAC5B;QACD,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,EAAE;YACzC,MAAM,IAAI,+BAA+B,EAAE,CAAC;SAC7C;IACH,CAAC;CACF;AAvDD,gDAuDC"}

package/dist/connection/http_connection.d.ts

@@ -0,0 +1,73 @@
+/// <reference types="node" />
+import stream from "stream";
+import { Connection, RestateStreamConsumer } from "./connection";
+import { Message } from "../types/types";
+/**
+ * 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 declare class RestateHttp2Connection implements Connection {
+    private readonly rawStream;
+    /**
+     * create a RestateDuplex stream from an http2 (duplex) stream.
+     */
+    static from(http2stream: stream.Duplex): RestateHttp2Connection;
+    private readonly sdkInput;
+    private readonly sdkOutput;
+    private currentConsumer;
+    private inputBuffer;
+    private consumerError?;
+    private consumerInputClosed;
+    constructor(rawStream: stream.Duplex);
+    /**
+     * 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.
+     */
+    pipeToConsumer(consumer: RestateStreamConsumer): void;
+    /**
+     * Removes the current consumer, if there is one.
+     */
+    removeCurrentConsumer(): void;
+    /**
+     * 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.
+     */
+    send(msg: Message): Promise<void>;
+    /**
+     * Ends the stream, awaiting pending writes.
+     */
+    end(): Promise<void>;
+}
+//# sourceMappingURL=http_connection.d.ts.map

package/dist/connection/http_connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_connection.d.ts","sourceRoot":"","sources":["../../src/connection/http_connection.ts"],"names":[],"mappings":";AAWA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAG5B,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAOzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,sBAAuB,YAAW,UAAU;IAuB3C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAtBtC;;OAEG;WACW,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,GAAG,sBAAsB;IAOtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAI3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAG5C,OAAO,CAAC,eAAe,CAAsC;IAC7D,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,aAAa,CAAC,CAAQ;IAC9B,OAAO,CAAC,mBAAmB,CAAS;gBAEP,SAAS,EAAE,MAAM,CAAC,MAAM;IAuErD;;;;;;;;OAQG;IACI,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IA+B5D;;OAEG;IACI,qBAAqB,IAAI,IAAI;IAQpC;;;;;;;;;;;;OAYG;IACI,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;OAEG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAUlC"}

package/dist/connection/http_connection.js

@@ -0,0 +1,203 @@
+"use strict";
+/*
+ * Copyright (c) 2023 - 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RestateHttp2Connection = void 0;
+const encoder_1 = require("../io/encoder");
+const decoder_1 = require("../io/decoder");
+const logger_1 = require("../utils/logger");
+const promises_1 = require("stream/promises");
+// utility promise, for cases where we want to save allocation of an extra promise
+const RESOLVED = 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).
+ */
+class RestateHttp2Connection {
+    rawStream;
+    /**
+     * create a RestateDuplex stream from an http2 (duplex) stream.
+     */
+    static from(http2stream) {
+        return new RestateHttp2Connection(http2stream);
+    }
+    // --------------------------------------------------------------------------
+    // input as decoded messages
+    sdkInput;
+    // output as encoded bytes. we convert manually, not as transforms,
+    // to skip a layer of stream indirection
+    sdkOutput;
+    // consumer handling
+    currentConsumer = null;
+    inputBuffer = [];
+    consumerError;
+    consumerInputClosed = false;
+    constructor(rawStream) {
+        this.rawStream = rawStream;
+        this.sdkInput = rawStream.pipe((0, decoder_1.streamDecoder)());
+        this.sdkOutput = rawStream;
+        // remember and forward messages
+        this.sdkInput.on("data", (m) => {
+            // 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) => {
+            // 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", () => {
+            logger_1.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) => {
+            logger_1.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) => {
+            logger_1.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.
+     */
+    pipeToConsumer(consumer) {
+        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.
+     */
+    removeCurrentConsumer() {
+        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.
+     */
+    send(msg) {
+        const encodedMessage = (0, encoder_1.encodeMessage)(msg);
+        const hasMoreCapacity = this.sdkOutput.write(encodedMessage);
+        if (hasMoreCapacity) {
+            return RESOLVED;
+        }
+        return new Promise((resolve) => {
+            this.sdkOutput.once("drain", resolve);
+        });
+    }
+    /**
+     * Ends the stream, awaiting pending writes.
+     */
+    async end() {
+        this.sdkOutput.end();
+        const options = {
+            error: true,
+            cleanup: true,
+        };
+        await (0, promises_1.finished)(this.rawStream, options);
+    }
+}
+exports.RestateHttp2Connection = RestateHttp2Connection;
+//# sourceMappingURL=http_connection.js.map

package/dist/connection/http_connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_connection.js","sourceRoot":"","sources":["../../src/connection/http_connection.ts"],"names":[],"mappings":"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"}

package/dist/connection/lambda_connection.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import { Connection } from "./connection";
+import { Message } from "../types/types";
+export declare class LambdaConnection implements Connection {
+    private outputBuffer;
+    private suspendedOrCompleted;
+    private readonly completionPromise;
+    private resolveOnCompleted;
+    constructor();
+    send(msg: Message): Promise<void>;
+    getResult(): Promise<Buffer>;
+    end(): Promise<void>;
+}
+//# sourceMappingURL=lambda_connection.d.ts.map

package/dist/connection/lambda_connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lambda_connection.d.ts","sourceRoot":"","sources":["../../src/connection/lambda_connection.ts"],"names":[],"mappings":";AAWA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAM1C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAKzC,qBAAa,gBAAiB,YAAW,UAAU;IAEjD,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,oBAAoB,CAAS;IAGrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkB;IACpD,OAAO,CAAC,kBAAkB,CAAiD;;IAU3E,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAQrB"}