npm - @milaboratories/pl-deployments - Versions diffs - 2.17.18 → 3.0.0 - Mend

@milaboratories/pl-deployments 2.17.18 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/local/pl.cjs CHANGED Viewed

@@ -12,6 +12,7 @@ let node_os = require("node:os");
 node_os = require_runtime.__toESM(node_os);
 let _milaboratories_pl_http = require("@milaboratories/pl-http");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
+let _milaboratories_pl_healthcheck = require("@milaboratories/pl-healthcheck");
 //#region src/local/pl.ts
 const LocalConfigYaml = "config-local.yaml";
 /**
@@ -25,11 +26,12 @@ var LocalPl = class {
 	nRuns = 0;
 	lastRunHistory = {};
 	wasStopped = false;
-	constructor(logger, workingDir, startOptions, initialStartHistory, onClose, onError, onCloseAndError, onCloseAndErrorNoStop) {
+	constructor(logger, workingDir, startOptions, initialStartHistory, grpcPort, onClose, onError, onCloseAndError, onCloseAndErrorNoStop) {
 		this.logger = logger;
 		this.workingDir = workingDir;
 		this.startOptions = startOptions;
 		this.initialStartHistory = initialStartHistory;
+		this.grpcPort = grpcPort;
 		this.onClose = onClose;
 		this.onError = onError;
 		this.onCloseAndError = onCloseAndError;
@@ -71,8 +73,58 @@ var LocalPl = class {
 	stopped() {
 		return this.wasStopped;
 	}
-	async isAlive() {
-		return await require_process.isProcessAlive((0, _milaboratories_ts_helpers.notEmpty)(this.pid));
+	/**
+	* Polls the OS until the backend process is observed alive.
+	* Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.
+	*/
+	async isAlive(opts) {
+		const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+		const pollMs = opts?.pollIntervalMs ?? 500;
+		while (true) {
+			if (Date.now() >= deadline) throw new Error("Timeout waiting for backend process to be alive");
+			await (0, _milaboratories_ts_helpers.sleep)(pollMs);
+			if (!this.pid) continue;
+			if (await require_process.isProcessAlive(this.pid)) return;
+		}
+	}
+	/**
+	* Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.
+	* Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.
+	*
+	* Calling this method is an explicit statement that the caller wants a real
+	* readiness signal; if `grpcPort` is undefined we throw rather than silently
+	* degrade to a process-only check (use {@link isAlive} for that).
+	*/
+	async isReady(opts) {
+		const grpcPort = opts?.grpcPort ?? this.grpcPort;
+		if (grpcPort === void 0) throw new Error("isReady requires grpcPort to be configured — caller asked for a real readiness check but no gRPC port is available");
+		const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+		const pollMs = opts?.pollIntervalMs ?? 500;
+		const requestTimeoutMs = Math.max(500, Math.min(pollMs, 2e3));
+		let processAlive = false;
+		let wasAlive = false;
+		let isFirstCheck = true;
+		while (true) {
+			if (Date.now() >= deadline) {
+				if (!processAlive) throw new Error("Timeout waiting for backend process to be alive");
+				throw new Error("Timeout waiting for backend to be ready");
+			}
+			if (!isFirstCheck) await (0, _milaboratories_ts_helpers.sleep)(pollMs);
+			isFirstCheck = false;
+			if (!this.pid) continue;
+			processAlive = await require_process.isProcessAlive(this.pid);
+			wasAlive = wasAlive || processAlive;
+			if (!processAlive) {
+				if (wasAlive) throw new Error("Backend process died while waiting for readiness");
+				continue;
+			}
+			try {
+				if (await (0, _milaboratories_pl_healthcheck.plHealthCheck)({
+					address: `127.0.0.1:${grpcPort}`,
+					defaultRequestTimeout: requestTimeoutMs
+				}) === _milaboratories_pl_healthcheck.ServingStatus.SERVING) return;
+			} catch {}
+		}
 	}
 	debugInfo() {
 		return {
@@ -127,7 +179,7 @@ Only Basic auth is supported by the backend.`);
 			args: processOpts.args,
 			cwd: processOpts.opts.cwd
 		});
-		const pl = new LocalPl(logger, ops.workingDir, processOpts, t, ops.onClose, ops.onError, ops.onCloseAndError, ops.onCloseAndErrorNoStop);
+		const pl = new LocalPl(logger, ops.workingDir, processOpts, t, ops.grpcPort, ops.onClose, ops.onError, ops.onCloseAndError, ops.onCloseAndErrorNoStop);
 		await pl.start();
 		return pl;
 	});

package/dist/local/pl.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"pl.cjs","names":["withTrace","processRun","filePid","writePid","processWaitStopped","isProcessAlive","os","fsp","resolveLocalPlBinaryPath","readPid","processStop","newDefaultPlBinarySource"],"sources":["../../src/local/pl.ts"],"sourcesContent":["import type { ProcessOptions } from \"./process\";\nimport { isProcessAlive, processStop, processWaitStopped, processRun } from \"./process\";\nimport type { PlBinarySource } from \"../common/pl_binary\";\nimport { newDefaultPlBinarySource, resolveLocalPlBinaryPath } from \"../common/pl_binary\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { notEmpty } from \"@milaboratories/ts-helpers\";\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { filePid, readPid, writePid } from \"./pid\";\nimport type { Trace } from \"./trace\";\nimport { withTrace } from \"./trace\";\nimport upath from \"upath\";\nimport fsp from \"node:fs/promises\";\nimport type { Required } from \"utility-types\";\nimport * as os from \"node:os\";\nimport type { ProxySettings } from \"@milaboratories/pl-http\";\nimport { defaultHttpDispatcher } from \"@milaboratories/pl-http\";\nimport { parseHttpAuth } from \"@milaboratories/pl-model-common\";\n\nexport const LocalConfigYaml = \"config-local.yaml\";\n\n/*\n Represents a local running pl-core,\n * and has methods to start, check if it's running, stop and wait for stopping it.\n * Also, a hook on pl-core closed can be provided.\n /\nexport class LocalPl {\n private instance?: ChildProcess;\n public pid?: number;\n private nRuns: number = 0;\n private lastRunHistory: Trace = {};\n private wasStopped = false;\n\n constructor(\n private readonly logger: MiLogger,\n private readonly workingDir: string,\n private readonly startOptions: ProcessOptions,\n private readonly initialStartHistory: Trace,\n private readonly onClose?: (pl: LocalPl) => Promise<void>,\n private readonly onError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>,\n ) {}\n\n async start() {\n await withTrace(this.logger, async (trace, t) => {\n this.wasStopped = false;\n const instance = processRun(this.logger, this.startOptions);\n instance.on(\"error\", (e: any) => {\n this.logger.error(\n `error '${e}', while running platforma, started opts: ${JSON.stringify(this.debugInfo())}`,\n );\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onError !== undefined) void this.onError(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n instance.on(\"close\", () => {\n this.logger.warn(`platforma was closed, started opts: ${JSON.stringify(this.debugInfo())}`);\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onClose !== undefined) void this.onClose(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n\n trace(\"started\", true);\n\n const pidFile = trace(\"pidFile\", filePid(this.workingDir));\n trace(\"pid\", notEmpty(instance.pid));\n trace(\"pidWritten\", await writePid(pidFile, notEmpty(instance.pid)));\n\n this.nRuns++;\n this.instance = instance;\n this.pid = instance.pid;\n this.lastRunHistory = t;\n });\n }\n\n stop() {\n // TODO use this.instance to stop the process\n this.wasStopped = true;\n processStop(notEmpty(this.pid));\n }\n\n async waitStopped() {\n await processWaitStopped(notEmpty(this.pid), 15000);\n }\n\n stopped() {\n return this.wasStopped;\n }\n\n async isAlive(): Promise<boolean> {\n return await isProcessAlive(notEmpty(this.pid));\n }\n\n debugInfo() {\n return {\n lastRunHistory: this.lastRunHistory,\n nRuns: this.nRuns,\n pid: this.pid,\n workingDir: this.workingDir,\n initialStartHistory: this.initialStartHistory,\n wasStopped: this.wasStopped,\n };\n }\n}\n\n/* Options to start a local pl-core. /\nexport type LocalPlOptions = {\n /* From what directory start a process. /\n readonly workingDir: string;\n /* A string representation of yaml config. /\n readonly config: string;\n /* How to get a binary, download it or get an existing one (default: download latest version) /\n readonly plBinary?: PlBinarySource;\n /* Additional options for a process, environments, stdout, stderr etc. /\n readonly spawnOptions?: SpawnOptions;\n /\n If the previous pl-core was started from the same directory,\n * we can check if it's still running and then stop it before starting a new one.\n * (default: true)\n /\n readonly closeOld?: boolean;\n /\n Proxy settings to use to fetch the binary and pass it down\n * as a HTTPS_PROXY/HTTP_PROXY environment variable;\n * Backend only supports Basic auth.\n /\n readonly proxy?: ProxySettings;\n\n readonly onClose?: (pl: LocalPl) => Promise<void>;\n readonly onError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>;\n};\n\nexport type LocalPlOptionsFull = Required<LocalPlOptions, \"plBinary\" \| \"spawnOptions\" \| \"closeOld\">;\n\n/\n Starts pl-core, if the option was provided downloads a binary, reads license environments etc.\n /\nexport async function localPlatformaInit(logger: MiLogger, _ops: LocalPlOptions): Promise<LocalPl> {\n // filling-in default values\n\n // Backend could consume a lot of CPU power,\n // we want to keep at least a couple for UI and other apps to work.\n const numCpu = Math.max(os.cpus().length - 2, 1);\n const ops = mergeDefaultOps(_ops, numCpu);\n\n return await withTrace(logger, async (trace, t) => {\n trace(\"startOptions\", { ...ops, config: \"too wordy\" });\n\n const workDir = upath.resolve(ops.workingDir);\n\n if (ops.closeOld) {\n trace(\"closeOld\", await localPlatformaReadPidAndStop(logger, workDir));\n }\n\n const configPath = upath.join(workDir, LocalConfigYaml);\n\n logger.info(`writing configuration '${configPath}'...`);\n await fsp.writeFile(configPath, ops.config);\n\n const plBinPath = upath.join(workDir, \"binaries\");\n const baseBinaryPath = await resolveLocalPlBinaryPath({\n logger,\n downloadDir: plBinPath,\n src: ops.plBinary,\n dispatcher: defaultHttpDispatcher(ops.proxy),\n });\n const binaryPath = trace(\"binaryPath\", upath.join(\"binaries\", baseBinaryPath));\n\n const env = { ...process.env };\n\n if (ops.proxy?.url) {\n const url = new URL(ops.proxy.url);\n if (ops.proxy.auth) {\n const parsed = parseHttpAuth(ops.proxy.auth);\n if (parsed.scheme !== \"Basic\") {\n throw new Error(`\\\nUnsupported auth scheme: ${parsed.scheme}. \\\nOnly Basic auth is supported by the backend.`);\n }\n url.username = parsed.username;\n url.password = parsed.password;\n }\n env.http_proxy = url.toString();\n env.https_proxy = url.toString();\n }\n\n const processOpts = plProcessOps(binaryPath, configPath, ops, workDir, env);\n trace(\"processOpts\", {\n cmd: processOpts.cmd,\n args: processOpts.args,\n cwd: processOpts.opts.cwd,\n });\n\n const pl = new LocalPl(\n logger,\n ops.workingDir,\n processOpts,\n t,\n ops.onClose,\n ops.onError,\n ops.onCloseAndError,\n ops.onCloseAndErrorNoStop,\n );\n await pl.start();\n\n return pl;\n });\n}\n\n/* Reads a pid of the old pl-core if it was started in the same working directory,\n * and closes it. /\nasync function localPlatformaReadPidAndStop(\n logger: MiLogger,\n workingDir: string,\n): Promise<Record<string, any>> {\n return await withTrace(logger, async (trace, t) => {\n const file = trace(\"pidFilePath\", filePid(workingDir));\n\n const oldPid = trace(\"pid\", await readPid(file));\n const alive = trace(\"wasAlive\", await isProcessAlive(oldPid));\n\n if (oldPid !== undefined && alive) {\n trace(\"stopped\", processStop(oldPid));\n try {\n trace(\"waitStopped\", await processWaitStopped(oldPid, 15_000)); // larger, that 10s we provide to backend in config.\n } catch {\n trace(\"forceStopped\", processStop(oldPid, true));\n trace(\"waitForceStopped\", await processWaitStopped(oldPid, 5_000));\n }\n }\n\n return t;\n });\n}\n\n/* Gets default options for the whole init process\n * and overrides them with the provided options. /\nexport function mergeDefaultOps(ops: LocalPlOptions, numCpu: number): LocalPlOptionsFull {\n const result: {\n plBinary: PlBinarySource;\n spawnOptions: SpawnOptions;\n closeOld: boolean;\n } = {\n plBinary: newDefaultPlBinarySource(),\n spawnOptions: {\n env: {\n GOMAXPROCS: String(numCpu),\n },\n },\n closeOld: true,\n };\n\n if (ops.spawnOptions?.env) {\n result.spawnOptions.env = { ...result.spawnOptions.env, ...ops.spawnOptions.env };\n }\n\n if (ops.spawnOptions) {\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.spawnOptions = { ...result.spawnOptions, ...withoutEnv };\n }\n\n const withoutSpawnOps = { ...ops };\n delete withoutSpawnOps[\"spawnOptions\"];\n\n return { ...result, ...withoutSpawnOps };\n}\n\n/* Gets default options for a platforma local binary\n * and overrides them with the provided options. */\nexport function plProcessOps(\n binaryPath: any,\n configPath: string,\n ops: LocalPlOptionsFull,\n workDir: string,\n defaultEnv: Record<string, string \| undefined>,\n): ProcessOptions {\n const result: ProcessOptions = {\n cmd: binaryPath,\n args: [\"--config\", configPath],\n opts: {\n env: { ...defaultEnv },\n cwd: workDir,\n stdio: [\"pipe\", \"ignore\", \"inherit\"],\n windowsHide: true, // hide a terminal on Windows\n },\n };\n\n if (ops.spawnOptions?.env) {\n result.opts.env = { ...result.opts.env, ...ops.spawnOptions.env };\n }\n\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.opts = { ...result.opts, ...withoutEnv };\n\n return result;\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"pl.cjs","names":["withTrace","processRun","filePid","writePid","processWaitStopped","isProcessAlive","ServingStatus","os","fsp","resolveLocalPlBinaryPath","readPid","processStop","newDefaultPlBinarySource"],"sources":["../../src/local/pl.ts"],"sourcesContent":["import type { ProcessOptions } from \"./process\";\nimport { isProcessAlive, processStop, processWaitStopped, processRun } from \"./process\";\nimport type { PlBinarySource } from \"../common/pl_binary\";\nimport { newDefaultPlBinarySource, resolveLocalPlBinaryPath } from \"../common/pl_binary\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { notEmpty } from \"@milaboratories/ts-helpers\";\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { filePid, readPid, writePid } from \"./pid\";\nimport type { Trace } from \"./trace\";\nimport { withTrace } from \"./trace\";\nimport upath from \"upath\";\nimport fsp from \"node:fs/promises\";\nimport type { Required } from \"utility-types\";\nimport * as os from \"node:os\";\nimport { sleep } from \"@milaboratories/ts-helpers\";\nimport type { ProxySettings } from \"@milaboratories/pl-http\";\nimport { defaultHttpDispatcher } from \"@milaboratories/pl-http\";\nimport { parseHttpAuth } from \"@milaboratories/pl-model-common\";\nimport { plHealthCheck, ServingStatus } from \"@milaboratories/pl-healthcheck\";\n\nexport const LocalConfigYaml = \"config-local.yaml\";\n\n/*\n Represents a local running pl-core,\n * and has methods to start, check if it's running, stop and wait for stopping it.\n * Also, a hook on pl-core closed can be provided.\n /\nexport class LocalPl {\n private instance?: ChildProcess;\n public pid?: number;\n private nRuns: number = 0;\n private lastRunHistory: Trace = {};\n private wasStopped = false;\n\n constructor(\n private readonly logger: MiLogger,\n private readonly workingDir: string,\n private readonly startOptions: ProcessOptions,\n private readonly initialStartHistory: Trace,\n private readonly grpcPort?: number,\n private readonly onClose?: (pl: LocalPl) => Promise<void>,\n private readonly onError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>,\n ) {}\n\n async start() {\n await withTrace(this.logger, async (trace, t) => {\n this.wasStopped = false;\n const instance = processRun(this.logger, this.startOptions);\n instance.on(\"error\", (e: any) => {\n this.logger.error(\n `error '${e}', while running platforma, started opts: ${JSON.stringify(this.debugInfo())}`,\n );\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onError !== undefined) void this.onError(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n instance.on(\"close\", () => {\n this.logger.warn(`platforma was closed, started opts: ${JSON.stringify(this.debugInfo())}`);\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onClose !== undefined) void this.onClose(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n\n trace(\"started\", true);\n\n const pidFile = trace(\"pidFile\", filePid(this.workingDir));\n trace(\"pid\", notEmpty(instance.pid));\n trace(\"pidWritten\", await writePid(pidFile, notEmpty(instance.pid)));\n\n this.nRuns++;\n this.instance = instance;\n this.pid = instance.pid;\n this.lastRunHistory = t;\n });\n }\n\n stop() {\n // TODO use this.instance to stop the process\n this.wasStopped = true;\n processStop(notEmpty(this.pid));\n }\n\n async waitStopped() {\n await processWaitStopped(notEmpty(this.pid), 15000);\n }\n\n stopped() {\n return this.wasStopped;\n }\n\n /\n Polls the OS until the backend process is observed alive.\n * Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.\n /\n async isAlive(opts?: { timeoutMs?: number; pollIntervalMs?: number }): Promise<void> {\n const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);\n const pollMs = opts?.pollIntervalMs ?? 500;\n\n while (true) {\n if (Date.now() >= deadline) {\n throw new Error(\"Timeout waiting for backend process to be alive\");\n }\n await sleep(pollMs);\n if (!this.pid) continue;\n if (await isProcessAlive(this.pid)) return;\n }\n }\n\n /\n Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.\n * Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.\n \n Calling this method is an explicit statement that the caller wants a real\n * readiness signal; if `grpcPort` is undefined we throw rather than silently\n * degrade to a process-only check (use {@link isAlive} for that).\n /\n async isReady(opts?: {\n grpcPort?: number;\n timeoutMs?: number;\n pollIntervalMs?: number;\n }): Promise<void> {\n const grpcPort = opts?.grpcPort ?? this.grpcPort;\n\n if (grpcPort === undefined) {\n throw new Error(\n \"isReady requires grpcPort to be configured — caller asked for a real readiness check but no gRPC port is available\",\n );\n }\n\n const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);\n const pollMs = opts?.pollIntervalMs ?? 500;\n const requestTimeoutMs = Math.max(500, Math.min(pollMs, 2_000));\n\n let processAlive = false;\n let wasAlive = false;\n let isFirstCheck = true;\n\n while (true) {\n if (Date.now() >= deadline) {\n if (!processAlive) {\n throw new Error(\"Timeout waiting for backend process to be alive\");\n }\n throw new Error(\"Timeout waiting for backend to be ready\");\n }\n\n if (!isFirstCheck) await sleep(pollMs);\n isFirstCheck = false;\n\n if (!this.pid) continue;\n\n processAlive = await isProcessAlive(this.pid);\n wasAlive = wasAlive \|\| processAlive;\n if (!processAlive) {\n if (wasAlive) {\n // saw the process alive at least once, now it's gone — definitive failure\n throw new Error(\"Backend process died while waiting for readiness\");\n }\n continue;\n }\n\n try {\n const status = await plHealthCheck({\n address: `127.0.0.1:${grpcPort}`,\n defaultRequestTimeout: requestTimeoutMs,\n });\n if (status === ServingStatus.SERVING) return;\n } catch {\n // not yet serving\n }\n }\n }\n\n debugInfo() {\n return {\n lastRunHistory: this.lastRunHistory,\n nRuns: this.nRuns,\n pid: this.pid,\n workingDir: this.workingDir,\n initialStartHistory: this.initialStartHistory,\n wasStopped: this.wasStopped,\n };\n }\n}\n\n/* Options to start a local pl-core. /\nexport type LocalPlOptions = {\n /* From what directory start a process. /\n readonly workingDir: string;\n /* A string representation of yaml config. /\n readonly config: string;\n /* How to get a binary, download it or get an existing one (default: download latest version) /\n readonly plBinary?: PlBinarySource;\n /* Additional options for a process, environments, stdout, stderr etc. /\n readonly spawnOptions?: SpawnOptions;\n /\n If the previous pl-core was started from the same directory,\n * we can check if it's still running and then stop it before starting a new one.\n * (default: true)\n /\n readonly closeOld?: boolean;\n /\n Proxy settings to use to fetch the binary and pass it down\n * as a HTTPS_PROXY/HTTP_PROXY environment variable;\n * Backend only supports Basic auth.\n /\n readonly proxy?: ProxySettings;\n\n /\n gRPC port the backend listens on (always on 127.0.0.1 for local).\n * Required by {@link LocalPl.isReady}, which polls\n * `grpc.health.v1.Health/Check` against this port to distinguish a process\n * that is alive but still initializing from one actually serving gRPC.\n /\n readonly grpcPort?: number;\n\n readonly onClose?: (pl: LocalPl) => Promise<void>;\n readonly onError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>;\n};\n\nexport type LocalPlOptionsFull = Required<LocalPlOptions, \"plBinary\" \| \"spawnOptions\" \| \"closeOld\">;\n\n/\n Starts pl-core, if the option was provided downloads a binary, reads license environments etc.\n /\nexport async function localPlatformaInit(logger: MiLogger, _ops: LocalPlOptions): Promise<LocalPl> {\n // filling-in default values\n\n // Backend could consume a lot of CPU power,\n // we want to keep at least a couple for UI and other apps to work.\n const numCpu = Math.max(os.cpus().length - 2, 1);\n const ops = mergeDefaultOps(_ops, numCpu);\n\n return await withTrace(logger, async (trace, t) => {\n trace(\"startOptions\", { ...ops, config: \"too wordy\" });\n\n const workDir = upath.resolve(ops.workingDir);\n\n if (ops.closeOld) {\n trace(\"closeOld\", await localPlatformaReadPidAndStop(logger, workDir));\n }\n\n const configPath = upath.join(workDir, LocalConfigYaml);\n\n logger.info(`writing configuration '${configPath}'...`);\n await fsp.writeFile(configPath, ops.config);\n\n const plBinPath = upath.join(workDir, \"binaries\");\n const baseBinaryPath = await resolveLocalPlBinaryPath({\n logger,\n downloadDir: plBinPath,\n src: ops.plBinary,\n dispatcher: defaultHttpDispatcher(ops.proxy),\n });\n const binaryPath = trace(\"binaryPath\", upath.join(\"binaries\", baseBinaryPath));\n\n const env = { ...process.env };\n\n if (ops.proxy?.url) {\n const url = new URL(ops.proxy.url);\n if (ops.proxy.auth) {\n const parsed = parseHttpAuth(ops.proxy.auth);\n if (parsed.scheme !== \"Basic\") {\n throw new Error(`\\\nUnsupported auth scheme: ${parsed.scheme}. \\\nOnly Basic auth is supported by the backend.`);\n }\n url.username = parsed.username;\n url.password = parsed.password;\n }\n env.http_proxy = url.toString();\n env.https_proxy = url.toString();\n }\n\n const processOpts = plProcessOps(binaryPath, configPath, ops, workDir, env);\n trace(\"processOpts\", {\n cmd: processOpts.cmd,\n args: processOpts.args,\n cwd: processOpts.opts.cwd,\n });\n\n const pl = new LocalPl(\n logger,\n ops.workingDir,\n processOpts,\n t,\n ops.grpcPort,\n ops.onClose,\n ops.onError,\n ops.onCloseAndError,\n ops.onCloseAndErrorNoStop,\n );\n await pl.start();\n\n return pl;\n });\n}\n\n/* Reads a pid of the old pl-core if it was started in the same working directory,\n * and closes it. /\nasync function localPlatformaReadPidAndStop(\n logger: MiLogger,\n workingDir: string,\n): Promise<Record<string, any>> {\n return await withTrace(logger, async (trace, t) => {\n const file = trace(\"pidFilePath\", filePid(workingDir));\n\n const oldPid = trace(\"pid\", await readPid(file));\n const alive = trace(\"wasAlive\", await isProcessAlive(oldPid));\n\n if (oldPid !== undefined && alive) {\n trace(\"stopped\", processStop(oldPid));\n try {\n trace(\"waitStopped\", await processWaitStopped(oldPid, 15_000)); // larger, that 10s we provide to backend in config.\n } catch {\n trace(\"forceStopped\", processStop(oldPid, true));\n trace(\"waitForceStopped\", await processWaitStopped(oldPid, 5_000));\n }\n }\n\n return t;\n });\n}\n\n/* Gets default options for the whole init process\n * and overrides them with the provided options. /\nexport function mergeDefaultOps(ops: LocalPlOptions, numCpu: number): LocalPlOptionsFull {\n const result: {\n plBinary: PlBinarySource;\n spawnOptions: SpawnOptions;\n closeOld: boolean;\n } = {\n plBinary: newDefaultPlBinarySource(),\n spawnOptions: {\n env: {\n GOMAXPROCS: String(numCpu),\n },\n },\n closeOld: true,\n };\n\n if (ops.spawnOptions?.env) {\n result.spawnOptions.env = { ...result.spawnOptions.env, ...ops.spawnOptions.env };\n }\n\n if (ops.spawnOptions) {\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.spawnOptions = { ...result.spawnOptions, ...withoutEnv };\n }\n\n const withoutSpawnOps = { ...ops };\n delete withoutSpawnOps[\"spawnOptions\"];\n\n return { ...result, ...withoutSpawnOps };\n}\n\n/* Gets default options for a platforma local binary\n * and overrides them with the provided options. */\nexport function plProcessOps(\n binaryPath: any,\n configPath: string,\n ops: LocalPlOptionsFull,\n workDir: string,\n defaultEnv: Record<string, string \| undefined>,\n): ProcessOptions {\n const result: ProcessOptions = {\n cmd: binaryPath,\n args: [\"--config\", configPath],\n opts: {\n env: { ...defaultEnv },\n cwd: workDir,\n stdio: [\"pipe\", \"ignore\", \"inherit\"],\n windowsHide: true, // hide a terminal on Windows\n },\n };\n\n if (ops.spawnOptions?.env) {\n result.opts.env = { ...result.opts.env, ...ops.spawnOptions.env };\n }\n\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.opts = { ...result.opts, ...withoutEnv };\n\n return result;\n}\n"],"mappings":"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"}

package/dist/local/pl.d.ts CHANGED Viewed

@@ -18,6 +18,7 @@ declare class LocalPl {
   private readonly workingDir;
   private readonly startOptions;
   private readonly initialStartHistory;
+  private readonly grpcPort?;
   private readonly onClose?;
   private readonly onError?;
   private readonly onCloseAndError?;
@@ -27,12 +28,32 @@ declare class LocalPl {
   private nRuns;
   private lastRunHistory;
   private wasStopped;
-  constructor(logger: MiLogger, workingDir: string, startOptions: ProcessOptions, initialStartHistory: Trace, onClose?: ((pl: LocalPl) => Promise<void>) | undefined, onError?: ((pl: LocalPl) => Promise<void>) | undefined, onCloseAndError?: ((pl: LocalPl) => Promise<void>) | undefined, onCloseAndErrorNoStop?: ((pl: LocalPl) => Promise<void>) | undefined);
+  constructor(logger: MiLogger, workingDir: string, startOptions: ProcessOptions, initialStartHistory: Trace, grpcPort?: number | undefined, onClose?: ((pl: LocalPl) => Promise<void>) | undefined, onError?: ((pl: LocalPl) => Promise<void>) | undefined, onCloseAndError?: ((pl: LocalPl) => Promise<void>) | undefined, onCloseAndErrorNoStop?: ((pl: LocalPl) => Promise<void>) | undefined);
   start(): Promise<void>;
   stop(): void;
   waitStopped(): Promise<void>;
   stopped(): boolean;
-  isAlive(): Promise<boolean>;
+  /**
+   * Polls the OS until the backend process is observed alive.
+   * Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.
+   */
+  isAlive(opts?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+  }): Promise<void>;
+  /**
+   * Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.
+   * Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.
+   *
+   * Calling this method is an explicit statement that the caller wants a real
+   * readiness signal; if `grpcPort` is undefined we throw rather than silently
+   * degrade to a process-only check (use {@link isAlive} for that).
+   */
+  isReady(opts?: {
+    grpcPort?: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+  }): Promise<void>;
   debugInfo(): {
     lastRunHistory: Trace;
     nRuns: number;
@@ -60,6 +81,13 @@ type LocalPlOptions = {
    * Backend only supports Basic auth.
    */
   readonly proxy?: ProxySettings;
+  /**
+   * gRPC port the backend listens on (always on 127.0.0.1 for local).
+   * Required by {@link LocalPl.isReady}, which polls
+   * `grpc.health.v1.Health/Check` against this port to distinguish a process
+   * that is alive but still initializing from one actually serving gRPC.
+   */
+  readonly grpcPort?: number;
   readonly onClose?: (pl: LocalPl) => Promise<void>;
   readonly onError?: (pl: LocalPl) => Promise<void>;
   readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;

package/dist/local/pl.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"pl.d.ts","names":[],"sources":["../../src/local/pl.ts"],"mappings":";;;;;;;;;~~cAkBa~~,eAAA;;AAAb;;;;cAOa,OAAA;EAAA,iBAQQ,MAAA;EAAA,iBACA,UAAA;EAAA,iBACA,YAAA;EAAA,iBACA,mBAAA;EAAA,iBACA,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,qBAAA;EAAA,~~QAdX~~,QAAA;EACD,GAAA;EAAA,QACC,KAAA;EAAA,QACA,cAAA;EAAA,QACA,UAAA;cAGW,MAAA,EAAQ,QAAA,EACR,UAAA,UACA,YAAA,EAAc,cAAA,EACd,mBAAA,EAAqB,KAAA,EACrB,OAAA,KAAW,EAAA,EAAI,OAAA,KAAY,OAAA,qBAC3B,OAAA,KAAW,EAAA,EAAI,OAAA,KAAY,OAAA,qBAC3B,eAAA,KAAmB,EAAA,EAAI,OAAA,KAAY,OAAA,qBACnC,qBAAA,KAAyB,EAAA,EAAI,OAAA,KAAY,OAAA;EAGtD,KAAA,CAAA,GAAK,OAAA;EAsCX,IAAA,CAAA;EAMM,WAAA,CAAA,GAAW,OAAA;EAIjB,OAAA,CAAA;~~EAIM~~,OAAA,~~CAAA~~,~~GAAW~~,OAAA;~~EAIjB~~,SAAA,CAAA;;;;;;;;;;KAaU,cAAA;~~EArFH~~,~~oDAuFE~~,UAAA,~~UArFD~~;EAAA,~~SAuFC~~,MAAA;~~WAEA~~,QAAA,GAAW,cAAA,~~EArFD~~;EAAA,~~SAuFV~~,YAAA,GAAe,YAAA;~~EArFS~~;;;;;EAAA,~~SA2FxB~~,QAAA;~~EAzFqC~~;;;;;EAAA,~~SA+FrC~~,KAAA,GAAQ,aAAA;EAAA,~~SAER~~,OAAA,IAAW,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SAC3B,OAAA,IAAW,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SAC3B,eAAA,IAAmB,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SACnC,qBAAA,IAAyB,EAAA,EAAI,OAAA,KAAY,OAAA;AAAA;AAAA,KAGxC,kBAAA,GAAqB,QAAA,CAAS,cAAA;;;;iBAKpB,kBAAA,CAAmB,MAAA,EAAQ,QAAA,EAAU,IAAA,EAAM,cAAA,GAAiB,OAAA,CAAQ,OAAA~~;;;iBAoG1E~~,eAAA,CAAgB,GAAA,EAAK,cAAA,EAAgB,MAAA,WAAiB,kBAAA;;;iBAiCtD,YAAA,CACd,UAAA,OACA,UAAA,UACA,GAAA,EAAK,kBAAA,EACL,OAAA,UACA,UAAA,EAAY,MAAA,+BACX,cAAA"}
1	+ {"version":3,"file":"pl.d.ts","names":[],"sources":["../../src/local/pl.ts"],"mappings":";;;;;;;;;cAoBa,eAAA;;AAAb;;;;cAOa,OAAA;EAAA,iBAQQ,MAAA;EAAA,iBACA,UAAA;EAAA,iBACA,YAAA;EAAA,iBACA,mBAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,qBAAA;EAAA,QAfX,QAAA;EACD,GAAA;EAAA,QACC,KAAA;EAAA,QACA,cAAA;EAAA,QACA,UAAA;cAGW,MAAA,EAAQ,QAAA,EACR,UAAA,UACA,YAAA,EAAc,cAAA,EACd,mBAAA,EAAqB,KAAA,EACrB,QAAA,uBACA,OAAA,KAAW,EAAA,EAAI,OAAA,KAAY,OAAA,qBAC3B,OAAA,KAAW,EAAA,EAAI,OAAA,KAAY,OAAA,qBAC3B,eAAA,KAAmB,EAAA,EAAI,OAAA,KAAY,OAAA,qBACnC,qBAAA,KAAyB,EAAA,EAAI,OAAA,KAAY,OAAA;EAGtD,KAAA,CAAA,GAAK,OAAA;EAsCX,IAAA,CAAA;EAMM,WAAA,CAAA,GAAW,OAAA;EAIjB,OAAA,CAAA;;;;;EAQM,OAAA,CAAQ,IAAA;IAAS,SAAA;IAAoB,cAAA;EAAA,IAA4B,OAAA;EA9DpD;;;;;;;;EAoFb,OAAA,CAAQ,IAAA;IACZ,QAAA;IACA,SAAA;IACA,cAAA;EAAA,IACE,OAAA;EAoDJ,SAAA,CAAA;;;;;;;;;;KAaU,cAAA;EAxJoC,oDA0JrC,UAAA,UAzJiC;EAAA,SA2JjC,MAAA,UA3J6C;EAAA,SA6J7C,QAAA,GAAW,cAAA,EA5J4B;EAAA,SA8JvC,YAAA,GAAe,YAAA;EA9JoC;;;;;EAAA,SAoKnD,QAAA;EArHQ;;;;;EAAA,SA2HR,KAAA,GAAQ,aAAA;EA/GsD;;;;;;EAAA,SAuH9D,QAAA;EAAA,SAEA,OAAA,IAAW,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SAC3B,OAAA,IAAW,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SAC3B,eAAA,IAAmB,EAAA,EAAI,OAAA,KAAY,OAAA;EAAA,SACnC,qBAAA,IAAyB,EAAA,EAAI,OAAA,KAAY,OAAA;AAAA;AAAA,KAGxC,kBAAA,GAAqB,QAAA,CAAS,cAAA;;;;iBAKpB,kBAAA,CAAmB,MAAA,EAAQ,QAAA,EAAU,IAAA,EAAM,cAAA,GAAiB,OAAA,CAAQ,OAAA;;AAzC1F;iBA8IgB,eAAA,CAAgB,GAAA,EAAK,cAAA,EAAgB,MAAA,WAAiB,kBAAA;;;iBAiCtD,YAAA,CACd,UAAA,OACA,UAAA,UACA,GAAA,EAAK,kBAAA,EACL,OAAA,UACA,UAAA,EAAY,MAAA,+BACX,cAAA"}

package/dist/local/pl.js CHANGED Viewed

@@ -2,12 +2,13 @@ import { isProcessAlive, processRun, processStop, processWaitStopped } from "./p
 import { newDefaultPlBinarySource, resolveLocalPlBinaryPath } from "../common/pl_binary.js";
 import { filePid, readPid, writePid } from "./pid.js";
 import { withTrace } from "./trace.js";
-import { notEmpty } from "@milaboratories/ts-helpers";
+import { notEmpty, sleep } from "@milaboratories/ts-helpers";
 import fsp from "node:fs/promises";
 import upath from "upath";
 import * as os$1 from "node:os";
 import { defaultHttpDispatcher } from "@milaboratories/pl-http";
 import { parseHttpAuth } from "@milaboratories/pl-model-common";
+import { ServingStatus, plHealthCheck } from "@milaboratories/pl-healthcheck";
 //#region src/local/pl.ts
 const LocalConfigYaml = "config-local.yaml";
 /**
@@ -21,11 +22,12 @@ var LocalPl = class {
 	nRuns = 0;
 	lastRunHistory = {};
 	wasStopped = false;
-	constructor(logger, workingDir, startOptions, initialStartHistory, onClose, onError, onCloseAndError, onCloseAndErrorNoStop) {
+	constructor(logger, workingDir, startOptions, initialStartHistory, grpcPort, onClose, onError, onCloseAndError, onCloseAndErrorNoStop) {
 		this.logger = logger;
 		this.workingDir = workingDir;
 		this.startOptions = startOptions;
 		this.initialStartHistory = initialStartHistory;
+		this.grpcPort = grpcPort;
 		this.onClose = onClose;
 		this.onError = onError;
 		this.onCloseAndError = onCloseAndError;
@@ -67,8 +69,58 @@ var LocalPl = class {
 	stopped() {
 		return this.wasStopped;
 	}
-	async isAlive() {
-		return await isProcessAlive(notEmpty(this.pid));
+	/**
+	* Polls the OS until the backend process is observed alive.
+	* Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.
+	*/
+	async isAlive(opts) {
+		const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+		const pollMs = opts?.pollIntervalMs ?? 500;
+		while (true) {
+			if (Date.now() >= deadline) throw new Error("Timeout waiting for backend process to be alive");
+			await sleep(pollMs);
+			if (!this.pid) continue;
+			if (await isProcessAlive(this.pid)) return;
+		}
+	}
+	/**
+	* Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.
+	* Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.
+	*
+	* Calling this method is an explicit statement that the caller wants a real
+	* readiness signal; if `grpcPort` is undefined we throw rather than silently
+	* degrade to a process-only check (use {@link isAlive} for that).
+	*/
+	async isReady(opts) {
+		const grpcPort = opts?.grpcPort ?? this.grpcPort;
+		if (grpcPort === void 0) throw new Error("isReady requires grpcPort to be configured — caller asked for a real readiness check but no gRPC port is available");
+		const deadline = Date.now() + (opts?.timeoutMs ?? 12e4);
+		const pollMs = opts?.pollIntervalMs ?? 500;
+		const requestTimeoutMs = Math.max(500, Math.min(pollMs, 2e3));
+		let processAlive = false;
+		let wasAlive = false;
+		let isFirstCheck = true;
+		while (true) {
+			if (Date.now() >= deadline) {
+				if (!processAlive) throw new Error("Timeout waiting for backend process to be alive");
+				throw new Error("Timeout waiting for backend to be ready");
+			}
+			if (!isFirstCheck) await sleep(pollMs);
+			isFirstCheck = false;
+			if (!this.pid) continue;
+			processAlive = await isProcessAlive(this.pid);
+			wasAlive = wasAlive || processAlive;
+			if (!processAlive) {
+				if (wasAlive) throw new Error("Backend process died while waiting for readiness");
+				continue;
+			}
+			try {
+				if (await plHealthCheck({
+					address: `127.0.0.1:${grpcPort}`,
+					defaultRequestTimeout: requestTimeoutMs
+				}) === ServingStatus.SERVING) return;
+			} catch {}
+		}
 	}
 	debugInfo() {
 		return {
@@ -123,7 +175,7 @@ Only Basic auth is supported by the backend.`);
 			args: processOpts.args,
 			cwd: processOpts.opts.cwd
 		});
