@empyria/restate 0.4.7 → 0.4.9

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/Admin.js

@@ -409,6 +409,44 @@ export async function pollInvocation({ restateURL, invocationId, intervalMs = 25
 	}
 }
 
+/**
+ * Looks once, without waiting, at the result of an invocation (the `/output` endpoint).
+ *
+ * - `running`: no result yet
+ * - `done`: it finished; `output` is its result
+ * - `failed`: it ended in an error; `code` and `message` come from Restate
+ * - `unknown`: Restate has no such invocation (never existed, or its result was kept long enough and is gone)
+ * @param {{restateURL: string, invocationId: string}} params
+ * @returns {Promise<{state: 'running'}|{state: 'done', output: unknown}|{state: 'failed', code: number, message: string}|{state: 'unknown'}>}
+ */
+export async function getInvocationOutput({ restateURL, invocationId }) {
+	const response = await fetch(`${restateURL}/restate/invocation/${invocationId}/output`)
+	if (response.status === 470) return { state: 'running' }
+
+	const text = await response.text()
+	let body
+	try {
+		body = text ? JSON.parse(text) : undefined
+	} catch {
+		body = undefined
+	}
+
+	if (response.ok) return { state: 'done', output: body }
+	// An error of the invocation itself carries `source: 'invocation'`; anything else is the ingress saying it
+	// does not know the invocation, or could not look.
+	if (body?.source === 'invocation') {
+		return {
+			state: 'failed',
+			code: Number(body.code ?? response.status),
+			message: String(body.message ?? response.statusText),
+		}
+	}
+	if (response.status === 400 || response.status === 404) return { state: 'unknown' }
+	throw new Error(
+		`Unexpected status ${response.status} reading invocation '${invocationId}': ${response.statusText}`,
+	)
+}
+
 /**
  * Request headers for an ingress call, adding Restate's `idempotency-key` when given.
  * @param {string} [idempotencyKey]
@@ -791,6 +829,7 @@ export const sendMessageAsynSafe = async ({ restateURL, callerParams, timeout })
  * @property {() => (message: WorkflowMessage) => Promise<InvocationSubmission>} submitWorkflowDiscovery
  * @property {(params: {invocationId: string}) => Promise<*>} waitForInvocation
  * @property {(params: {invocationId: string, intervalMs?: number}) => Promise<*>} pollInvocation
+ * @property {(params: {invocationId: string}) => Promise<Awaited<ReturnType<typeof getInvocationOutput>>>} getInvocationOutput
  * @property {(params: Omit<ServiceMessage, 'restateURL'>) => Promise<*>} sendMessage
  * @property {(params: Omit<ServiceMessage, 'restateURL'>) => Promise<InvocationSubmission>} sendMessageAsync
  * @property {() => (message: ServiceMessage) => Promise<*>} sendMessageWithDiscovery
@@ -833,6 +872,8 @@ export function createRestateAdmin({ restateAdminURL, restateURL }) {
 		pollInvocation: ({ invocationId, intervalMs }) =>
 			pollInvocation({ restateURL, invocationId, intervalMs }),
 
+		getInvocationOutput: ({ invocationId }) => getInvocationOutput({ restateURL, invocationId }),
+
 		sendMessage: ({ name, message, key, payload, idempotencyKey }) =>
 			sendMessage({ restateURL, name, message, key, payload, idempotencyKey }),
 		sendMessageAsync: ({ name, message, key, payload, idempotencyKey }) =>

package/lib/Cron.js

@@ -10,6 +10,18 @@ export const setJobStateName = (jobStateName) => {
 	return JOB_STATE_NAME
 }
 
+/**
+ * A retry policy that never gives up: it backs off to one attempt a minute and keeps trying. Restate's default
+ * stops after a few attempts and *pauses* the invocation, and a paused invocation of a virtual object holds the
+ * object's lock, so every later call queues behind it for ever. A schedule that was due while the services were
+ * down (a restart, a crash, a night off) must simply run when they are back, so jobs use this.
+ */
+export const RETRY_FOREVER = {
+	initialInterval: { seconds: 1 },
+	maxInterval: { minutes: 1 },
+	exponentiationFactor: 2,
+}
+
 export const cronJobInitiator = restate.service({
 	name: 'CronJobInitiator',
 	handlers: {
@@ -25,6 +37,7 @@ export const cronJobInitiator = restate.service({
 
 export const cronJob = restate.object({
 	name: 'CronJob',
+	options: { retryPolicy: RETRY_FOREVER },
 	handlers: {
 		initiate: async (ctx, request) => {
 			if (await ctx.get(JOB_STATE_NAME)) {

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.7",
+	"version": "0.4.9",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",

package/test/Admin.test.js

@@ -14,6 +14,7 @@ import {
 	submitWorkflowDiscovery,
 	waitForInvocation,
 	pollInvocation,
+	getInvocationOutput,
 	sendMessage,
 	sendMessageAsync,
 	sendMessageWithDiscovery,
@@ -314,6 +315,40 @@ describe('submitWorkflowDiscovery', () => {
 	})
 })
 
+describe('getInvocationOutput', () => {
+	const look = (response) => {
+		globalThis.fetch = mock(async () => response)
+		return getInvocationOutput({ restateURL: 'http://ingress', invocationId: 'inv-1' })
+	}
+
+	test('done: returns the output', async () => {
+		expect(await look(jsonResponse({ a: 1 }))).toEqual({ state: 'done', output: { a: 1 } })
+	})
+
+	test('running: 470 means no result yet', async () => {
+		expect(await look(jsonResponse(null, false, 470))).toEqual({ state: 'running' })
+	})
+
+	test('failed: an error of the invocation itself', async () => {
+		const body = { code: 404, message: 'no such skill', source: 'invocation' }
+		expect(await look(jsonResponse(body, false, 404))).toEqual({
+			state: 'failed',
+			code: 404,
+			message: 'no such skill',
+		})
+	})
+
+	test('unknown: the ingress does not know the invocation', async () => {
+		expect(await look(jsonResponse({ message: 'x', source: 'ingress' }, false, 400))).toEqual({
+			state: 'unknown',
+		})
+	})
+
+	test('anything else is an error', async () => {
+		await expect(look(jsonResponse(null, false, 503))).rejects.toThrow('503')
+	})
+})
+
 describe('waitForInvocation / pollInvocation', () => {
 	test('waitForInvocation returns the attach result', async () => {
 		globalThis.fetch = mock(async () => jsonResponse({ done: true }))

package/test/Cron.test.js

@@ -291,3 +291,11 @@ describe('ensureCronJob', () => {
 		).rejects.toThrow('500')
 	})
 })
+
+describe('retry policy', () => {
+	test('a job never gives up: no attempt limit, so it is never paused', async () => {
+		const { RETRY_FOREVER } = await import('../lib/Cron.js')
+		expect(RETRY_FOREVER.maxAttempts).toBeUndefined()
+		expect(cronJob.options?.retryPolicy ?? cronJob.retryPolicy).toBeDefined()
+	})
+})

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()
+	})
+})