@empyria/restate 0.4.17 → 0.4.20

package/AGENTS.md

@@ -79,11 +79,11 @@ may observe an already-mocked value. See `test/Admin.test.js`.
 same address registers again, but only `force: true` updates its handler list. Check both against a live server when
 touching them.
 
-`setupRestate` registers the single complete `serviceURL` it is given (scheme included — never assemble a URL from
-host + port, the scheme and any proxy mapping are the caller's to state). `port` is only the listen port. `host` is a
-deprecated fallback (`http://host:port`) kept for consumers pinned to older call sites; the URL decision is
-`resolveServiceURL` (unit tested). `createRestateAdmin().setupRestate` must forward every option to `setupRestate` — it
-once dropped `keepDeploymentOnShutdown`/`forceRegistration`/`registrationCallbackFn`.
+`setupRestate` takes ONE complete `serviceURL` (scheme and explicit port included): it is registered as given and the
+endpoint listens on its port. There is deliberately no `host` or `port` option — never assemble a URL from parts, the
+scheme and any mapping are the caller's to state. `parseServiceURL` validates it (unit tested).
+`createRestateAdmin().setupRestate` must forward every option to `setupRestate` — it once dropped
+`keepDeploymentOnShutdown`/`forceRegistration`/`registrationCallbackFn`.
 
 `setupRestate` (in `lib/Admin.js`) is not unit tested: it binds real HTTP/2 + health-check
 ports, installs process-wide `SIGTERM`/`SIGINT` handlers, and its returned `forceClose` calls

package/README.md

@@ -122,14 +122,14 @@ 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
+### Serving and registering an endpoint
 
-Tell `setupRestate` where Restate reaches the endpoint with one complete URL, scheme included:
-`setupRestate({ restateAdminURL, port: 9080, serviceURL: 'https://agent-service.internal:9080', services })`. `port` is only
-what the process listens on; `serviceURL` is what gets registered (it may differ behind a proxy). Without `serviceURL`
-nothing is registered. The old `host` option still works (registers `http://<host>:<port>`) but is deprecated.
+`setupRestate({ restateAdminURL, serviceURL: 'https://agent-service.internal:9080', services })` takes one complete URL, the
+address Restate reaches the endpoint at. It is registered as given and the endpoint listens on its port, so the scheme and
+an explicit port are required (there is no separate host or port option); the health endpoint listens on the next port
+unless `healthPort` is set.
 
-`setupRestate` serves, registers the deployment, and deletes it again on SIGINT/SIGTERM. Invocations in flight are
+It serves, registers the deployment, and deletes it again on SIGINT/SIGTERM. Invocations in flight are
 pinned to their deployment, so deleting it strands them: a restarted process cannot finish them and they can only be
 killed. For a process restarted at the same address, pass `keepDeploymentOnShutdown: true` and `forceRegistration: true`:
 Restate keeps the deployment ID when the same address registers again (checked against Restate 1.7), running
@@ -137,8 +137,7 @@ invocations resume on the new process, and `force` updates the services and hand
 re-registration keeps the old handler list). Only compatible changes are safe this way: an invocation of a removed or
 renamed handler cannot resume.
 