-		const pl = new LocalPl(logger, ops.workingDir, processOpts, t, ops.onClose, ops.onError, ops.onCloseAndError, ops.onCloseAndErrorNoStop);
+		const pl = new LocalPl(logger, ops.workingDir, processOpts, t, ops.grpcPort, ops.onClose, ops.onError, ops.onCloseAndError, ops.onCloseAndErrorNoStop);
 		await pl.start();
 		return pl;
 	});

package/dist/local/pl.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"pl.js","names":["os"],"sources":["../../src/local/pl.ts"],"sourcesContent":["import type { ProcessOptions } from \"./process\";\nimport { isProcessAlive, processStop, processWaitStopped, processRun } from \"./process\";\nimport type { PlBinarySource } from \"../common/pl_binary\";\nimport { newDefaultPlBinarySource, resolveLocalPlBinaryPath } from \"../common/pl_binary\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { notEmpty } from \"@milaboratories/ts-helpers\";\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { filePid, readPid, writePid } from \"./pid\";\nimport type { Trace } from \"./trace\";\nimport { withTrace } from \"./trace\";\nimport upath from \"upath\";\nimport fsp from \"node:fs/promises\";\nimport type { Required } from \"utility-types\";\nimport * as os from \"node:os\";\nimport type { ProxySettings } from \"@milaboratories/pl-http\";\nimport { defaultHttpDispatcher } from \"@milaboratories/pl-http\";\nimport { parseHttpAuth } from \"@milaboratories/pl-model-common\";\n\nexport const LocalConfigYaml = \"config-local.yaml\";\n\n/*\n Represents a local running pl-core,\n * and has methods to start, check if it's running, stop and wait for stopping it.\n * Also, a hook on pl-core closed can be provided.\n /\nexport class LocalPl {\n private instance?: ChildProcess;\n public pid?: number;\n private nRuns: number = 0;\n private lastRunHistory: Trace = {};\n private wasStopped = false;\n\n constructor(\n private readonly logger: MiLogger,\n private readonly workingDir: string,\n private readonly startOptions: ProcessOptions,\n private readonly initialStartHistory: Trace,\n private readonly onClose?: (pl: LocalPl) => Promise<void>,\n private readonly onError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>,\n ) {}\n\n async start() {\n await withTrace(this.logger, async (trace, t) => {\n this.wasStopped = false;\n const instance = processRun(this.logger, this.startOptions);\n instance.on(\"error\", (e: any) => {\n this.logger.error(\n `error '${e}', while running platforma, started opts: ${JSON.stringify(this.debugInfo())}`,\n );\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onError !== undefined) void this.onError(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n instance.on(\"close\", () => {\n this.logger.warn(`platforma was closed, started opts: ${JSON.stringify(this.debugInfo())}`);\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onClose !== undefined) void this.onClose(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n\n trace(\"started\", true);\n\n const pidFile = trace(\"pidFile\", filePid(this.workingDir));\n trace(\"pid\", notEmpty(instance.pid));\n trace(\"pidWritten\", await writePid(pidFile, notEmpty(instance.pid)));\n\n this.nRuns++;\n this.instance = instance;\n this.pid = instance.pid;\n this.lastRunHistory = t;\n });\n }\n\n stop() {\n // TODO use this.instance to stop the process\n this.wasStopped = true;\n processStop(notEmpty(this.pid));\n }\n\n async waitStopped() {\n await processWaitStopped(notEmpty(this.pid), 15000);\n }\n\n stopped() {\n return this.wasStopped;\n }\n\n async isAlive(): Promise<boolean> {\n return await isProcessAlive(notEmpty(this.pid));\n }\n\n debugInfo() {\n return {\n lastRunHistory: this.lastRunHistory,\n nRuns: this.nRuns,\n pid: this.pid,\n workingDir: this.workingDir,\n initialStartHistory: this.initialStartHistory,\n wasStopped: this.wasStopped,\n };\n }\n}\n\n/* Options to start a local pl-core. /\nexport type LocalPlOptions = {\n /* From what directory start a process. /\n readonly workingDir: string;\n /* A string representation of yaml config. /\n readonly config: string;\n /* How to get a binary, download it or get an existing one (default: download latest version) /\n readonly plBinary?: PlBinarySource;\n /* Additional options for a process, environments, stdout, stderr etc. /\n readonly spawnOptions?: SpawnOptions;\n /\n If the previous pl-core was started from the same directory,\n * we can check if it's still running and then stop it before starting a new one.\n * (default: true)\n /\n readonly closeOld?: boolean;\n /\n Proxy settings to use to fetch the binary and pass it down\n * as a HTTPS_PROXY/HTTP_PROXY environment variable;\n * Backend only supports Basic auth.\n /\n readonly proxy?: ProxySettings;\n\n readonly onClose?: (pl: LocalPl) => Promise<void>;\n readonly onError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>;\n};\n\nexport type LocalPlOptionsFull = Required<LocalPlOptions, \"plBinary\" \| \"spawnOptions\" \| \"closeOld\">;\n\n/\n Starts pl-core, if the option was provided downloads a binary, reads license environments etc.\n /\nexport async function localPlatformaInit(logger: MiLogger, _ops: LocalPlOptions): Promise<LocalPl> {\n // filling-in default values\n\n // Backend could consume a lot of CPU power,\n // we want to keep at least a couple for UI and other apps to work.\n const numCpu = Math.max(os.cpus().length - 2, 1);\n const ops = mergeDefaultOps(_ops, numCpu);\n\n return await withTrace(logger, async (trace, t) => {\n trace(\"startOptions\", { ...ops, config: \"too wordy\" });\n\n const workDir = upath.resolve(ops.workingDir);\n\n if (ops.closeOld) {\n trace(\"closeOld\", await localPlatformaReadPidAndStop(logger, workDir));\n }\n\n const configPath = upath.join(workDir, LocalConfigYaml);\n\n logger.info(`writing configuration '${configPath}'...`);\n await fsp.writeFile(configPath, ops.config);\n\n const plBinPath = upath.join(workDir, \"binaries\");\n const baseBinaryPath = await resolveLocalPlBinaryPath({\n logger,\n downloadDir: plBinPath,\n src: ops.plBinary,\n dispatcher: defaultHttpDispatcher(ops.proxy),\n });\n const binaryPath = trace(\"binaryPath\", upath.join(\"binaries\", baseBinaryPath));\n\n const env = { ...process.env };\n\n if (ops.proxy?.url) {\n const url = new URL(ops.proxy.url);\n if (ops.proxy.auth) {\n const parsed = parseHttpAuth(ops.proxy.auth);\n if (parsed.scheme !== \"Basic\") {\n throw new Error(`\\\nUnsupported auth scheme: ${parsed.scheme}. \\\nOnly Basic auth is supported by the backend.`);\n }\n url.username = parsed.username;\n url.password = parsed.password;\n }\n env.http_proxy = url.toString();\n env.https_proxy = url.toString();\n }\n\n const processOpts = plProcessOps(binaryPath, configPath, ops, workDir, env);\n trace(\"processOpts\", {\n cmd: processOpts.cmd,\n args: processOpts.args,\n cwd: processOpts.opts.cwd,\n });\n\n const pl = new LocalPl(\n logger,\n ops.workingDir,\n processOpts,\n t,\n ops.onClose,\n ops.onError,\n ops.onCloseAndError,\n ops.onCloseAndErrorNoStop,\n );\n await pl.start();\n\n return pl;\n });\n}\n\n/* Reads a pid of the old pl-core if it was started in the same working directory,\n * and closes it. /\nasync function localPlatformaReadPidAndStop(\n logger: MiLogger,\n workingDir: string,\n): Promise<Record<string, any>> {\n return await withTrace(logger, async (trace, t) => {\n const file = trace(\"pidFilePath\", filePid(workingDir));\n\n const oldPid = trace(\"pid\", await readPid(file));\n const alive = trace(\"wasAlive\", await isProcessAlive(oldPid));\n\n if (oldPid !== undefined && alive) {\n trace(\"stopped\", processStop(oldPid));\n try {\n trace(\"waitStopped\", await processWaitStopped(oldPid, 15_000)); // larger, that 10s we provide to backend in config.\n } catch {\n trace(\"forceStopped\", processStop(oldPid, true));\n trace(\"waitForceStopped\", await processWaitStopped(oldPid, 5_000));\n }\n }\n\n return t;\n });\n}\n\n/* Gets default options for the whole init process\n * and overrides them with the provided options. /\nexport function mergeDefaultOps(ops: LocalPlOptions, numCpu: number): LocalPlOptionsFull {\n const result: {\n plBinary: PlBinarySource;\n spawnOptions: SpawnOptions;\n closeOld: boolean;\n } = {\n plBinary: newDefaultPlBinarySource(),\n spawnOptions: {\n env: {\n GOMAXPROCS: String(numCpu),\n },\n },\n closeOld: true,\n };\n\n if (ops.spawnOptions?.env) {\n result.spawnOptions.env = { ...result.spawnOptions.env, ...ops.spawnOptions.env };\n }\n\n if (ops.spawnOptions) {\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.spawnOptions = { ...result.spawnOptions, ...withoutEnv };\n }\n\n const withoutSpawnOps = { ...ops };\n delete withoutSpawnOps[\"spawnOptions\"];\n\n return { ...result, ...withoutSpawnOps };\n}\n\n/* Gets default options for a platforma local binary\n * and overrides them with the provided options. */\nexport function plProcessOps(\n binaryPath: any,\n configPath: string,\n ops: LocalPlOptionsFull,\n workDir: string,\n defaultEnv: Record<string, string \| undefined>,\n): ProcessOptions {\n const result: ProcessOptions = {\n cmd: binaryPath,\n args: [\"--config\", configPath],\n opts: {\n env: { ...defaultEnv },\n cwd: workDir,\n stdio: [\"pipe\", \"ignore\", \"inherit\"],\n windowsHide: true, // hide a terminal on Windows\n },\n };\n\n if (ops.spawnOptions?.env) {\n result.opts.env = { ...result.opts.env, ...ops.spawnOptions.env };\n }\n\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.opts = { ...result.opts, ...withoutEnv };\n\n return result;\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"pl.js","names":["os"],"sources":["../../src/local/pl.ts"],"sourcesContent":["import type { ProcessOptions } from \"./process\";\nimport { isProcessAlive, processStop, processWaitStopped, processRun } from \"./process\";\nimport type { PlBinarySource } from \"../common/pl_binary\";\nimport { newDefaultPlBinarySource, resolveLocalPlBinaryPath } from \"../common/pl_binary\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { notEmpty } from \"@milaboratories/ts-helpers\";\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { filePid, readPid, writePid } from \"./pid\";\nimport type { Trace } from \"./trace\";\nimport { withTrace } from \"./trace\";\nimport upath from \"upath\";\nimport fsp from \"node:fs/promises\";\nimport type { Required } from \"utility-types\";\nimport * as os from \"node:os\";\nimport { sleep } from \"@milaboratories/ts-helpers\";\nimport type { ProxySettings } from \"@milaboratories/pl-http\";\nimport { defaultHttpDispatcher } from \"@milaboratories/pl-http\";\nimport { parseHttpAuth } from \"@milaboratories/pl-model-common\";\nimport { plHealthCheck, ServingStatus } from \"@milaboratories/pl-healthcheck\";\n\nexport const LocalConfigYaml = \"config-local.yaml\";\n\n/*\n Represents a local running pl-core,\n * and has methods to start, check if it's running, stop and wait for stopping it.\n * Also, a hook on pl-core closed can be provided.\n /\nexport class LocalPl {\n private instance?: ChildProcess;\n public pid?: number;\n private nRuns: number = 0;\n private lastRunHistory: Trace = {};\n private wasStopped = false;\n\n constructor(\n private readonly logger: MiLogger,\n private readonly workingDir: string,\n private readonly startOptions: ProcessOptions,\n private readonly initialStartHistory: Trace,\n private readonly grpcPort?: number,\n private readonly onClose?: (pl: LocalPl) => Promise<void>,\n private readonly onError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndError?: (pl: LocalPl) => Promise<void>,\n private readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>,\n ) {}\n\n async start() {\n await withTrace(this.logger, async (trace, t) => {\n this.wasStopped = false;\n const instance = processRun(this.logger, this.startOptions);\n instance.on(\"error\", (e: any) => {\n this.logger.error(\n `error '${e}', while running platforma, started opts: ${JSON.stringify(this.debugInfo())}`,\n );\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onError !== undefined) void this.onError(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n instance.on(\"close\", () => {\n this.logger.warn(`platforma was closed, started opts: ${JSON.stringify(this.debugInfo())}`);\n\n // keep in mind there are no awaits here, it will be asynchronous\n if (this.onClose !== undefined) void this.onClose(this);\n if (this.onCloseAndError !== undefined) void this.onCloseAndError(this);\n if (this.onCloseAndErrorNoStop !== undefined && !this.wasStopped)\n void this.onCloseAndErrorNoStop(this);\n });\n\n trace(\"started\", true);\n\n const pidFile = trace(\"pidFile\", filePid(this.workingDir));\n trace(\"pid\", notEmpty(instance.pid));\n trace(\"pidWritten\", await writePid(pidFile, notEmpty(instance.pid)));\n\n this.nRuns++;\n this.instance = instance;\n this.pid = instance.pid;\n this.lastRunHistory = t;\n });\n }\n\n stop() {\n // TODO use this.instance to stop the process\n this.wasStopped = true;\n processStop(notEmpty(this.pid));\n }\n\n async waitStopped() {\n await processWaitStopped(notEmpty(this.pid), 15000);\n }\n\n stopped() {\n return this.wasStopped;\n }\n\n /\n Polls the OS until the backend process is observed alive.\n * Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.\n /\n async isAlive(opts?: { timeoutMs?: number; pollIntervalMs?: number }): Promise<void> {\n const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);\n const pollMs = opts?.pollIntervalMs ?? 500;\n\n while (true) {\n if (Date.now() >= deadline) {\n throw new Error(\"Timeout waiting for backend process to be alive\");\n }\n await sleep(pollMs);\n if (!this.pid) continue;\n if (await isProcessAlive(this.pid)) return;\n }\n }\n\n /\n Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.\n * Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.\n \n Calling this method is an explicit statement that the caller wants a real\n * readiness signal; if `grpcPort` is undefined we throw rather than silently\n * degrade to a process-only check (use {@link isAlive} for that).\n /\n async isReady(opts?: {\n grpcPort?: number;\n timeoutMs?: number;\n pollIntervalMs?: number;\n }): Promise<void> {\n const grpcPort = opts?.grpcPort ?? this.grpcPort;\n\n if (grpcPort === undefined) {\n throw new Error(\n \"isReady requires grpcPort to be configured — caller asked for a real readiness check but no gRPC port is available\",\n );\n }\n\n const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);\n const pollMs = opts?.pollIntervalMs ?? 500;\n const requestTimeoutMs = Math.max(500, Math.min(pollMs, 2_000));\n\n let processAlive = false;\n let wasAlive = false;\n let isFirstCheck = true;\n\n while (true) {\n if (Date.now() >= deadline) {\n if (!processAlive) {\n throw new Error(\"Timeout waiting for backend process to be alive\");\n }\n throw new Error(\"Timeout waiting for backend to be ready\");\n }\n\n if (!isFirstCheck) await sleep(pollMs);\n isFirstCheck = false;\n\n if (!this.pid) continue;\n\n processAlive = await isProcessAlive(this.pid);\n wasAlive = wasAlive \|\| processAlive;\n if (!processAlive) {\n if (wasAlive) {\n // saw the process alive at least once, now it's gone — definitive failure\n throw new Error(\"Backend process died while waiting for readiness\");\n }\n continue;\n }\n\n try {\n const status = await plHealthCheck({\n address: `127.0.0.1:${grpcPort}`,\n defaultRequestTimeout: requestTimeoutMs,\n });\n if (status === ServingStatus.SERVING) return;\n } catch {\n // not yet serving\n }\n }\n }\n\n debugInfo() {\n return {\n lastRunHistory: this.lastRunHistory,\n nRuns: this.nRuns,\n pid: this.pid,\n workingDir: this.workingDir,\n initialStartHistory: this.initialStartHistory,\n wasStopped: this.wasStopped,\n };\n }\n}\n\n/* Options to start a local pl-core. /\nexport type LocalPlOptions = {\n /* From what directory start a process. /\n readonly workingDir: string;\n /* A string representation of yaml config. /\n readonly config: string;\n /* How to get a binary, download it or get an existing one (default: download latest version) /\n readonly plBinary?: PlBinarySource;\n /* Additional options for a process, environments, stdout, stderr etc. /\n readonly spawnOptions?: SpawnOptions;\n /\n If the previous pl-core was started from the same directory,\n * we can check if it's still running and then stop it before starting a new one.\n * (default: true)\n /\n readonly closeOld?: boolean;\n /\n Proxy settings to use to fetch the binary and pass it down\n * as a HTTPS_PROXY/HTTP_PROXY environment variable;\n * Backend only supports Basic auth.\n /\n readonly proxy?: ProxySettings;\n\n /\n gRPC port the backend listens on (always on 127.0.0.1 for local).\n * Required by {@link LocalPl.isReady}, which polls\n * `grpc.health.v1.Health/Check` against this port to distinguish a process\n * that is alive but still initializing from one actually serving gRPC.\n /\n readonly grpcPort?: number;\n\n readonly onClose?: (pl: LocalPl) => Promise<void>;\n readonly onError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;\n readonly onCloseAndErrorNoStop?: (pl: LocalPl) => Promise<void>;\n};\n\nexport type LocalPlOptionsFull = Required<LocalPlOptions, \"plBinary\" \| \"spawnOptions\" \| \"closeOld\">;\n\n/\n Starts pl-core, if the option was provided downloads a binary, reads license environments etc.\n /\nexport async function localPlatformaInit(logger: MiLogger, _ops: LocalPlOptions): Promise<LocalPl> {\n // filling-in default values\n\n // Backend could consume a lot of CPU power,\n // we want to keep at least a couple for UI and other apps to work.\n const numCpu = Math.max(os.cpus().length - 2, 1);\n const ops = mergeDefaultOps(_ops, numCpu);\n\n return await withTrace(logger, async (trace, t) => {\n trace(\"startOptions\", { ...ops, config: \"too wordy\" });\n\n const workDir = upath.resolve(ops.workingDir);\n\n if (ops.closeOld) {\n trace(\"closeOld\", await localPlatformaReadPidAndStop(logger, workDir));\n }\n\n const configPath = upath.join(workDir, LocalConfigYaml);\n\n logger.info(`writing configuration '${configPath}'...`);\n await fsp.writeFile(configPath, ops.config);\n\n const plBinPath = upath.join(workDir, \"binaries\");\n const baseBinaryPath = await resolveLocalPlBinaryPath({\n logger,\n downloadDir: plBinPath,\n src: ops.plBinary,\n dispatcher: defaultHttpDispatcher(ops.proxy),\n });\n const binaryPath = trace(\"binaryPath\", upath.join(\"binaries\", baseBinaryPath));\n\n const env = { ...process.env };\n\n if (ops.proxy?.url) {\n const url = new URL(ops.proxy.url);\n if (ops.proxy.auth) {\n const parsed = parseHttpAuth(ops.proxy.auth);\n if (parsed.scheme !== \"Basic\") {\n throw new Error(`\\\nUnsupported auth scheme: ${parsed.scheme}. \\\nOnly Basic auth is supported by the backend.`);\n }\n url.username = parsed.username;\n url.password = parsed.password;\n }\n env.http_proxy = url.toString();\n env.https_proxy = url.toString();\n }\n\n const processOpts = plProcessOps(binaryPath, configPath, ops, workDir, env);\n trace(\"processOpts\", {\n cmd: processOpts.cmd,\n args: processOpts.args,\n cwd: processOpts.opts.cwd,\n });\n\n const pl = new LocalPl(\n logger,\n ops.workingDir,\n processOpts,\n t,\n ops.grpcPort,\n ops.onClose,\n ops.onError,\n ops.onCloseAndError,\n ops.onCloseAndErrorNoStop,\n );\n await pl.start();\n\n return pl;\n });\n}\n\n/* Reads a pid of the old pl-core if it was started in the same working directory,\n * and closes it. /\nasync function localPlatformaReadPidAndStop(\n logger: MiLogger,\n workingDir: string,\n): Promise<Record<string, any>> {\n return await withTrace(logger, async (trace, t) => {\n const file = trace(\"pidFilePath\", filePid(workingDir));\n\n const oldPid = trace(\"pid\", await readPid(file));\n const alive = trace(\"wasAlive\", await isProcessAlive(oldPid));\n\n if (oldPid !== undefined && alive) {\n trace(\"stopped\", processStop(oldPid));\n try {\n trace(\"waitStopped\", await processWaitStopped(oldPid, 15_000)); // larger, that 10s we provide to backend in config.\n } catch {\n trace(\"forceStopped\", processStop(oldPid, true));\n trace(\"waitForceStopped\", await processWaitStopped(oldPid, 5_000));\n }\n }\n\n return t;\n });\n}\n\n/* Gets default options for the whole init process\n * and overrides them with the provided options. /\nexport function mergeDefaultOps(ops: LocalPlOptions, numCpu: number): LocalPlOptionsFull {\n const result: {\n plBinary: PlBinarySource;\n spawnOptions: SpawnOptions;\n closeOld: boolean;\n } = {\n plBinary: newDefaultPlBinarySource(),\n spawnOptions: {\n env: {\n GOMAXPROCS: String(numCpu),\n },\n },\n closeOld: true,\n };\n\n if (ops.spawnOptions?.env) {\n result.spawnOptions.env = { ...result.spawnOptions.env, ...ops.spawnOptions.env };\n }\n\n if (ops.spawnOptions) {\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.spawnOptions = { ...result.spawnOptions, ...withoutEnv };\n }\n\n const withoutSpawnOps = { ...ops };\n delete withoutSpawnOps[\"spawnOptions\"];\n\n return { ...result, ...withoutSpawnOps };\n}\n\n/* Gets default options for a platforma local binary\n * and overrides them with the provided options. */\nexport function plProcessOps(\n binaryPath: any,\n configPath: string,\n ops: LocalPlOptionsFull,\n workDir: string,\n defaultEnv: Record<string, string \| undefined>,\n): ProcessOptions {\n const result: ProcessOptions = {\n cmd: binaryPath,\n args: [\"--config\", configPath],\n opts: {\n env: { ...defaultEnv },\n cwd: workDir,\n stdio: [\"pipe\", \"ignore\", \"inherit\"],\n windowsHide: true, // hide a terminal on Windows\n },\n };\n\n if (ops.spawnOptions?.env) {\n result.opts.env = { ...result.opts.env, ...ops.spawnOptions.env };\n }\n\n const withoutEnv = { ...ops.spawnOptions };\n delete withoutEnv[\"env\"];\n result.opts = { ...result.opts, ...withoutEnv };\n\n return result;\n}\n"],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-deployments",
-  "version": "2.17.18",
+  "version": "3.0.0",
   "description": "MiLaboratories Platforma Backend code service run wrapper",
   "keywords": [],
   "license": "UNLICENSED",
