@milaboratories/pl-deployments 1.1.0

package/dist/ssh/ssh.d.ts

@@ -0,0 +1,128 @@
+import { ConnectConfig, SFTPWrapper, Client } from 'ssh2';
+import { default as net } from 'net';
+import { MiLogger } from '@milaboratories/ts-helpers';
+export type SshAuthMethods = 'publickey' | 'password';
+export type SshAuthMethodsResult = SshAuthMethods[];
+export declare class SshClient {
+    private readonly logger;
+    private readonly client;
+    private config?;
+    homeDir?: string;
+    constructor(logger: MiLogger, client: Client);
+    /**
+     * Initializes the SshClient and establishes a connection using the provided configuration.
+     * @param config - The connection configuration object for the SSH client.
+     * @returns A new instance of SshClient with an active connection.
+     */
+    static init(logger: MiLogger, config: ConnectConfig): Promise<SshClient>;
+    /**
+     * Connects to the SSH server using the specified configuration.
+     * @param config - The connection configuration object for the SSH client.
+     * @returns A promise that resolves when the connection is established or rejects on error.
+     */
+    connect(config: ConnectConfig): Promise<unknown>;
+    /**
+     * Executes a command on the SSH server.
+     * @param command - The command to execute on the remote server.
+     * @returns A promise resolving with the command's stdout and stderr outputs.
+     */
+    exec(command: string): Promise<SshExecResult>;
+    /**
+     * Retrieves the supported authentication methods for a given host and port.
+     * @param host - The hostname or IP address of the server.
+     * @param port - The port number to connect to on the server.
+     * @returns 'publickey' | 'password'[] A promise resolving with a list of supported authentication methods.
+     */
+    static getAuthTypes(host: string, port: number): Promise<SshAuthMethodsResult>;
+    /**
+     * Extracts authentication methods from debug logs.
+     * @param log - The debug log output containing authentication information.
+     * @returns An array of extracted authentication methods.
+     */
+    private static extractAuthMethods;
+    /**
+     * Sets up port forwarding between a remote port on the SSH server and a local port.
+     * A new connection is used for this operation instead of an existing one.
+     * @param ports - An object specifying the remote and local port configuration.
+     * @param config - Optional connection configuration for the SSH client.
+     * @returns { server: net.Server } A promise resolving with the created server instance.
+     */
+    forwardPort(ports: {
+        remotePort: number;
+        localPort: number;
+        localHost?: string;
+    }, config?: ConnectConfig): Promise<{
+        server: net.Server;
+    }>;
+    /**
+    * Checks if a specified host is available by performing a DNS lookup.
+    * @param hostname - The hostname or IP address to check.
+    * @returns A promise resolving with `true` if the host is reachable, otherwise `false`.
+    */
+    static checkHostAvailability(hostname: string): Promise<boolean>;
+    /**
+     * Determines whether a private key requires a passphrase for use.
+     * @param privateKey - The private key content to check.
+     * @returns A promise resolving with `true` if a passphrase is required, otherwise `false`.
+     */
+    static isPassphraseRequiredForKey(privateKey: string): Promise<boolean>;
+    /**
+     * Uploads a local file to a remote server via SFTP.
+     * This function creates new SFTP connection
+     * @param localPath - The local file path.
+     * @param remotePath - The remote file path on the server.
+     * @returns A promise resolving with `true` if the file was successfully uploaded.
+     */
+    uploadFile(localPath: string, remotePath: string): Promise<boolean>;
+    delay(delay: number): Promise<void>;
+    withSftp<R>(callback: (sftp: SFTPWrapper) => Promise<R>): Promise<R>;
+    writeFileOnTheServer(remotePath: string, data: string | Buffer, mode?: number): Promise<boolean>;
+    readFile(remotePath: string): Promise<string>;
+    chmod(path: string, mode: number): Promise<unknown>;
+    checkFileExists(remotePath: string): Promise<unknown>;
+    checkPathExists(remotePath: string): Promise<{
+        exists: boolean;
+        isFile: boolean;
+        isDirectory: boolean;
+    }>;
+    private writeFile;
+    uploadFileUsingExistingSftp(sftp: SFTPWrapper, localPath: string, remotePath: string, mode?: number): Promise<unknown>;
+    private __uploadDirectory;
+    /**
+     * Uploads a local directory and its contents (including subdirectories) to the remote server via SFTP.
+     * @param localDir - The path to the local directory to upload.
+     * @param remoteDir - The path to the remote directory on the server.
+     * @returns A promise that resolves when the directory and its contents are uploaded.
+     */
+    uploadDirectory(localDir: string, remoteDir: string, mode?: number): Promise<void>;
+    /**
+     * Ensures that a remote directory and all its parent directories exist.
+     * @param sftp - The SFTP wrapper.
+     * @param remotePath - The path to the remote directory.
+     * @returns A promise that resolves when the directory is created.
+     */
+    private __createRemoteDirectory;
+    /**
+     * Ensures that a remote directory and all its parent directories exist.
+     * @param sftp - The SFTP wrapper.
+     * @param remotePath - The path to the remote directory.
+     * @returns A promise that resolves when the directory is created.
+     */
+    createRemoteDirectory(remotePath: string, mode?: number): Promise<void>;
+    /**
+     * Downloads a file from the remote server to a local path via SFTP.
+     * @param remotePath - The remote file path on the server.
+     * @param localPath - The local file path to save the file.
+     * @returns A promise resolving with `true` if the file was successfully downloaded.
+     */
+    downloadFile(remotePath: string, localPath: string): Promise<boolean>;
+    /**
+     * Closes the SSH client connection.
+     */
+    close(): void;
+}
+export type SshExecResult = {
+    stdout: string;
+    stderr: string;
+};
+//# sourceMappingURL=ssh.d.ts.map

