@empyria/restate 0.4.16 → 0.4.17

package/AGENTS.md

@@ -79,6 +79,12 @@ 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` (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
 `process.exit()` — none of which are safe to exercise in-process in a test run.

package/README.md

@@ -124,6 +124,11 @@ Cron expressions are `croner` patterns (five fields, or six with seconds for tes
 
 ### An endpoint that does not register itself
 
+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` 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`:

package/lib/Admin.js

@@ -592,8 +592,12 @@ export function defineObject(def) {
  * that was removed or renamed cannot resume.
  * @param {Object} params
  * @param {string} params.restateAdminURL
- * @param {string} params.host
- * @param {number} params.port
+ * @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 {number} [params.healthPort] - Defaults to `port + 1`.
  * @param {Parameters<typeof restate.createEndpointHandler>[0]['services']} [params.services]
  * @param {() => void} [params.shutdownCallbackFn]
@@ -605,6 +609,7 @@ export function defineObject(def) {
  */
 export async function setupRestate({
 	restateAdminURL,
+	serviceURL: serviceURLParam,
 	host,
 	port,
 	healthPort = port + 1,
@@ -684,9 +689,8 @@ export async function setupRestate({
 
 	server.listen(port, () => console.log(`Server running on ${port}`))
 
-	if (host && port) {
-		const serviceURL = `http://${host}:${port}`
-
+	const serviceURL = resolveServiceURL({ serviceURL: serviceURLParam, host, port })
+	if (serviceURL) {
 		/**
 		 * @param {Object} params
 		 * @param {string} params.restateAdminURL
@@ -771,6 +775,31 @@ export async function setupRestate({
 	})
 }
 
+/**
+ * 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
+ */
+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
+	}
+	return host && port ? `http://${host}:${port}` : undefined
+}
+
 /**
  * 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.
@@ -885,15 +914,7 @@ export function createRestateAdmin({ restateAdminURL, restateURL }) {
 		listHandlers: ({ name }) => listHandlers({ restateAdminURL, name }),
 
 		// Management queries
-		setupRestate: ({ port, healthPort, host, services, shutdownCallbackFn }) =>
-			setupRestate({
-				restateAdminURL,
-				host,
-				port,
-				healthPort: healthPort ?? port + 1,
-				services,
-				shutdownCallbackFn,
-			}),
+		setupRestate: (params) => setupRestate({ ...params, restateAdminURL }),
 		registerDeployment: ({ serviceURL }) => registerDeployment({ restateAdminURL, serviceURL }),
 
 		submitWorkflow: ({ name, key, payload }) =>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.16",
+	"version": "0.4.17",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",

package/test/Admin.test.js

@@ -21,6 +21,7 @@ import {
 	sendMessageAsyncWithDiscovery,
 	registerDeployment,
 	shouldDeleteOnShutdown,
+	resolveServiceURL,
 	sendMessageAsynSafe,
 	defineWorkflow,
 	defineService,
@@ -542,6 +543,31 @@ 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')
+	})
+
+	test('falls back to http://host:port for the deprecated host', () => {
+		expect(resolveServiceURL({ host: 'svc', port: 9080 })).toBe('http://svc:9080')
+	})
+
+	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(() => resolveServiceURL({ serviceURL: 'svc:9080' })).toThrow(/complete URL|http/)
+		expect(() => resolveServiceURL({ serviceURL: 'ftp://svc' })).toThrow(/http or https/)
+	})
+})
+
 describe('shouldDeleteOnShutdown', () => {
 	test('deletes a registered deployment by default', () => {
 		expect(shouldDeleteOnShutdown({ deploymentId: 'dep-1' })).toBe(true)