-When something else owns
-registration (a supervisor that registers a process's address once and restarts the process), use
+To serve without registering: 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.
 

package/lib/Admin.js

@@ -550,7 +550,7 @@ export function sendMessageAsyncWithDiscovery({ restateAdminURL }) {
 }
 
 /**
- * @typedef {import('node:http2').Http2Server & {deploymentId: string, services: string[], forceClose: () => void}} RestateServer
+ * @typedef {import('node:http2').Http2Server & {deploymentId: string|undefined, services: string[]|undefined, forceClose: () => void}} RestateServer
  */
 
 /**
@@ -578,6 +578,34 @@ export function defineObject(def) {
 	return restate.object(def)
 }
 
+/**
+ * The health check `setupRestate` uses unless given a `healthCheckFn`: `GET /health`, `/health/liveness` and
+ * `/health/readiness` answer 200 once the deployment is registered and 503 before, anything else 404.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{isHealthy: boolean, deploymentId?: string, services?: string[]}} state
+ */
+export function defaultHealthCheck(req, res, { isHealthy, deploymentId, services }) {
+	if (
+		(req.url === '/health' ||
+			req.url === '/health/liveness' ||
+			req.url === '/health/readiness') &&
+		req.method === 'GET'
+	) {
+		res.writeHead(isHealthy ? 200 : 503, { 'Content-Type': 'application/json' })
+		res.end(
+			JSON.stringify({
+				status: isHealthy ? 'ok' : 'unavailable',
+				deployment: deploymentId,
+				services,
+			}),
+		)
+	} else {
+		res.writeHead(404)
+		res.end()
+	}
+}
+
 /**
  * Starts the HTTP/2 Restate endpoint, a health-check HTTP server, registers
  * the deployment with the admin API, and wires SIGTERM/SIGINT for graceful
@@ -592,16 +620,17 @@ export function defineObject(def) {
  * that was removed or renamed cannot resume.
  * @param {Object} params
  * @param {string} params.restateAdminURL
- * @param {number} params.port Port this endpoint listens on (the bind, not the advertised address).
- * @param {string} [params.serviceURL] Complete URL Restate uses to reach this endpoint, scheme included
- *   (e.g. `https://agent-service.internal:9080`). Registration happens only when it is set — the scheme and
- *   any proxy/port mapping are the caller's to state, never guessed here.
- * @param {string} [params.host] @deprecated Use `serviceURL`. Only when `serviceURL` is absent: registers as
- *   `http://<host>:<port>` (plain HTTP is assumed).
+ * @param {string} params.serviceURL Complete URL Restate uses to reach this endpoint, scheme and port included
+ *   (e.g. `https://agent-service.internal:9080`). It is registered as given, and the endpoint listens on its port, so
+ *   the port must be explicit. Scheme and port are the caller's to state, never guessed here.
  * @param {number} [params.healthPort] - Defaults to `port + 1`.
  * @param {Parameters<typeof restate.createEndpointHandler>[0]['services']} [params.services]
  * @param {() => void} [params.shutdownCallbackFn]
  * @param {(deploymentId: string) => void} [params.registrationCallbackFn]
+ * @param {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, state: {isHealthy: boolean, deploymentId?: string, services?: string[]}) => void | Promise<void>} [params.healthCheckFn]
+ *   Takes over every request to the health port: routing, status code, headers and body are the function's to set and
+ *   it must end the response. `state.isHealthy` is true once the deployment is registered. Without it, `/health`,
+ *   `/health/liveness` and `/health/readiness` answer 200 or 503 with a small JSON body, healthy once registered.
  * @param {boolean} [params.keepDeploymentOnShutdown=false] Leave the deployment registered on SIGINT/SIGTERM.
  * @param {boolean} [params.forceRegistration=false] Register with `force: true`, updating an existing deployment at
  *   the same address in place.
@@ -610,15 +639,17 @@ export function defineObject(def) {
 export async function setupRestate({
 	restateAdminURL,
 	serviceURL: serviceURLParam,
-	host,
-	port,
-	healthPort = port + 1,
+	healthPort: healthPortParam,
 	services = [],
 	shutdownCallbackFn,
 	registrationCallbackFn,
+	healthCheckFn,
 	keepDeploymentOnShutdown = false,
 	forceRegistration = false,
 }) {
+	const { serviceURL, port } = parseServiceURL(serviceURLParam)
+	const healthPort = healthPortParam ?? port + 1
+
 	const handler = restate.createEndpointHandler({ services })
 
 	const server = http2.createServer(handler)
@@ -626,25 +657,20 @@ export async function setupRestate({
 	// --- Health server ---
 	let isHealthy = false
 
+	const checkFn = healthCheckFn ?? defaultHealthCheck
 	const healthServer = createHttpServer((req, res) => {
-		if (
-			(req.url === '/health' ||
-				req.url === '/health/liveness' ||
-				req.url === '/health/readiness') &&
-			req.method === 'GET'
-		) {
-			const status = isHealthy ? 200 : 503
-			const body = JSON.stringify({
-				status: isHealthy ? 'ok' : 'unavailable',
-				deployment: server.deploymentId,
-				services: server.services,
-			})
-			res.writeHead(status, { 'Content-Type': 'application/json' })
-			res.end(body)
-		} else {
-			res.writeHead(404)
-			res.end()
+		const state = {
+			isHealthy,
+			deploymentId: server.deploymentId,
+			services: server.services,
 		}
+		Promise.resolve()
+			.then(() => checkFn(req, res, state))
+			.catch((err) => {
+				console.error('healthCheckFn failed', err)
+				if (!res.headersSent) res.writeHead(500)
+				res.end()
+			})
 	})
 
 	healthServer.listen(healthPort, () => console.log(`Health endpoint on :${healthPort}/health`))
@@ -689,125 +715,121 @@ export async function setupRestate({
 
 	server.listen(port, () => console.log(`Server running on ${port}`))
 
-	const serviceURL = resolveServiceURL({ serviceURL: serviceURLParam, host, port })
-	if (serviceURL) {
-		/**
-		 * @param {Object} params
-		 * @param {string} params.restateAdminURL
-		 * @param {string} params.serviceURL
-		 * @param {number} [params.attempts=5]
-		 * @param {number} [params.baseDelayMs=3000]
-		 * @returns {Promise<RegisterDeploymentResponse>}
-		 */
-		async function registerDeploymentWithRetry({
-			restateAdminURL,
-			serviceURL,
-			attempts = 5,
-			baseDelayMs = 3_000,
-		}) {
-			let lastErr
-
-			for (let attempt = 1; attempt <= attempts; attempt++) {
+	/**
+	 * @param {Object} params
+	 * @param {string} params.restateAdminURL
+	 * @param {string} params.serviceURL
+	 * @param {number} [params.attempts=5]
+	 * @param {number} [params.baseDelayMs=3000]
+	 * @returns {Promise<RegisterDeploymentResponse>}
+	 */
+	async function registerDeploymentWithRetry({
+		restateAdminURL,
+		serviceURL,
+		attempts = 5,
+		baseDelayMs = 3_000,
+	}) {
+		let lastErr
+
+		for (let attempt = 1; attempt <= attempts; attempt++) {
+			try {
+				const result = await registerDeployment({
+					restateAdminURL,
+					serviceURL,
+					force: forceRegistration,
+				})
+
 				try {
-					const result = await registerDeployment({
-						restateAdminURL,
-						serviceURL,
-						force: forceRegistration,
-					})
-
-					try {
-						registrationCallbackFn?.(result.id)
-					} catch (err) {
-						console.error(
-							`Error in registration callback for deployment ${result.id}: ${
-								err instanceof Error ? err.message : String(err)
-							}`,
-						)
-					}
-
-					return result
+					registrationCallbackFn?.(result.id)
 				} catch (err) {
-					lastErr = err
-
-					// Deterministic — retrying won't help. Bail immediately.
-					if (err instanceof Error && err.message.includes('META0004')) {
-						throw err
-					}
-
-					if (attempt < attempts) {
-						const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), DELAY_CAP)
-						console.log(
-							`Registration attempt ${attempt}/${attempts} failed, retrying in ${delay}ms: ${
-								err instanceof Error ? err.message : String(err)
-							}`,
-						)
-						await sleep(delay)
-					}
+					console.error(
+						`Error in registration callback for deployment ${result.id}: ${
+							err instanceof Error ? err.message : String(err)
+						}`,
+					)
 				}
-			}
 
-			throw new Error(
-				`Failed to register deployment after ${attempts} attempts: ${
-					lastErr instanceof Error ? lastErr.message : String(lastErr)
-				}`,
-			)
-		}
-		const deployment = await registerDeploymentWithRetry({
-			restateAdminURL,
-			serviceURL,
-		}).catch(console.error)
+				return result
+			} catch (err) {
+				lastErr = err
 
-		isHealthy = !!deployment // Only healthy once registered
+				// Deterministic — retrying won't help. Bail immediately.
+				if (err instanceof Error && err.message.includes('META0004')) {
+					throw err
+				}
 
-		return Object.assign(server, {
-			deploymentId: deployment?.id,
-			services: deployment?.services?.map((s) => s.name),
-			forceClose,
-		})
-	} else {
-		isHealthy = true
+				if (attempt < attempts) {
+					const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), DELAY_CAP)
+					console.log(
+						`Registration attempt ${attempt}/${attempts} failed, retrying in ${delay}ms: ${
+							err instanceof Error ? err.message : String(err)
+						}`,
+					)
+					await sleep(delay)
+				}
+			}
+		}
+
+		throw new Error(
+			`Failed to register deployment after ${attempts} attempts: ${
+				lastErr instanceof Error ? lastErr.message : String(lastErr)
+			}`,
+		)
 	}