package/dist/ssh/ssh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../src/ssh/ssh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiB,WAAW,EAAE,MAAM,MAAM,CAAC;AACtE,OAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,GAAG,MAAM,KAAK,CAAC;AAKtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAG3D,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC;AACtD,MAAM,MAAM,oBAAoB,GAAG,cAAc,EAAE,CAAC;AAEpD,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,MAAM,CAAC,CAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;gBAGL,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM;IAGjC;;;;OAIG;WACiB,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAOrF;;;;OAIG;IACU,OAAO,CAAC,MAAM,EAAE,aAAa;IAc1C;;;;OAIG;IACU,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA0B1D;;;;;OAKG;WACiB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA2B3F;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAKjC;;;;;;OAMG;IACU,WAAW,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;KAAE,CAAC;IA2DvJ;;;;MAIE;WACkB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ7E;;;;OAIG;WACiB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAepF;;;;;;OAMG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAehF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBpE,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,GAAE,MAAc;IAMpF,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAapD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAahC,eAAe,CAAC,UAAU,EAAE,MAAM;IAgBlC,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;YAoBhG,SAAS;IAWhB,2BAA2B,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc;YAgBnG,iBAAiB;IA8B/B;;;;;OAKG;IACU,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAStG;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;OAKG;IACI,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BrF;;;;;OAKG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAalF;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/ssh/supervisord.d.ts

@@ -0,0 +1,8 @@
+import { MiLogger } from '@milaboratories/ts-helpers';
+import { SshClient, SshExecResult } from './ssh';
+export declare function supervisorCtlStart(sshClient: SshClient, remoteHome: string, arch: string): Promise<void>;
+export declare function supervisorStop(sshClient: SshClient, remoteHome: string, arch: string): Promise<void>;
+export declare function supervisorStatus(logger: MiLogger, sshClient: SshClient, remoteHome: string, arch: string): Promise<boolean>;
+export declare function generateSupervisordConfig(minioStorageDir: string, minioEnvs: Record<string, string>, supervisorRemotePort: number, remoteWorkDir: string, platformaConfigPath: string, minioPath: string, plPath: string): string;
+export declare function supervisorExec(sshClient: SshClient, remoteHome: string, arch: string, command: string): Promise< SshExecResult>;
+//# sourceMappingURL=supervisord.d.ts.map

