@empyria/restate 0.4.18 → 0.4.21

package/README.md

@@ -125,9 +125,9 @@ Cron expressions are `croner` patterns (five fields, or six with seconds for tes
 ### Serving and registering an endpoint
 
 `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.
+address Restate reaches the endpoint at. It is registered as given and the endpoint listens on its port (80 or 443 when
+the URL has none or states the scheme's default), so the scheme is required (there is no separate host or port option);
+the health endpoint listens on the next port unless `healthPort` is set.
 
 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

package/lib/Admin.js

@@ -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,13 +620,17 @@ export function defineObject(def) {
  * that was removed or renamed cannot resume.
  * @param {Object} params
  * @param {string} params.restateAdminURL
- * @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 {string} params.serviceURL Complete URL Restate uses to reach this endpoint (e.g.
+ *   `https://agent-service.internal:9080`). It is registered as given, and the endpoint listens on its port: 80 or 443
+ *   when the URL has none or states the scheme's default (listening there needs the privilege to bind it).
  * @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.
@@ -611,6 +643,7 @@ export async function setupRestate({
 	services = [],
 	shutdownCallbackFn,
 	registrationCallbackFn,
+	healthCheckFn,
 	keepDeploymentOnShutdown = false,
 	forceRegistration = false,
 }) {
@@ -624,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`))
@@ -764,10 +792,9 @@ export async function setupRestate({
 
 /**
  * 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
+ * @param {string} serviceURL Complete http(s) URL; a port left out (or equal to the scheme's default) means 80/443
  * @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)
+ * @throws {Error} If it is missing or not an absolute http(s) URL
  */
 export function parseServiceURL(serviceURL) {
 	if (!serviceURL) {
@@ -786,12 +813,9 @@ export function parseServiceURL(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 { serviceURL, port: Number(url.port) }
+	// `URL.port` is '' for the scheme's default port, written or not; that is the port Restate dials, so listen on it.
+	const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80
+	return { serviceURL, port }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.18",
+	"version": "0.4.21",
 	"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

@@ -566,9 +566,11 @@ describe('parseServiceURL', () => {
 		expect(() => parseServiceURL('ftp://svc:21')).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/)
+	test("uses the scheme's default port when the URL has none or states it", () => {
+		expect(parseServiceURL('https://svc.example.com').port).toBe(443)
+		expect(parseServiceURL('https://svc.example.com:443').port).toBe(443)
+		expect(parseServiceURL('http://svc').port).toBe(80)
+		expect(parseServiceURL('http://svc:80').port).toBe(80)
 	})
 })