+	const deployment = await registerDeploymentWithRetry({
+		restateAdminURL,
+		serviceURL,
+	}).catch(console.error)
+
+	isHealthy = !!deployment // Only healthy once registered
 
 	return Object.assign(server, {
-		deploymentId: 'NA',
-		services: [],
+		deploymentId: deployment?.id,
+		services: deployment?.services?.map((s) => s.name),
 		forceClose,
 	})
 }
 
 /**
- * The URL `setupRestate` registers with Restate: `serviceURL` as given (validated as an absolute http(s) URL),
- * else the deprecated `host` + `port` pair as `http://host:port`, else `undefined` (no registration).
- * @param {{serviceURL?: string, host?: string, port?: number}} params
- * @returns {string|undefined}
- * @throws {Error} If `serviceURL` is not an absolute http(s) URL
+ * Validates the URL `setupRestate` registers with Restate and returns it with the port the endpoint listens on.
+ * @param {string} serviceURL Complete http(s) URL including an explicit port
+ * @returns {{serviceURL: string, port: number}} `serviceURL` unchanged
+ * @throws {Error} If it is missing, not an absolute http(s) URL, or has no explicit port (the scheme's default would
+ *   be a guess)
  */
-export function resolveServiceURL({ serviceURL, host, port }) {
-	if (serviceURL) {
-		let url
-		try {
-			url = new URL(serviceURL)
-		} catch {
-			throw new Error(
-				`serviceURL must be a complete URL including http:// or https://, got '${serviceURL}'`,
-			)
-		}
-		if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-			throw new Error(`serviceURL must use http or https, got '${serviceURL}'`)
-		}
-		return serviceURL
+export function parseServiceURL(serviceURL) {
+	if (!serviceURL) {
+		throw new Error(
+			'setupRestate needs `serviceURL`: the complete URL (scheme and port) Restate reaches this endpoint at',
+		)
+	}
+	let url
+	try {
+		url = new URL(serviceURL)
+	} catch {
+		throw new Error(
+			`serviceURL must be a complete URL including http:// or https://, got '${serviceURL}'`,
+		)
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+		throw new Error(`serviceURL must use http or https, got '${serviceURL}'`)
+	}
+	if (!url.port) {
+		throw new Error(
+			`serviceURL '${serviceURL}' has no explicit port: the endpoint listens on the port in the URL`,
+		)
 	}
-	return host && port ? `http://${host}:${port}` : undefined
+	return { serviceURL, port: Number(url.port) }
 }
 
 /**
- * Whether `setupRestate`'s shutdown removes the deployment: only a real one (registered, not `'NA'`), and not when the
- * caller keeps it for the next start.
+ * Whether `setupRestate`'s shutdown removes the deployment: only one that registered (`deploymentId` is undefined when registration
+ * failed), and not when the caller keeps it for the next start.
  * @param {{deploymentId: string|undefined, keepDeploymentOnShutdown?: boolean}} params
  * @returns {boolean}
  */
 export function shouldDeleteOnShutdown({ deploymentId, keepDeploymentOnShutdown = false }) {
-	return Boolean(deploymentId) && deploymentId !== 'NA' && !keepDeploymentOnShutdown
+	return Boolean(deploymentId) && !keepDeploymentOnShutdown
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.17",
+	"version": "0.4.20",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -36,10 +36,10 @@
 		"croner": "10.0.1"
 	},
 	"devDependencies": {
-		"@ai-sdk/openai-compatible": "3.0.63",
-		"@ai-sdk/provider": "4.0.22",
+		"@ai-sdk/openai-compatible": "3.0.65",
+		"@ai-sdk/provider": "4.0.24",
 		"@restatedev/restate-server": "1.7.13",
-		"ai": "7.0.128",
+		"ai": "7.0.130",
 		"oxfmt": "0.72.0",
 		"oxlint": "1.87.0"
 	},

package/test/Admin.test.js

@@ -21,7 +21,7 @@ import {
 	sendMessageAsyncWithDiscovery,
 	registerDeployment,
 	shouldDeleteOnShutdown,
-	resolveServiceURL,
+	parseServiceURL,
 	sendMessageAsynSafe,
 	defineWorkflow,
 	defineService,
@@ -543,28 +543,32 @@ describe('registerDeployment', () => {
 	})
 })
 