package/dist/ssh/supervisord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisord.d.ts","sourceRoot":"","sources":["../../src/ssh/supervisord.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,iBAOjC;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,iBAOjC;AAOD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAC/B,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAED,wBAAgB,yBAAyB,CACvC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,oBAAoB,EAAE,MAAM,EAC5B,aAAa,EAAE,MAAM,EACrB,mBAAmB,EAAE,MAAM,EAE3B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,UAoCf;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM,0CAOhB"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@milaboratories/pl-deployments",
+  "version": "1.1.0",
+  "pl-version": "1.18.3",
+  "description": "MiLaboratories Platforma Backend code service run wrapper",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "./dist/**/*",
+    "./src/**/*",
+    "README.md",
+    "bin/run.cmd",
+    "bin/run.js",
+    "assets",
+    "postinstall.js"
+  ],
+  "keywords": [],
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/decompress": "^4.2.7",
+    "@types/jest": "^29.5.14",
+    "@types/node": "~20.16.15",
+    "@types/ssh2": "^1.15.1",
+    "eslint": "^9.16.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.1",
+    "testcontainers": "^10.16.0",
+    "ts-jest": "^29.2.5",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "~5.5.4",
+    "utility-types": "^3.11.0",
+    "vite": "^5.4.11",
+    "vitest": "^2.1.8",
+    "@milaboratories/platforma-build-configs": "1.0.2",
+    "@milaboratories/eslint-config": "^1.0.1"
+  },
+  "dependencies": {
+    "decompress": "^4.2.1",
+    "upath": "^2.0.1",
+    "ssh2": "^1.16.0",
+    "tar": "^7.4.3",
+    "undici": "^7.2.3",
+    "yaml": "^2.6.1",
+    "zod": "~3.23.8",
+    "@milaboratories/pl-config": "^1.4.0",
+    "@milaboratories/ts-helpers": "^1.1.3"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit --composite false",
+    "build": "vite build",
+    "test": "vitest",
+    "do-pack": "rm -rf src/.test && rm -f *.tgz && pnpm pack && mv *.tgz package.tgz",
+    "cleanup-docker": "docker container stop pl-ssh-test-pl pl-ssh-test-ssh && docker container rm pl-ssh-test-pl pl-ssh-test-ssh && docker image rm pl-ssh-test-container-ssh:1.0.0 pl-ssh-test-container-pl:1.0.0",
+    "exec-docker": "docker exec -ti pl-ssh-test-pl bash"
+  }
+}

package/src/common/os_and_arch.ts

@@ -0,0 +1,44 @@
+import os from 'os';
+
+export const OSes = ['linux', 'macos', 'windows'] as const;
+export type OSType = (typeof OSes)[number];
+
+/** @param osName - should be the thing returned from either {@link os.platform())} or `uname -s` */
+export function newOs(osName: string): OSType {
+  switch (osName.toLowerCase()) {
+    case 'darwin':
+      return 'macos';
+    case 'linux':
+      return 'linux';
+    case 'win32':
+      return 'windows';
+    default:
+      throw new Error(
+        `operating system '${osName}' is not currently supported by Platforma ecosystem. The list of OSes supported: `
+        + JSON.stringify(OSes),
+      );
+  }
+}
+
+export const Arches = ['amd64', 'arm64'] as const;
+export type ArchType = (typeof Arches)[number];
+
+/** @param arch - should be the thing returned from either {@link os.arch())} or `uname -m` */
+export function newArch(arch: string): ArchType {
+  switch (arch) {
+    case 'aarch64':
+    case 'aarch64_be':
+    case 'arm64':
+      return 'arm64';
+
+    case 'x86_64':
+    case 'x64':
+      return 'amd64';
+
+    default:
+      throw new Error(
+        `processor architecture '${arch}' is not currently supported by Platforma ecosystem. The list of architectures supported: `
+        + JSON.stringify(Arches),
+      );
+  }
+}

package/src/common/pl_binary.ts

@@ -0,0 +1,39 @@
+import type { MiLogger } from '@milaboratories/ts-helpers';
+import { assertNever } from '@milaboratories/ts-helpers';
+import { downloadPlBinary, DownloadBinaryResult } from './pl_binary_download';
+import { getDefaultPlVersion } from './pl_version';
+import os from 'os';
+
+/** Shows how the binary should be got. */
+export type PlBinarySource = PlBinarySourceDownload | PlBinarySourceLocal;
+
+export type PlBinarySourceDownload = {
+  readonly type: 'Download';
+  readonly version: string;
+};
+
+export type PlBinarySourceLocal = {
+  readonly type: 'Local';
+  readonly path: string;
+};
+
+export function newDefaultPlBinarySource(): PlBinarySourceDownload {
+  return { type: 'Download', version: getDefaultPlVersion() };
+}
+
+export async function resolveLocalPlBinaryPath(
+  logger: MiLogger,
+  downloadDir: string,
+  src: PlBinarySource,
+): Promise<string> {
+  switch (src.type) {
+    case 'Download':
+      return (await downloadPlBinary(logger, downloadDir, src.version, os.arch(), os.platform())).binaryPath!;
+
+    case 'Local':
+      return src.path;
+
+    default:
+      assertNever(src);
+  }
+}