@@ -32,10 +32,11 @@
     "upath": "^2.0.1",
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
+    "@milaboratories/pl-config": "1.8.1",
     "@milaboratories/pl-http": "1.2.4",
+    "@milaboratories/pl-healthcheck": "1.0.0",
     "@milaboratories/pl-model-common": "1.42.0",
-    "@milaboratories/ts-helpers": "1.8.2",
-    "@milaboratories/pl-config": "1.8.1"
+    "@milaboratories/ts-helpers": "1.8.2"
   },
   "devDependencies": {
     "@types/decompress": "^4.2.7",
@@ -46,7 +47,7 @@
     "typescript": "~5.9.3",
     "utility-types": "^3.11.0",
     "vitest": "^4.1.3",
-    "@milaboratories/ts-builder": "1.4.0",
+    "@milaboratories/ts-builder": "1.5.0",
     "@milaboratories/ts-configs": "1.2.3",
     "@milaboratories/build-configs": "2.0.0"
   },

package/src/local/pl.test.ts CHANGED Viewed

@@ -32,7 +32,7 @@ test(
     console.log(`Platforma: %o`, pl.debugInfo());
-    expect(await pl.isAlive()).toBeTruthy();
+    await pl.isAlive();
     expect(pl.pid).not.toBeUndefined();
     pl.stop();
@@ -57,14 +57,14 @@ test(
     await sleep(5000);
     console.log(`OldPlatforma: %o`, oldPl.debugInfo());
-    expect(await oldPl.isAlive()).toBeTruthy();
+    await oldPl.isAlive();
     const newPl = await localPlatformaInit(logger, options);
-    expect(await oldPl.isAlive()).toBeFalsy();
+    await expect(oldPl.isAlive({ timeoutMs: 1000 })).rejects.toThrow();
     await sleep(5000);
     console.log(`NewPlatforma: %o`, newPl.debugInfo());
-    expect(await newPl.isAlive()).toBeTruthy();
+    await newPl.isAlive();
     expect(newPl.pid).not.toBeUndefined();
     newPl.stop();
     await newPl.waitStopped();
@@ -87,17 +87,17 @@ test(
     });
     await sleep(1000);
-    expect(await pl.isAlive()).toBeTruthy();
+    await pl.isAlive();
     processStop(pl.pid!);
     await sleep(3000);
     console.log(`Platforma after first stop: %o`, pl.debugInfo());
-    expect(await pl.isAlive()).toBeTruthy();
+    await pl.isAlive();
     processStop(pl.pid!);
     await sleep(3000);
     console.log(`Platforma after second stop: %o`, pl.debugInfo());
-    expect(await pl.isAlive()).toBeTruthy();
+    await pl.isAlive();
     expect(pl.debugInfo().nRuns).toEqual(3);
     pl.stop();

package/src/local/pl.ts CHANGED Viewed

@@ -12,9 +12,11 @@ import upath from "upath";
 import fsp from "node:fs/promises";
 import type { Required } from "utility-types";
 import * as os from "node:os";
+import { sleep } from "@milaboratories/ts-helpers";
 import type { ProxySettings } from "@milaboratories/pl-http";
 import { defaultHttpDispatcher } from "@milaboratories/pl-http";
 import { parseHttpAuth } from "@milaboratories/pl-model-common";
+import { plHealthCheck, ServingStatus } from "@milaboratories/pl-healthcheck";
 export const LocalConfigYaml = "config-local.yaml";
@@ -35,6 +37,7 @@ export class LocalPl {
     private readonly workingDir: string,
     private readonly startOptions: ProcessOptions,
     private readonly initialStartHistory: Trace,
+    private readonly grpcPort?: number,
     private readonly onClose?: (pl: LocalPl) => Promise<void>,
     private readonly onError?: (pl: LocalPl) => Promise<void>,
     private readonly onCloseAndError?: (pl: LocalPl) => Promise<void>,
@@ -93,8 +96,86 @@ export class LocalPl {
     return this.wasStopped;
   }
-  async isAlive(): Promise<boolean> {
-    return await isProcessAlive(notEmpty(this.pid));
+  /**
+   * Polls the OS until the backend process is observed alive.
+   * Throws on timeout. Does NOT touch gRPC — use {@link isReady} for that.
+   */
+  async isAlive(opts?: { timeoutMs?: number; pollIntervalMs?: number }): Promise<void> {
+    const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);
+    const pollMs = opts?.pollIntervalMs ?? 500;
+    while (true) {
+      if (Date.now() >= deadline) {
+        throw new Error("Timeout waiting for backend process to be alive");
+      }
+      await sleep(pollMs);
+      if (!this.pid) continue;
+      if (await isProcessAlive(this.pid)) return;
+    }
+  }
+  /**
+   * Polls `grpc.health.v1.Health/Check` until the backend reports SERVING.
+   * Throws on timeout, on missing `grpcPort`, or if the process dies mid-wait.
+   *
+   * Calling this method is an explicit statement that the caller wants a real
+   * readiness signal; if `grpcPort` is undefined we throw rather than silently
+   * degrade to a process-only check (use {@link isAlive} for that).
+   */
+  async isReady(opts?: {
+    grpcPort?: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+  }): Promise<void> {
+    const grpcPort = opts?.grpcPort ?? this.grpcPort;
+    if (grpcPort === undefined) {
+      throw new Error(
+        "isReady requires grpcPort to be configured — caller asked for a real readiness check but no gRPC port is available",
+      );
+    }
+    const deadline = Date.now() + (opts?.timeoutMs ?? 120_000);
+    const pollMs = opts?.pollIntervalMs ?? 500;
+    const requestTimeoutMs = Math.max(500, Math.min(pollMs, 2_000));
+    let processAlive = false;
+    let wasAlive = false;
+    let isFirstCheck = true;
+    while (true) {
+      if (Date.now() >= deadline) {
+        if (!processAlive) {
+          throw new Error("Timeout waiting for backend process to be alive");
+        }
+        throw new Error("Timeout waiting for backend to be ready");
+      }
+      if (!isFirstCheck) await sleep(pollMs);
+      isFirstCheck = false;
+      if (!this.pid) continue;
+      processAlive = await isProcessAlive(this.pid);
+      wasAlive = wasAlive || processAlive;
+      if (!processAlive) {
+        if (wasAlive) {
+          // saw the process alive at least once, now it's gone — definitive failure
+          throw new Error("Backend process died while waiting for readiness");
+        }
+        continue;
+      }
+      try {
+        const status = await plHealthCheck({
+          address: `127.0.0.1:${grpcPort}`,
+          defaultRequestTimeout: requestTimeoutMs,
+        });
+        if (status === ServingStatus.SERVING) return;
+      } catch {
+        // not yet serving
+      }
+    }
   }
   debugInfo() {
@@ -132,6 +213,14 @@ export type LocalPlOptions = {
    */
   readonly proxy?: ProxySettings;
+  /**
+   * gRPC port the backend listens on (always on 127.0.0.1 for local).
+   * Required by {@link LocalPl.isReady}, which polls
+   * `grpc.health.v1.Health/Check` against this port to distinguish a process
+   * that is alive but still initializing from one actually serving gRPC.
+   */
+  readonly grpcPort?: number;
   readonly onClose?: (pl: LocalPl) => Promise<void>;
   readonly onError?: (pl: LocalPl) => Promise<void>;
   readonly onCloseAndError?: (pl: LocalPl) => Promise<void>;
@@ -204,6 +293,7 @@ Only Basic auth is supported by the backend.`);
       ops.workingDir,
       processOpts,
       t,
+      ops.grpcPort,
       ops.onClose,
       ops.onError,
       ops.onCloseAndError,