-describe('resolveServiceURL', () => {
-	test('uses a complete serviceURL as given, scheme included', () => {
-		expect(
-			resolveServiceURL({ serviceURL: 'https://svc.example.com:9443/base', port: 9080 }),
-		).toBe('https://svc.example.com:9443/base')
-	})
-
-	test('serviceURL wins over the deprecated host', () => {
-		expect(resolveServiceURL({ serviceURL: 'https://a', host: 'b', port: 1 })).toBe('https://a')
+describe('parseServiceURL', () => {
+	test('returns the URL unchanged with the port it carries', () => {
+		expect(parseServiceURL('http://agent-service:9080')).toEqual({
+			serviceURL: 'http://agent-service:9080',
+			port: 9080,
+		})
+		expect(parseServiceURL('https://svc.example.com:9443/base')).toEqual({
+			serviceURL: 'https://svc.example.com:9443/base',
+			port: 9443,
+		})
 	})
 
-	test('falls back to http://host:port for the deprecated host', () => {
-		expect(resolveServiceURL({ host: 'svc', port: 9080 })).toBe('http://svc:9080')
+	test('requires a serviceURL', () => {
+		expect(() => parseServiceURL(undefined)).toThrow(/needs `serviceURL`/)
+		expect(() => parseServiceURL('')).toThrow(/needs `serviceURL`/)
 	})
 
-	test('returns undefined (no registration) when nothing is given', () => {
-		expect(resolveServiceURL({ port: 9080 })).toBeUndefined()
+	test('rejects a URL without a scheme or with a non-http scheme', () => {
+		expect(() => parseServiceURL('agent-service:9080')).toThrow(/http/)
+		expect(() => parseServiceURL('not a url')).toThrow(/complete URL/)
+		expect(() => parseServiceURL('ftp://svc:21')).toThrow(/http or https/)
 	})
 
-	test('rejects a URL without a scheme or with a non-http scheme', () => {
-		expect(() => resolveServiceURL({ serviceURL: 'svc:9080' })).toThrow(/complete URL|http/)
-		expect(() => resolveServiceURL({ serviceURL: 'ftp://svc' })).toThrow(/http or https/)
+	test('refuses to guess the scheme default when the URL has no explicit port', () => {
+		expect(() => parseServiceURL('https://svc.example.com')).toThrow(/no explicit port/)
+		expect(() => parseServiceURL('http://svc:80')).toThrow(/no explicit port/)
 	})
 })
 
@@ -580,7 +584,7 @@ describe('shouldDeleteOnShutdown', () => {
 	})
 
 	test('never deletes without a real deployment', () => {
-		for (const deploymentId of [undefined, '', 'NA']) {
+		for (const deploymentId of [undefined, '']) {
 			expect(shouldDeleteOnShutdown({ deploymentId })).toBe(false)
 		}
 	})