package/src/common/pl_binary_download.ts

@@ -0,0 +1,258 @@
+import fs from 'fs';
+import fsp from 'fs/promises';
+import upath from 'upath';
+import { request } from 'undici';
+import { Writable, Readable } from 'stream';
+import { text } from 'stream/consumers';
+import * as tar from 'tar';
+import type { MiLogger } from '@milaboratories/ts-helpers';
+import { assertNever, fileExists } from '@milaboratories/ts-helpers';
+import decompress from 'decompress';
+import type { ArchType, OSType } from './os_and_arch';
+import { newOs, newArch } from './os_and_arch';
+
+export type DownloadBinaryResult = {
+  archiveUrl: string;
+  archivePath: string;
+  archiveType: ArchiveType;
+  targetFolder: string;
+  baseName: string;
+  binaryPath?: string;
+};
+
+export async function downloadBinaryNoExtract(
+  logger: MiLogger,
+  baseDir: string,
+  softwareName: string,
+  tgzName: string,
+  arch: string,
+  platform: string,
+): Promise<DownloadBinaryResult> {
+  const opts = getPathsForDownload(softwareName, tgzName, baseDir, newArch(arch), newOs(platform));
+  const { archiveUrl, archivePath } = opts;
+
+  await downloadArchive(logger, archiveUrl, archivePath);
+
+  return opts;
+}
+
+export async function downloadBinary(
+  logger: MiLogger,
+  baseDir: string,
+  softwareName: string,
+  archiveName: string,
+  arch: string,
+  platform: string,
+): Promise<DownloadBinaryResult> {
+  const opts = getPathsForDownload(softwareName, archiveName, baseDir, newArch(arch), newOs(platform));
+  const { archiveUrl, archivePath, archiveType, targetFolder, baseName } = opts;
+
+  await downloadArchive(logger, archiveUrl, archivePath);
+  await extractArchive(logger, archivePath, archiveType, targetFolder);
+
+  return opts;
+}
+
+export async function downloadPlBinary(
+  logger: MiLogger,
+  baseDir: string,
+  plVersion: string,
+  arch: string,
+  platform: string,
+): Promise<DownloadBinaryResult> {
+  const opts = localDownloadPlOptions(plVersion, baseDir, newArch(arch), newOs(platform));
+  const { archiveUrl, archivePath, archiveType, targetFolder, binaryPath } = opts;
+
+  await downloadArchive(logger, archiveUrl, archivePath);
+  await extractArchive(logger, archivePath, archiveType, targetFolder);
+
+  return opts;
+}
+
+function getPathsForDownload(
+  softwareName: string,
+  archiveName: string,
+  baseDir: string,
+  arch: ArchType,
+  os: OSType,
+): DownloadBinaryResult {
+  const baseName = `${archiveName}-${arch}`;
+  const archiveType = osToArchiveType[os];
+
+  const archiveFileName = `${baseName}.${archiveType}`;
+  const archiveUrl = `https://cdn.platforma.bio/software/${softwareName}/${os}/${archiveFileName}`;
+  const archivePath = upath.join(baseDir, archiveFileName);
+  // folder where binary distribution of pl will be unpacked
+  const targetFolder = upath.join(baseDir, baseName);
+
+  return {
+    archiveUrl,
+    archivePath,
+    archiveType,
+    targetFolder,
+    baseName,
+  };
+}
+
+export function localDownloadPlOptions(
+  plVersion: string,
+  baseDir: string,
+  arch: ArchType,
+  os: OSType,
+): DownloadBinaryResult {
+  const baseName = `pl-${plVersion}-${arch}`;
+  const archiveType = osToArchiveType[os];
+
+  const archiveFileName = `${baseName}.${archiveType}`;
+  const archiveUrl = `https://cdn.platforma.bio/software/pl/${os}/${archiveFileName}`;
+  const archivePath = upath.join(baseDir, archiveFileName);
+
+  // folder where binary distribution of pl will be unpacked
+  const targetFolder = upath.join(baseDir, baseName);
+
+  const binaryPath = upath.join(baseName, 'binaries', osToBinaryName[os]);
+
+  return {
+    archiveUrl,
+    archivePath,
+    archiveType,
+    targetFolder,
+    binaryPath,
+    baseName,
+  };
+}
+
+export type DownloadInfo = {
+  dstArchive?: string;
+  fileExisted?: boolean;
+  dirnameCreated?: boolean;
+  statusCode?: number;
+  errorMsg?: string;
+  tmpPath?: string;
+  wroteTmp?: boolean;
+  tmpExisted?: boolean;
+  renamed?: boolean;
+  newExisted?: boolean;
+};
+
+export async function downloadArchive(
+  logger: MiLogger, archiveUrl: string, dstArchiveFile: string,
+): Promise<DownloadInfo> {
+  const state: DownloadInfo = {};
+  state.dstArchive = dstArchiveFile;
+
+  try {
+    state.fileExisted = await fileExists(dstArchiveFile);
+    if (state.fileExisted) {
+      logger.info(`Platforma Backend archive download skipped: '${dstArchiveFile}' already exists`);
+      return state;
+    }
+
+    await fsp.mkdir(upath.dirname(dstArchiveFile), { recursive: true });
+    state.dirnameCreated = true;
+
+    logger.info(`Downloading archive:\n  URL: ${archiveUrl}\n Save to: ${dstArchiveFile}`);
+
+    const { body, statusCode } = await request(archiveUrl);
+    state.statusCode = statusCode;
+    if (statusCode != 200) {
+      // completely draining the stream to prevent leaving open connections
+      const textBody = await text(body);
+      state.errorMsg = `failed to download archive: ${statusCode}, response: ${textBody.slice(0, 1000)}`;
+      logger.error(state.errorMsg);
+      throw new Error(state.errorMsg);
+    }
+
+    // to prevent incomplete downloads we first write in a temp file
+    state.tmpPath = dstArchiveFile + '.tmp';
+    await Readable.toWeb(body).pipeTo(Writable.toWeb(fs.createWriteStream(state.tmpPath)));
+    state.wroteTmp = true;
+    state.tmpExisted = await fileExists(state.tmpPath);
+
+    // and then atomically rename it
+    await fsp.rename(state.tmpPath, dstArchiveFile);
+    state.renamed = true;
+    state.newExisted = await fileExists(dstArchiveFile);
+
+    return state;
+  } catch (e: unknown) {
+    const msg = `downloadArchive: error ${JSON.stringify(e)} occurred, state: ${JSON.stringify(state)}`;
+    logger.error(msg);
+    throw new Error(msg);
+  }
+}
+
+/** Used to prevent mid-way interrupted unarchived folders to be used */
+const MarkerFileName = '.ok';
+
+export async function extractArchive(
+  logger: MiLogger,
+  archivePath: string,
+  archiveType: ArchiveType,
+  dstFolder: string,
+) {
+  logger.info('extracting archive...');
+  logger.info(`  archive path: '${archivePath}'`);
+  logger.info(`  target dir: '${dstFolder}'`);
+
+  if (!(await fileExists(archivePath))) {
+    const msg = `Platforma Backend binary archive not found at '${archivePath}'`;
+    logger.error(msg);
+    throw new Error(msg);
+  }
+
+  const markerFilePath = upath.join(dstFolder, MarkerFileName);
+
+  if (await fileExists(markerFilePath)) {
+    logger.info(`Platforma Backend binaries unpack skipped: '${dstFolder}' exists`);
+    return;
+  }
+
+  if (await fileExists(dstFolder)) {
+    logger.info(`Removing previous incompletely unpacked folder: '${dstFolder}'`);
+    await fsp.rm(dstFolder, { recursive: true });
+  }
+
+  logger.info(`  creating target dir '${dstFolder}'`);
+  await fsp.mkdir(dstFolder, { recursive: true });
+
+  logger.info(
+    `Unpacking Platforma Backend archive:\n  Archive:   ${archivePath}\n  Target dir: ${dstFolder}`,
+  );
+
+  switch (archiveType) {
+    case 'tgz':
+      await tar.x({
+        file: archivePath,
+        cwd: dstFolder,
+        gzip: true,
+      });
+      break;
+
+    case 'zip':
+      await decompress(archivePath, dstFolder);
+      break;
+
+    default:
+      assertNever(archiveType);
+  }
+
+  // writing marker file, to be able in the future detect that we completely unarchived the tar file
+  await fsp.writeFile(markerFilePath, 'ok');
+
+  logger.info(`  ... unpack done.`);
+}
+
+export type ArchiveType = 'tgz' | 'zip';
+
+const osToArchiveType: Record<OSType, ArchiveType> = {
+  linux: 'tgz',
+  macos: 'tgz',
+  windows: 'zip',
+};
+
+const osToBinaryName: Record<OSType, string> = {
+  linux: 'platforma',
+  macos: 'platforma',
+  windows: 'platforma.exe',
+};

