@empyria/restate 0.1.20 → 0.1.22

package/lib/Admin.js

@@ -212,15 +212,54 @@ export async function listHandlers({ restateAdminURL, name }) {
  * @property {object} payload
  * @typedef {BaseMessage & {key: string}} WorkflowMessage Message targeting a Restate
  *   workflow — `key` is required to address the workflow instance.
- * @typedef {BaseMessage & {key?: string, message: string}} ServiceMessage Message
- *   targeting a Restate service or virtual object handler. `key` is the Virtual
- *   Object key (omit for plain services); `message` is the handler name.
+ * @typedef {BaseMessage & {key?: string, message: string, idempotencyKey?: string}} ServiceMessage
+ *   Message targeting a Restate service or virtual object handler. `key` is the Virtual
+ *   Object key (omit for plain services); `message` is the handler name. `idempotencyKey`,
+ *   when set, is sent as Restate's `idempotency-key` header: resending the same message
+ *   with the same key (e.g. after a network timeout) attaches to the original invocation
+ *   instead of running the handler twice.
  * @typedef {Object} InvocationSubmission Response returned by Restate when an
  *   invocation is enqueued asynchronously.
  * @property {string} invocationId
  * @property {'Accepted'|'PreviouslyAccepted'} status
  */
 
+/**
+ * Separator {@link childKey} joins key segments with. Not `/`: keys are interpolated
+ * straight into ingress URL paths (see {@link submitWorkflow}), where a `/` would split
+ * the key into extra path segments.
+ */
+export const CHILD_KEY_SEPARATOR = ':'
+
+/**
+ * Derives a sub-workflow's key deterministically from its parent's, so a replayed parent
+ * addresses the very same child instead of starting a new one. Never use a random ID
+ * for a child: a workflow's `run` executes once per key, and the key is what makes the
+ * call idempotent across replays.
+ *
+ *   childKey('order-42', 'approval')        // 'order-42:approval'
+ *   childKey('order-42', 'shipment', 3)     // 'order-42:shipment:3'
+ * @param {string} parentKey key of the calling workflow (`ctx.key`)
+ * @param {string} nodePath stable name of the calling step within the parent's flow
+ * @param {number|string} [iteration] loop index, when the step runs more than once
+ * @returns {string}
+ * @throws {TypeError} If a segment is empty or contains {@link CHILD_KEY_SEPARATOR} or `/`.
+ */
+export function childKey(parentKey, nodePath, iteration) {
+	const segments = iteration === undefined ? [nodePath] : [nodePath, String(iteration)]
+	for (const segment of segments) {
+		if (typeof segment !== 'string' || segment === '' || /[:/]/.test(segment)) {
+			throw new TypeError(
+				`Invalid child key segment '${segment}': must be a non-empty string without '${CHILD_KEY_SEPARATOR}' or '/'`,
+			)
+		}
+	}
+	if (typeof parentKey !== 'string' || parentKey === '') {
+		throw new TypeError('childKey requires a non-empty parentKey')
+	}
+	return [parentKey, ...segments].join(CHILD_KEY_SEPARATOR)
+}
+
 /**
  * Starts a sub-workflow and returns a handle to the invocation. Submitting against a
  * `workflowKey` that already has a running or completed workflow is a safe no-op on
@@ -280,7 +319,10 @@ export function callSubWorkflow(ctx, workflowName, workflowKey, payload) {
  * @param {Object} options
  * @param {string} options.restateURL - Restate endpoint URL
  * @param {string} options.name - Workflow name
- * @param {string} [options.key] - Unique workflow instance key
+ * @param {string} [options.key] - Unique workflow instance key. This is also the workflow's
+ *   idempotency key: resubmitting the same key is `PreviouslyAccepted`, not a second run.
+ *   Omitting it generates a random key, so a retried submission starts a duplicate run —
+ *   pass a business key (e.g. the order ID) whenever the caller may retry.
  * @param {TPayload} options.payload - Request payload
  * @returns {Promise<InvocationSubmission>}
  */
@@ -366,17 +408,28 @@ export async function pollInvocation({ restateURL, invocationId, intervalMs = 25
 	}
 }
 
+/**
+ * Request headers for an ingress call, adding Restate's `idempotency-key` when given.
+ * @param {string} [idempotencyKey]
+ * @returns {Record<string, string>}
+ */
+function ingressHeaders(idempotencyKey) {
+	const headers = { 'Content-Type': 'application/json' }
+	if (idempotencyKey) headers['idempotency-key'] = idempotencyKey
+	return headers
+}
+
 /**
  * Sends a message to a Restate service with configurable retry policy.
  * @template TResult
  * @param {ServiceMessage} params
  * @returns {Promise<TResult>}
  */
-export async function sendMessage({ restateURL, name, message, key, payload }) {
+export async function sendMessage({ restateURL, name, message, key, payload, idempotencyKey }) {
 	const path = key ? `${name}/${key}/${message}` : `${name}/${message}`
 	const response = await fetch(`${restateURL}/${path}`, {
 		method: 'POST',
-		headers: { 'Content-Type': 'application/json' },
+		headers: ingressHeaders(idempotencyKey),
 		body: JSON.stringify(payload),
 	})
 
@@ -395,11 +448,18 @@ export async function sendMessage({ restateURL, name, message, key, payload }) {
  * @param {ServiceMessage} params
  * @returns {Promise<InvocationSubmission>}
  */
-export async function sendMessageAsync({ restateURL, name, message, key, payload }) {
+export async function sendMessageAsync({
+	restateURL,
+	name,
+	message,
+	key,
+	payload,
+	idempotencyKey,
+}) {
 	const path = key ? `${name}/${key}/${message}` : `${name}/${message}`
 	const response = await fetch(`${restateURL}/${path}/send`, {
 		method: 'POST',
-		headers: { 'Content-Type': 'application/json' },
+		headers: ingressHeaders(idempotencyKey),
 		body: JSON.stringify(payload),
 	})
 
@@ -429,10 +489,10 @@ export async function sendMessageAsync({ restateURL, name, message, key, payload
  * @returns {(message: ServiceMessage) => Promise<TResult>}
  */
 export function sendMessageWithDiscovery({ restateAdminURL }) {
-	return async ({ restateURL, name, message, key, payload }) => {
+	return async ({ restateURL, name, message, key, payload, idempotencyKey }) => {
 		await checkServiceHandler(restateAdminURL, name, message)
 
-		return sendMessage({ restateURL, name, message, key, payload })
+		return sendMessage({ restateURL, name, message, key, payload, idempotencyKey })
 	}
 }
 
@@ -443,10 +503,10 @@ export function sendMessageWithDiscovery({ restateAdminURL }) {
  * @returns {(message: ServiceMessage) => Promise<InvocationSubmission>}
  */
 export function sendMessageAsyncWithDiscovery({ restateAdminURL }) {
-	return async ({ restateURL, name, message, key, payload }) => {
+	return async ({ restateURL, name, message, key, payload, idempotencyKey }) => {
 		await checkServiceHandler(restateAdminURL, name, message)
 
-		return sendMessageAsync({ restateURL, name, message, key, payload })
+		return sendMessageAsync({ restateURL, name, message, key, payload, idempotencyKey })
 	}
 }
 
@@ -772,10 +832,10 @@ export function createRestateAdmin({ restateAdminURL, restateURL }) {
 		pollInvocation: ({ invocationId, intervalMs }) =>
 			pollInvocation({ restateURL, invocationId, intervalMs }),
 
-		sendMessage: ({ name, message, key, payload }) =>
-			sendMessage({ restateURL, name, message, key, payload }),
-		sendMessageAsync: ({ name, message, key, payload }) =>
-			sendMessageAsync({ restateURL, name, message, key, payload }),
+		sendMessage: ({ name, message, key, payload, idempotencyKey }) =>
+			sendMessage({ restateURL, name, message, key, payload, idempotencyKey }),
+		sendMessageAsync: ({ name, message, key, payload, idempotencyKey }) =>
+			sendMessageAsync({ restateURL, name, message, key, payload, idempotencyKey }),
 		sendMessageWithDiscovery: () => sendMessageWithDiscovery({ restateAdminURL }),
 		sendMessageAsyncWithDiscovery: () => sendMessageAsyncWithDiscovery({ restateAdminURL }),
 	}

package/lib/Validation.js

@@ -1,3 +1,4 @@
+import { TerminalError } from '@restatedev/restate-sdk'
 import { createValidator } from '@empyria/common'
 
 /**
@@ -15,6 +16,14 @@ import { createValidator } from '@empyria/common'
  * that doesn't match the declared output type, the error is caught before
  * Restate records the result.
  *
+ * Validation failures are thrown as `TerminalError`, never as the plain
+ * `ValidationError` `@empyria/common` raises: Restate retries any non-terminal
+ * error indefinitely, and a payload that failed validation once fails it on
+ * every retry. Input failures carry errorCode 400 (the caller's fault), output
+ * failures 500 (the handler's fault) — Restate propagates the code to an
+ * ingress caller as the HTTP status. Errors thrown by `handler` itself are left
+ * untouched, so transient failures there are still retried.
+ *
  * Usage:
  *   handlers: {
  *     run: withValidation(InputSchema, OutputSchema, async (ctx, input) => { ... })
@@ -25,15 +34,29 @@ export function withValidation(inputSchema, outputSchema, handler) {
 	const validateOutput = createValidator(outputSchema)
 
 	return async (ctx, input) => {
-		// Validate input — throws ValidationError if the payload is malformed.
-		const validatedInput = validateInput(input)
+		const validatedInput = asTerminal(validateInput, input, 'input', 400)
 
 		// Execute the actual workflow logic.
 		const result = await handler(ctx, validatedInput)
 
-		// Validate output — guards against handler implementation drift.
-		const validatedOutput = validateOutput(result)
+		return asTerminal(validateOutput, result, 'output', 500)
+	}
+}
 
-		return validatedOutput
+/**
+ * Runs `validator(value)`, rethrowing any failure as a `TerminalError`.
+ * @param {(value: *) => *} validator
+ * @param {*} value
+ * @param {'input'|'output'} side
+ * @param {number} errorCode
+ */
+function asTerminal(validator, value, side, errorCode) {
+	try {
+		return validator(value)
+	} catch (e) {
+		throw new TerminalError(e.message, {
+			errorCode,
+			metadata: { validation: side, errorName: String(e.errorName ?? e.name) },
+		})
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.1.20",
+	"version": "0.1.22",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -24,8 +24,8 @@
 		"test:watch": "bun test --watch"
 	},
 	"dependencies": {
-		"@empyria/classification": "0.1.8",
-		"@empyria/common": "0.3.6",
+		"@empyria/classification": "0.1.9",
+		"@empyria/common": "0.3.7",
 		"@restatedev/pubsub": "0.3.2",
 		"@restatedev/pubsub-client": "0.3.2",
 		"@restatedev/restate-sdk": "1.17.2",
@@ -35,8 +35,8 @@
 	},
 	"devDependencies": {
 		"@restatedev/restate-server": "1.7.12",
-		"oxfmt": "0.70.0",
-		"oxlint": "1.85.0"
+		"oxfmt": "0.71.0",
+		"oxlint": "1.86.0"
 	},
 	"engines": {
 		"bun": ">=1.4.2",

package/test/Admin.test.js

@@ -3,6 +3,8 @@ import {
 	checkServiceHandler,
 	startSubWorkflow,
 	callSubWorkflow,
+	childKey,
+	CHILD_KEY_SEPARATOR,
 	listServices,
 	queryRestate,
 	deleteDeployment,
@@ -113,6 +115,32 @@ describe('checkServiceHandler', () => {
 	})
 })
 
+describe('childKey', () => {
+	test('joins parent key and node path', () => {
+		expect(childKey('order-42', 'approval')).toBe('order-42:approval')
+		expect(CHILD_KEY_SEPARATOR).toBe(':')
+	})
+
+	test('appends the iteration when given, including 0', () => {
+		expect(childKey('order-42', 'shipment', 3)).toBe('order-42:shipment:3')
+		expect(childKey('order-42', 'shipment', 0)).toBe('order-42:shipment:0')
+	})
+
+	test('nests: a grandchild key extends the child key', () => {
+		expect(childKey(childKey('order-42', 'approval'), 'review', 1)).toBe(
+			'order-42:approval:review:1',
+		)
+	})
+
+	test('rejects empty or separator-containing segments and an empty parent', () => {
+		expect(() => childKey('order-42', '')).toThrow(TypeError)
+		expect(() => childKey('order-42', 'a:b')).toThrow(TypeError)
+		expect(() => childKey('order-42', 'a/b')).toThrow(TypeError)
+		expect(() => childKey('order-42', 'step', '')).toThrow(TypeError)
+		expect(() => childKey('', 'step')).toThrow(TypeError)
+	})
+})
+
 describe('startSubWorkflow / callSubWorkflow', () => {
 	test("startSubWorkflow sends via ctx.genericSend to the workflow's run handler", () => {
 		let sentArgs
@@ -389,6 +417,23 @@ describe('sendMessage / sendMessageAsync', () => {
 		).rejects.toThrow()
 	})
 
+	test('sends the idempotency-key header only when idempotencyKey is given', async () => {
+		const seen = []
+		globalThis.fetch = mock(async (url, init) => {
+			seen.push(init.headers)
+			return String(url).endsWith('/send')
+				? jsonResponse({ invocationId: 'inv-3', status: 'PreviouslyAccepted' })
+				: { ok: true, text: async () => '' }
+		})
+		const base = { restateURL: 'http://ingress', name: 'Svc', message: 'do', payload: {} }
+		await sendMessage({ ...base, idempotencyKey: 'req-1' })
+		await sendMessageAsync({ ...base, idempotencyKey: 'req-2' })
+		await sendMessage(base)
+		expect(seen[0]['idempotency-key']).toBe('req-1')
+		expect(seen[1]['idempotency-key']).toBe('req-2')
+		expect(seen[2]).not.toHaveProperty('idempotency-key')
+	})
+
 	test('sendMessageWithDiscovery / sendMessageAsyncWithDiscovery validate first', async () => {
 		globalThis.fetch = mock(async (url) => {
 			if (String(url).endsWith('/services')) return jsonResponse(servicesPayload)
@@ -522,4 +567,19 @@ describe('createRestateAdmin', () => {
 		})
 		expect(await admin.query('SELECT status FROM sys_invocation')).toEqual(rows)
 	})
+	test('sendMessage/sendMessageAsync forward idempotencyKey', async () => {
+		const seen = []
+		globalThis.fetch = mock(async (url, init) => {
+			seen.push(init.headers['idempotency-key'])
+			return jsonResponse({ invocationId: 'inv-4', status: 'Accepted' })
+		})
+		const admin = createRestateAdmin({
+			restateAdminURL: 'http://admin',
+			restateURL: 'http://ingress',
+		})
+		const msg = { name: 'Svc', message: 'do', payload: {} }
+		await admin.sendMessage({ ...msg, idempotencyKey: 'a' })
+		await admin.sendMessageAsync({ ...msg, idempotencyKey: 'b' })
+		expect(seen).toEqual(['a', 'b'])
+	})
 })

package/test/Validation.test.js

@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'bun:test'
+import { TerminalError } from '@restatedev/restate-sdk'
 import { withValidation } from '../lib/Validation.js'
-import { EmpyriaError } from '@empyria/common'
 
 const inputSchema = {
 	type: 'object',
@@ -13,6 +13,15 @@ const outputSchema = {
 	required: ['greeting'],
 }
 
+const rejection = async (promise) => {
+	try {
+		await promise
+	} catch (e) {
+		return e
+	}
+	throw new Error('expected a rejection')
+}
+
 describe('withValidation', () => {
 	test('validates input and output, and returns the validated output', async () => {
 		const handler = withValidation(inputSchema, outputSchema, async (ctx, input) => ({
@@ -22,13 +31,34 @@ describe('withValidation', () => {
 		expect(result).toEqual({ greeting: 'Hello, Bob' })
 	})
 
-	test('throws when the input does not match the schema', async () => {
-		const handler = withValidation(inputSchema, outputSchema, async () => ({ greeting: 'hi' }))
-		await expect(handler({}, {})).rejects.toThrow(EmpyriaError)
+	test('throws a 400 TerminalError when the input does not match the schema', async () => {
+		let called = false
+		const handler = withValidation(inputSchema, outputSchema, async () => {
+			called = true
+			return { greeting: 'hi' }
+		})
+		const e = await rejection(handler({}, {}))
+		expect(e).toBeInstanceOf(TerminalError)
+		expect(e.code).toBe(400)
+		expect(e.metadata.validation).toBe('input')
+		expect(called).toBe(false)
 	})
 
-	test('throws when the handler output does not match the schema', async () => {
+	test('throws a 500 TerminalError when the handler output does not match the schema', async () => {
 		const handler = withValidation(inputSchema, outputSchema, async () => ({ wrong: true }))
-		await expect(handler({}, { name: 'Bob' })).rejects.toThrow(EmpyriaError)
+		const e = await rejection(handler({}, { name: 'Bob' }))
+		expect(e).toBeInstanceOf(TerminalError)
+		expect(e.code).toBe(500)
+		expect(e.metadata.validation).toBe('output')
+	})
+
+	test('leaves errors thrown by the handler itself retryable', async () => {
+		const boom = new Error('transient')
+		const handler = withValidation(inputSchema, outputSchema, async () => {
+			throw boom
+		})
+		const e = await rejection(handler({}, { name: 'Bob' }))
+		expect(e).toBe(boom)
+		expect(e).not.toBeInstanceOf(TerminalError)
 	})
 })