@milaboratories/pl-deployments 2.18.0 → 3.0.0

package/dist/local/pl.cjs

@@ -10,10 +10,9 @@ let upath = require("upath");
 upath = require_runtime.__toESM(upath);
 let node_os = require("node:os");
 node_os = require_runtime.__toESM(node_os);
-let node_net = require("node:net");
-node_net = require_runtime.__toESM(node_net);
 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";
 /**
@@ -74,10 +73,58 @@ var LocalPl = class {
 	stopped() {
 		return this.wasStopped;
 	}
-	async isAlive() {
-		if (!await require_process.isProcessAlive((0, _milaboratories_ts_helpers.notEmpty)(this.pid))) return false;
-		if (this.grpcPort === void 0) return true;
-		return await tcpProbe("127.0.0.1", this.grpcPort);
+	/**
+	* 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 {
@@ -182,30 +229,6 @@ function mergeDefaultOps(ops, numCpu) {
 		...withoutSpawnOps
 	};
 }
-/** Resolves true if a TCP connect to host:port succeeds within timeoutMs. Used by
-* {@link LocalPl.isAlive} to verify the gRPC listener has actually bound — the backend
-* process can be alive long before its server sockets are accepting connections. */
-async function tcpProbe(host, port, timeoutMs = 500) {
-	return await new Promise((resolve) => {
-		const socket = node_net.default.connect({
-			host,
-			port
-		});
-		const finalize = (ok) => {
-			socket.destroy();
-			resolve(ok);
-		};
-		const timer = setTimeout(() => finalize(false), timeoutMs);
-		socket.once("connect", () => {
-			clearTimeout(timer);
-			finalize(true);
-		});
-		socket.once("error", () => {
-			clearTimeout(timer);
-			finalize(false);
-		});
-	});
-}
 /** Gets default options for a platforma local binary
 * and overrides them with the provided options. */
 function plProcessOps(binaryPath, configPath, ops, workDir, defaultEnv) {

package/dist/local/pl.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"pl.cjs","names":["withTrace","processRun","filePid","writePid","processWaitStopped","isProcessAlive","os","fsp","resolveLocalPlBinaryPath","readPid","processStop","newDefaultPlBinarySource","net"],"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 net from \"node:net\";\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 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  async isAlive(): Promise<boolean> {\n    if (!(await isProcessAlive(notEmpty(this.pid)))) return false;\n    if (this.grpcPort === undefined) return true;\n    return await tcpProbe(\"127.0.0.1\", this.grpcPort);\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   * When set, {@link LocalPl.isAlive} additionally probes this TCP port so callers\n   * can distinguish a process that is alive but still binding from a process that is\n   * actually accepting gRPC connections.\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/** Resolves true if a TCP connect to host:port succeeds within timeoutMs. Used by\n * {@link LocalPl.isAlive} to verify the gRPC listener has actually bound — the backend\n * process can be alive long before its server sockets are accepting connections. */\nasync function tcpProbe(host: string, port: number, timeoutMs = 500): Promise<boolean> {\n  return await new Promise<boolean>((resolve) => {\n    const socket = net.connect({ host, port });\n    const finalize = (ok: boolean) => {\n      socket.destroy();\n      resolve(ok);\n    };\n    const timer = setTimeout(() => finalize(false), timeoutMs);\n    socket.once(\"connect\", () => {\n      clearTimeout(timer);\n      finalize(true);\n    });\n    socket.once(\"error\", () => {\n      clearTimeout(timer);\n      finalize(false);\n    });\n  });\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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"}
+{"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

@@ -33,7 +33,27 @@ declare class LocalPl {
   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;
@@ -63,9 +83,9 @@ type LocalPlOptions = {
   readonly proxy?: ProxySettings;
   /**
    * gRPC port the backend listens on (always on 127.0.0.1 for local).
-   * When set, {@link LocalPl.isAlive} additionally probes this TCP port so callers
-   * can distinguish a process that is alive but still binding from a process that is
-   * actually accepting gRPC connections.
+   * 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>;

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

@@ -1 +1 @@
-{"version":3,"file":"pl.d.ts","names":[],"sources":["../../src/local/pl.ts"],"mappings":";;;;;;;;;cAmBa,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;EAIM,OAAA,CAAA,GAAW,OAAA;EAMjB,SAAA,CAAA;;;;;;;;;;KAaU,cAAA;EAxFH,oDA0FE,UAAA,UAxFD;EAAA,SA0FC,MAAA;WAEA,QAAA,GAAW,cAAA,EAxFD;EAAA,SA0FV,YAAA,GAAe,YAAA;EAxFS;;;;;EAAA,SA8FxB,QAAA;EA3FqB;;;;;EAAA,SAiGrB,KAAA,GAAQ,aAAA;EAhGE;;;;;;EAAA,SAwGV,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;;;iBAqG1E,eAAA,CAAgB,GAAA,EAAK,cAAA,EAAgB,MAAA,WAAiB,kBAAA;;;iBAuDtD,YAAA,CACd,UAAA,OACA,UAAA,UACA,GAAA,EAAK,kBAAA,EACL,OAAA,UACA,UAAA,EAAY,MAAA,+BACX,cAAA"}
+{"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

@@ -2,13 +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 net from "node:net";
 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";
 /**
@@ -69,10 +69,58 @@ var LocalPl = class {
 	stopped() {
 		return this.wasStopped;
 	}
-	async isAlive() {
-		if (!await isProcessAlive(notEmpty(this.pid))) return false;
-		if (this.grpcPort === void 0) return true;
-		return await tcpProbe("127.0.0.1", this.grpcPort);
+	/**
+	* 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 {
@@ -177,30 +225,6 @@ function mergeDefaultOps(ops, numCpu) {
 		...withoutSpawnOps
 	};
 }
-/** Resolves true if a TCP connect to host:port succeeds within timeoutMs. Used by
-* {@link LocalPl.isAlive} to verify the gRPC listener has actually bound — the backend
-* process can be alive long before its server sockets are accepting connections. */
-async function tcpProbe(host, port, timeoutMs = 500) {
-	return await new Promise((resolve) => {
-		const socket = net.connect({
-			host,
-			port
-		});
-		const finalize = (ok) => {
-			socket.destroy();
-			resolve(ok);
-		};
-		const timer = setTimeout(() => finalize(false), timeoutMs);
-		socket.once("connect", () => {
-			clearTimeout(timer);
-			finalize(true);
-		});
-		socket.once("error", () => {
-			clearTimeout(timer);
-			finalize(false);
-		});
-	});
-}
 /** Gets default options for a platforma local binary
 * and overrides them with the provided options. */
 function plProcessOps(binaryPath, configPath, ops, workDir, defaultEnv) {

package/dist/local/pl.js.map

@@ -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 net from \"node:net\";\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 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  async isAlive(): Promise<boolean> {\n    if (!(await isProcessAlive(notEmpty(this.pid)))) return false;\n    if (this.grpcPort === undefined) return true;\n    return await tcpProbe(\"127.0.0.1\", this.grpcPort);\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   * When set, {@link LocalPl.isAlive} additionally probes this TCP port so callers\n   * can distinguish a process that is alive but still binding from a process that is\n   * actually accepting gRPC connections.\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/** Resolves true if a TCP connect to host:port succeeds within timeoutMs. Used by\n * {@link LocalPl.isAlive} to verify the gRPC listener has actually bound — the backend\n * process can be alive long before its server sockets are accepting connections. */\nasync function tcpProbe(host: string, port: number, timeoutMs = 500): Promise<boolean> {\n  return await new Promise<boolean>((resolve) => {\n    const socket = net.connect({ host, port });\n    const finalize = (ok: boolean) => {\n      socket.destroy();\n      resolve(ok);\n    };\n    const timer = setTimeout(() => finalize(false), timeoutMs);\n    socket.once(\"connect\", () => {\n      clearTimeout(timer);\n      finalize(true);\n    });\n    socket.once(\"error\", () => {\n      clearTimeout(timer);\n      finalize(false);\n    });\n  });\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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"}
+{"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/dist/ssh/pl.cjs

@@ -8,9 +8,9 @@ const require_connection_info = require("./connection_info.cjs");
 let _milaboratories_ts_helpers = require("@milaboratories/ts-helpers");
 let upath = require("upath");
 upath = require_runtime.__toESM(upath);
+let _milaboratories_pl_http = require("@milaboratories/pl-http");
 let node_net = require("node:net");
 node_net = require_runtime.__toESM(node_net);
-let _milaboratories_pl_http = require("@milaboratories/pl-http");
 let _milaboratories_pl_config = require("@milaboratories/pl-config");
 //#region src/ssh/pl.ts
 const minRequiredGlibcVersion = 2.28;

package/dist/ssh/pl.js

@@ -6,8 +6,8 @@ import { generateSupervisordConfig, generateSupervisordConfigWithMinio, isAllAli
 import { newConnectionInfo, parseConnectionInfo, stringifyConnectionInfo } from "./connection_info.js";
 import { notEmpty, sleep } from "@milaboratories/ts-helpers";
 import upath from "upath";
-import net from "node:net";
 import { defaultHttpDispatcher } from "@milaboratories/pl-http";
+import net from "node:net";
 import { generateSshPlConfigs, getFreePort } from "@milaboratories/pl-config";
 //#region src/ssh/pl.ts
 const minRequiredGlibcVersion = 2.28;

package/dist/ssh/ssh.cjs

@@ -6,10 +6,10 @@ node_fs = require_runtime.__toESM(node_fs);
 let node_fs_promises = require("node:fs/promises");
 let upath = require("upath");
 upath = require_runtime.__toESM(upath);
-let node_net = require("node:net");
-node_net = require_runtime.__toESM(node_net);
 let ssh2 = require("ssh2");
 ssh2 = require_runtime.__toESM(ssh2);
+let node_net = require("node:net");
+node_net = require_runtime.__toESM(node_net);
 let node_dns = require("node:dns");
 node_dns = require_runtime.__toESM(node_dns);
 let node_crypto = require("node:crypto");

package/dist/ssh/ssh.d.ts

@@ -1,6 +1,6 @@
 import { MiLogger } from "@milaboratories/ts-helpers";
-import net from "node:net";
 import ssh, { Client, ConnectConfig, SFTPWrapper } from "ssh2";
+import net from "node:net";
 
 //#region src/ssh/ssh.d.ts
 type SshAuthMethods = "publickey" | "password";

package/dist/ssh/ssh.js

@@ -3,8 +3,8 @@ import { Retry3TimesWithDelay, RetryablePromise, retry } from "@milaboratories/t
 import fs from "node:fs";
 import { readFile } from "node:fs/promises";
 import upath from "upath";
-import net from "node:net";
 import ssh, { Client } from "ssh2";
+import net from "node:net";
 import dns from "node:dns";
 import { randomBytes } from "node:crypto";
 //#region src/ssh/ssh.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-deployments",
-  "version": "2.18.0",
+  "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/ts-helpers": "1.8.2",
+    "@milaboratories/pl-healthcheck": "1.0.0",
     "@milaboratories/pl-model-common": "1.42.0",
-    "@milaboratories/pl-config": "1.8.1"
+    "@milaboratories/ts-helpers": "1.8.2"
   },
   "devDependencies": {
     "@types/decompress": "^4.2.7",
@@ -46,9 +47,9 @@
     "typescript": "~5.9.3",
     "utility-types": "^3.11.0",
     "vitest": "^4.1.3",
-    "@milaboratories/build-configs": "2.0.0",
+    "@milaboratories/ts-builder": "1.5.0",
     "@milaboratories/ts-configs": "1.2.3",
-    "@milaboratories/ts-builder": "1.5.0"
+    "@milaboratories/build-configs": "2.0.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/local/pl.test.ts

@@ -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

@@ -10,12 +10,13 @@ import type { Trace } from "./trace";
 import { withTrace } from "./trace";
 import upath from "upath";
 import fsp from "node:fs/promises";
-import net from "node:net";
 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";
 
@@ -95,10 +96,86 @@ export class LocalPl {
     return this.wasStopped;
   }
 
-  async isAlive(): Promise<boolean> {
-    if (!(await isProcessAlive(notEmpty(this.pid)))) return false;
-    if (this.grpcPort === undefined) return true;
-    return await tcpProbe("127.0.0.1", this.grpcPort);
+  /**
+   * 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() {
@@ -138,9 +215,9 @@ export type LocalPlOptions = {
 
   /**
    * gRPC port the backend listens on (always on 127.0.0.1 for local).
-   * When set, {@link LocalPl.isAlive} additionally probes this TCP port so callers
-   * can distinguish a process that is alive but still binding from a process that is
-   * actually accepting gRPC connections.
+   * 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;
 
@@ -287,28 +364,6 @@ export function mergeDefaultOps(ops: LocalPlOptions, numCpu: number): LocalPlOpt
   return { ...result, ...withoutSpawnOps };
 }
 
-/** Resolves true if a TCP connect to host:port succeeds within timeoutMs. Used by
- * {@link LocalPl.isAlive} to verify the gRPC listener has actually bound — the backend
- * process can be alive long before its server sockets are accepting connections. */
-async function tcpProbe(host: string, port: number, timeoutMs = 500): Promise<boolean> {
-  return await new Promise<boolean>((resolve) => {
-    const socket = net.connect({ host, port });
-    const finalize = (ok: boolean) => {
-      socket.destroy();
-      resolve(ok);
-    };
-    const timer = setTimeout(() => finalize(false), timeoutMs);
-    socket.once("connect", () => {
-      clearTimeout(timer);
-      finalize(true);
-    });
-    socket.once("error", () => {
-      clearTimeout(timer);
-      finalize(false);
-    });
-  });
-}
-
 /** Gets default options for a platforma local binary
  * and overrides them with the provided options. */
 export function plProcessOps(