package/src/common/pl_version.ts

@@ -0,0 +1,5 @@
+declare const PL_VERSION: string;
+
+export function getDefaultPlVersion(): string {
+  return PL_VERSION;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './local/pl';
+export * from './common/pl_version';
+export * from './ssh/ssh';
+export * from './ssh/pl';

package/src/local/config.test.yaml

@@ -0,0 +1,60 @@
+license:
+  value: ''
+  file: ''
+
+logging:
+  level: 'info'
+  destinations:
+    - path: 'platforma.log'
+
+monitoring:
+  listen: '127.0.0.1:11235'
+
+debug:
+  listen: '127.0.0.1:11236'
+
+core:
+  logging:
+    extendedInfo: true
+    dumpResourceData: true
+
+  grpc:
+    listen: '127.0.0.1:11234'
+    tlsEnabled: false
+
+  authEnabled: false
+  auth: []
+  db:
+    path: './db'
+
+controllers:
+  data:
+    main:
+      storages:
+        main:
+          mode: primary
+          downloadable: true
+
+        work:
+          mode: active
+          downloadable: false
+
+    storages:
+      - id: 'main'
+        type: 'FS'
+        indexCachePeriod: '1m'
+        rootPath: './storages/main'
+
+      - id: 'work'
+        type: 'FS'
+        indexCachePeriod: '1m'
+        rootPath: './storages/work'
+
+  runner:
+    type: local
+    storageRoot: './storages/work'
+
+  packageLoader:
+    packagesRoot: './packages'
+
+  workflows: {}

package/src/local/options.ts

@@ -0,0 +1,34 @@
+import type { SpawnOptions } from 'child_process';
+import type { PlBinarySource } from '../common/pl_binary';
+
+/** Options to start a local pl-core. */
+export type LocalPlOptions = {
+  /** From what directory start a process. */
+  readonly workingDir: string;
+  /** A string representation of yaml config. */
+  readonly config: string;
+  /** How to get a binary, download it or get an existing one. */
+  readonly binary: PlBinarySource;
+  /** Additional options for a process, environments, stdout, stderr etc. */
+  readonly spawnOptions: SpawnOptions;
+  /**
+   * If the previous pl-core was started from the same directory,
+   * we can check if it's still running and then stop it before starting a new one.
+   */
+  readonly closeOld: boolean;
+  /** What should we do on closing or if the process exit with error */
+  readonly restartMode: LocalPlRestart;
+};
+
+export type LocalPlRestart = LocalPlRestartSilent | LocalPlRestartHook;
+
+/** Do nothing if the error happened or a process exited. */
+export type LocalPlRestartSilent = {
+  type: 'silent';
+};
+
+/** Run a hook if the error happened or a process exited. */
+export type LocalPlRestartHook = {
+  type: 'hook';
+  hook(pl: any): void;
+};

package/src/local/pid.ts

@@ -0,0 +1,21 @@
+import { fileExists } from '@milaboratories/ts-helpers';
+import fs from 'fs/promises';
+import upath from 'upath';
+
+export function filePid(dir: string) {
+  return upath.join(dir, 'pl_pid');
+}
+
+export async function readPid(filePath: string): Promise<number | undefined> {
+  if (!(await fileExists(filePath))) {
+    return undefined;
+  }
+
+  const text = await fs.readFile(filePath);
+
+  return Number(text.toString());
+}
+
+export async function writePid(filePath: string, pid: number) {
+  await fs.writeFile(filePath, JSON.stringify(pid));
+}