@restatedev/restate-sdk v0.9.2
Restate Typescript SDK
Restate 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).
// 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 or the docs for further details.
Using the SDK
To use this SDK, simply add the dependency to your project:
npm install @restatedev/restate-sdk
For brand-new projects, we recommend using the Restate Node Template:
npx -y @restatedev/create-app
Contributing to the SDK
Prerequisites
- NodeJS (and npm) installed
Building the SDK
Install the dependencies, build the Restate protocol types (from ProtoBuf), and transpile the TypeScript code:
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
npm run test
Run the formatter and linter via
npm run format
npm run lint
Launch a sample program (requires no build)
npm run example
Testing end-to-end with Restate Runtime
This requires the Docker Engine 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:
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:
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:
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 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
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
- Bump the version field in package.json to
X.Y.Z
- Create and push a tag of the form
vX.Y.Z
to the upstream repository - Create a new GitHub release
Creating the GitHub release will trigger npm publish
via GitHub actions.
After having created a new SDK release, you need to:
2 days ago
7 days ago
15 days ago
14 days ago
14 days ago
14 days ago
14 days ago
14 days ago
16 days ago
18 days ago
18 days ago
18 days ago
20 days ago
19 days ago
19 days ago
22 days ago
22 days ago
23 days ago
27 days ago
26 days ago
27 days ago
27 days ago
27 days ago
28 days ago
27 days ago
28 days ago
29 days ago
30 days ago
30 days ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago