@empyria/restate 0.4.8 → 0.4.10

package/README.md

@@ -50,6 +50,7 @@ import { checkServiceHandler } from '@empyria/restate/lib/Admin.js'
 | [lib/Cron.js](./lib/Cron.js)             | `cronJobInitiator`/`cronJob` — Restate services implementing cron-driven, replay-safe recurring job scheduling on top of `croner`.                                                                                                                                                                     |
 | [lib/Pubsub.js](./lib/Pubsub.js)         | `definePubsub` (register a pubsub Virtual Object on your endpoint), `pubsubPublisher` (publish into it from inside a handler, in-process), `pubsubClient` (publish/pull/subscribe to it from anywhere else, over the network) — thin wrappers around `@restatedev/pubsub`/`@restatedev/pubsub-client`. |
 | [lib/Validation.js](./lib/Validation.js) | `withValidation` — wraps a workflow handler with input/output JSON schema validation via `@empyria/common`.                                                                                                                                                                                            |
+| [lib/Endpoint.js](./lib/Endpoint.js)     | `serveEndpoint` — serves services/workflows over HTTP/2 without registering itself or deleting its deployment on exit (for a supervisor that registers the address).                                                                                                                                   |
 
 ## Agents: `@empyria/restate/agent`
 
@@ -121,6 +122,13 @@ endpoint, then create jobs with either:
 Cron expressions are `croner` patterns (five fields, or six with seconds for tests). The target handler is sent the
 `payload` as its input, or no input when there is none.
 
+### An endpoint that does not register itself
+
+`setupRestate` serves, registers the deployment, and deletes it again on SIGINT/SIGTERM. When something else owns
+registration (a supervisor that registers a process's address once and restarts the process), use
+`serveEndpoint({port, services})` instead: it only serves. Invocations already running on a deployment are pinned to its
+address, so the deployment must survive the process stopping and come back at the same address.
+
 ### Shaping an agent
 
 `defineAgent` options beyond the basics:

package/index.js

@@ -7,3 +7,5 @@ export * from './lib/Admin.js'
 export * from './lib/Caller.js'
 
 export * from './lib/Pubsub.js'
+
+export * from './lib/Endpoint.js'

package/lib/Endpoint.js

@@ -0,0 +1,28 @@
+import http2 from 'node:http2'
+import * as restate from '@restatedev/restate-sdk'
+
+/**
+ * An endpoint that only serves: the given services/workflows over HTTP/2 on `port`, and nothing else.
+ * Unlike `setupRestate` it does not register with Restate and does not delete its deployment when it stops. Use it
+ * when something else owns registration, for example a supervisor that registers the address once and restarts the
+ * process: workflows already running on a deployment are pinned to its address and must be able to wait for it to
+ * come back. It stops accepting connections on SIGINT/SIGTERM.
+ *
+ * @param {{port: number, services: Parameters<typeof restate.createEndpointHandler>[0]['services']}} params
+ * @returns {Promise<import('node:http2').Http2Server>} resolves once it is listening
+ */
+export async function serveEndpoint({ port, services }) {
+	const server = http2.createServer(restate.createEndpointHandler({ services }))
+	await new Promise((resolve, reject) => {
+		server.once('error', reject)
+		server.listen(port, resolve)
+	})
+	// Open sessions from Restate would keep close() waiting; in-flight calls are retried by Restate anyway.
+	const stop = () => {
+		server.close()
+		setTimeout(() => process.exit(0), 1000)
+	}
+	process.once('SIGINT', stop)
+	process.once('SIGTERM', stop)
+	return server
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.8",
+	"version": "0.4.10",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -27,7 +27,7 @@
 	},
 	"dependencies": {
 		"@empyria/classification": "0.1.9",
-		"@empyria/common": "0.3.9",
+		"@empyria/common": "0.3.10",
 		"@restatedev/pubsub": "0.3.2",
 		"@restatedev/pubsub-client": "0.3.2",
 		"@restatedev/restate-sdk": "1.17.2",

package/test/Endpoint.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import http2 from 'node:http2'
+import * as restate from '@restatedev/restate-sdk'
+import { serveEndpoint } from '../lib/Endpoint.js'
+
+describe('serveEndpoint', () => {
+	test('listens over HTTP/2 and answers Restate discovery, without registering anywhere', async () => {
+		const hello = restate.service({ name: 'Hello', handlers: { hi: async () => 'hi' } })
+		const server = await serveEndpoint({ port: 0, services: [hello] })
+		const { port } = server.address()
+		const client = http2.connect(`http://127.0.0.1:${port}`)
+		const body = await new Promise((resolve, reject) => {
+			const req = client.request({
+				':path': '/discover',
+				accept: 'application/vnd.restate.endpointmanifest.v3+json',
+			})
+			let text = ''
+			req.on('data', (chunk) => (text += chunk))
+			req.on('end', () => resolve(text))
+			req.on('error', reject)
+			req.end()
+		})
+		client.close()
+		server.close()
+		expect(JSON.parse(body).services.map((s) => s.name)).toEqual(['Hello'])
+	})
+
+	test('fails when the port is taken', async () => {
+		const first = await serveEndpoint({ port: 0, services: [] })
+		const { port } = first.address()
+		await expect(serveEndpoint({ port, services: [] })).rejects.toThrow()
+		first.close()
+	})
+})