@milaboratories/pl-deployments 1.1.10 → 1.1.12

package/src/ssh/connection_info.ts

@@ -0,0 +1,62 @@
+/** We store all info about the connection on the server,
+ * so that another client could read the file and connect from another machine. */
+import { z } from 'zod';
+
+//
+// Types
+//
+
+export const PortPair = z.object({
+  local: z.number(),
+  remote: z.number(),
+});
+/** The pair of ports for forwarding. */
+export type PortPair = z.infer<typeof PortPair>;
+
+export const SshPlPorts = z.object({
+  grpc: PortPair,
+  monitoring: PortPair,
+  debug: PortPair,
+  minioPort: PortPair,
+  minioConsolePort: PortPair,
+});
+/** All info about ports that are forwarded. */
+export type SshPlPorts = z.infer<typeof SshPlPorts>;
+
+export const ConnectionInfo = z.object({
+  plUser: z.string(),
+  plPassword: z.string(),
+  ports: SshPlPorts,
+
+  // It's false by default because it was added later,
+  // and in some deployments there won't be useGlobalAccess flag in the file.
+  useGlobalAccess: z.boolean().default(false),
+});
+/** The content of the file that holds all the info about the connection on the remote server. */
+export type ConnectionInfo = z.infer<typeof ConnectionInfo>;
+
+//
+// Funcs
+//
+
+export function newConnectionInfo(
+  plUser: string,
+  plPassword: string,
+  ports: SshPlPorts,
+  useGlobalAccess: boolean,
+): ConnectionInfo {
+  return {
+    plUser,
+    plPassword,
+    ports,
+    useGlobalAccess,
+  };
+}
+
+export function parseConnectionInfo(content: string): ConnectionInfo {
+  return ConnectionInfo.parse(JSON.parse(content));
+}
+
+export function stringifyConnectionInfo(conn: ConnectionInfo): string {
+  return JSON.stringify(conn, undefined, 2);
+}

package/src/ssh/pl.ts

@@ -11,7 +11,10 @@ import { getDefaultPlVersion } from '../common/pl_version';
 import net from 'net';
 import type { PlLicenseMode, SshPlConfigGenerationResult } from '@milaboratories/pl-config';
 import { generateSshPlConfigs, getFreePort } from '@milaboratories/pl-config';
+import type { SupervisorStatus } from './supervisord';
 import { supervisorStatus, supervisorStop as supervisorCtlShutdown, generateSupervisordConfig, supervisorCtlStart } from './supervisord';
+import type { ConnectionInfo, SshPlPorts } from './connection_info';
+import { newConnectionInfo, parseConnectionInfo, stringifyConnectionInfo } from './connection_info';
 
 export class SshPl {
   private initState: PlatformaInitState = {};
@@ -42,49 +45,60 @@ export class SshPl {
     this.sshClient.close();
   }
 
-  public async isAlive(): Promise<boolean> {
+  /** Provides an info if the platforma and minio are running along with the debug info. */
+  public async isAlive(): Promise<SupervisorStatus> {
     const arch = await this.getArch();
     const remoteHome = await this.getUserHomeDirectory();
-
-    try {
-      return await supervisorStatus(this.logger, this.sshClient, remoteHome, arch.arch);
-    } catch (e: unknown) {
-      // probably there are no supervisor on the server.
-      return false;
-    }
+    return await supervisorStatus(this.logger, this.sshClient, remoteHome, arch.arch);
   }
 
+  /** Starts all the services on the server.
+    * Idempotent semantic: we could call it several times. */
   public async start() {
     const arch = await this.getArch();
     const remoteHome = await this.getUserHomeDirectory();
 
     try {
-      await supervisorCtlStart(this.sshClient, remoteHome, arch.arch);
+      if (!(await this.isAlive()).allAlive) {
+        await supervisorCtlStart(this.sshClient, remoteHome, arch.arch);
 
-      // We are waiting for Platforma to run to ensure that it has started.
-      return await this.checkIsAliveWithInterval();
+        // We are waiting for Platforma to run to ensure that it has started.
+        return await this.checkIsAliveWithInterval();
+      }
     } catch (e: unknown) {
-      const msg = `ssh.start: error occurred ${e}`;
+      const msg = `SshPl.start: error occurred ${e}`;
       this.logger.error(msg);
       throw new Error(msg);
     }
   }
 
+  /** Stops all the services on the server.
+    * Idempotent semantic: we could call it several times. */
   public async stop() {
     const arch = await this.getArch();
     const remoteHome = await this.getUserHomeDirectory();
 
     try {
-      await supervisorCtlShutdown(this.sshClient, remoteHome, arch.arch);
-      return await this.checkIsAliveWithInterval(undefined, undefined, false);
+      if ((await this.isAlive()).allAlive) {
+        await supervisorCtlShutdown(this.sshClient, remoteHome, arch.arch);
+        return await this.checkIsAliveWithInterval(undefined, undefined, false);
+      }
     } catch (e: unknown) {
-      const msg = `ssh.stop: error occurred ${e}`;
+      const msg = `PlSsh.stop: error occurred ${e}`;
       this.logger.error(msg);
       throw new Error(msg);
     }
   }
 
+  /** Stops the services, deletes a directory with the state and closes SSH connection. */
   public async reset(): Promise<boolean> {
+    await this.stopAndClean();
+    this.cleanUp();
+    return true;
+  }
+
+  /** Stops platforma and deletes its state. */
+  public async stopAndClean(): Promise<void> {
     const workDir = await this.getUserHomeDirectory();
 
     this.logger.info(`pl.reset: Stop Platforma on the server`);
@@ -92,26 +106,35 @@ export class SshPl {
 
     this.logger.info(`pl.reset: Deleting Platforma workDir ${workDir} on the server`);
     await this.sshClient.deleteFolder(plpath.workDir(workDir));
-
-    this.cleanUp();
-
-    return true;
   }
 
-  public async platformaInit(ops: SshPlConfig): Promise<SshInitReturnTypes> {
-    const state: PlatformaInitState = { localWorkdir: ops.localWorkdir };
+  /** Downloads binaries and untar them on the server,
+   * generates all the configs, creates necessary dirs,
+   * and finally starts all the services. */
+  public async platformaInit(options: SshPlConfig): Promise<ConnectionInfo> {
+    const state: PlatformaInitState = { localWorkdir: options.localWorkdir };
 
     try {
+      // merge options with default ops.
+      const ops: SshPlConfig = {
+        ...defaultSshPlConfig,
+        ...options,
+      };
       state.arch = await this.getArch();
       state.remoteHome = await this.getUserHomeDirectory();
-      state.isAlive = await this.isAlive();
+      state.alive = await this.isAlive();
 
-      if (state.isAlive) {
+      if (state.alive.allAlive) {
         state.userCredentials = await this.getUserCredentials(state.remoteHome);
         if (!state.userCredentials) {
           throw new Error(`SshPl.platformaInit: platforma is alive but userCredentials are not found`);
         }
-        return state.userCredentials;
+        const needRestart = state.userCredentials.useGlobalAccess != ops.useGlobalAccess;
+        if (!needRestart)
+          return state.userCredentials;
+
+        // make sure that we won't be in a broken state.
+        await this.stopAndClean();
       }
 
       const downloadRes = await this.downloadBinariesAndUploadToTheServer(
@@ -143,6 +166,7 @@ export class SshPl {
           },
         },
         licenseMode: ops.license,
+        useGlobalAccess: notEmpty(ops.useGlobalAccess),
       });
       state.generatedConfig = { ...config, filesToCreate: { skipped: 'it is too wordy' } };
 
@@ -171,25 +195,22 @@ export class SshPl {
         throw new Error(`Can not write supervisord config on the server ${plpath.workDir(state.remoteHome)}`);
       }
 
-      state.connectionInfo = {
-        plUser: config.plUser,
-        plPassword: config.plPassword,
-        ports: state.ports,
-      };
+      state.connectionInfo = newConnectionInfo(
+        config.plUser,
+        config.plPassword,
+        state.ports,
+        notEmpty(ops.useGlobalAccess),
+      );
       await this.sshClient.writeFileOnTheServer(
         plpath.connectionInfo(state.remoteHome),
-        JSON.stringify(state.connectionInfo, undefined, 2),
+        stringifyConnectionInfo(state.connectionInfo),
       );
 
       await this.start();
       state.started = true;
       this.initState = state;
 
-      return {
-        plUser: config.plUser,
-        plPassword: config.plPassword,
-        ports: state.ports,
-      };
+      return state.connectionInfo;
     } catch (e: unknown) {
       const msg = `SshPl.platformaInit: error occurred: ${e}, state: ${JSON.stringify(state)}`;
       this.logger.error(msg);
@@ -239,8 +260,10 @@ export class SshPl {
 
   /** We have to extract pl in the remote server,
   * because Windows doesn't support symlinks
-  * that are found in linux pl binaries tgz archive.
-  * For this reason, we extract all to the remote server. */
+  * that are found in Linux pl binaries tgz archive.
+  * For this reason, we extract all to the remote server.
+  * It requires `tar` to be installed on the server
+  * (it's not installed for Rocky Linux for example). */
   public async downloadAndUntar(
     localWorkdir: string,
     remoteHome: string,
@@ -308,28 +331,28 @@ export class SshPl {
     return false;
   }
 
-  public async checkIsAliveWithInterval(interval: number = 1000, count = 15, shouldStart = true) {
+  public async checkIsAliveWithInterval(interval: number = 1000, count = 15, shouldStart = true): Promise<void> {
     const maxMs = count * interval;
 
     let total = 0;
     let alive = await this.isAlive();
-    while (shouldStart ? !alive : alive) {
+    while (shouldStart ? !alive.allAlive : alive.allAlive) {
       await sleep(interval);
       total += interval;
       if (total > maxMs) {
-        throw new Error(`isAliveWithInterval: The process did not ${shouldStart ? 'started' : 'stopped'} after ${maxMs} ms.`);
+        throw new Error(`isAliveWithInterval: The process did not ${shouldStart ? 'started' : 'stopped'} after ${maxMs} ms. Live status: ${JSON.stringify(alive)}`);
       }
       alive = await this.isAlive();
     }
   }
 
-  public async getUserCredentials(remoteHome: string): Promise<SshInitReturnTypes> {
+  public async getUserCredentials(remoteHome: string): Promise<ConnectionInfo> {
     const connectionInfo = await this.sshClient.readFile(plpath.connectionInfo(remoteHome));
-    return JSON.parse(connectionInfo) as SshInitReturnTypes;
+    return parseConnectionInfo(connectionInfo);
   }
 
-  public async fetchPorts(remoteHome: string, arch: Arch): Promise<SshPlatformaPorts> {
-    const ports: SshPlatformaPorts = {
+  public async fetchPorts(remoteHome: string, arch: Arch): Promise<SshPlPorts> {
+    const ports: SshPlPorts = {
       grpc: {
         local: await getFreePort(),
         remote: await this.getFreePortForPlatformaOnServer(remoteHome, arch),
@@ -403,41 +426,20 @@ export class SshPl {
   }
 }
 
-export type SshPlatformaPorts = {
-  grpc: {
-    local: number;
-    remote: number;
-  };
-  monitoring: {
-    local: number;
-    remote: number;
-  };
-  debug: {
-    local: number;
-    remote: number;
-  };
-  minioPort: {
-    local: number;
-    remote: number;
-  };
-  minioConsolePort: {
-    local: number;
-    remote: number;
-  };
-};
-
 type Arch = { platform: string; arch: string };
 
 export type SshPlConfig = {
   localWorkdir: string;
   license: PlLicenseMode;
+  useGlobalAccess?: boolean;
 };
 
-export type SshInitReturnTypes = {
-  plUser: string;
-  plPassword: string;
-  ports: SshPlatformaPorts;
-} | null;
+const defaultSshPlConfig: Pick<
+  SshPlConfig,
+  'useGlobalAccess'
+> = {
+  useGlobalAccess: false,
+};
 
 type BinPaths = {
   history?: DownloadAndUntarState[];
@@ -462,12 +464,12 @@ type PlatformaInitState = {
   localWorkdir?: string;
   arch?: Arch;
   remoteHome?: string;
-  isAlive?: boolean;
-  userCredentials?: SshInitReturnTypes;
+  alive?: SupervisorStatus;
+  userCredentials?: ConnectionInfo;
   downloadedBinaries?: DownloadAndUntarState[];
   binPaths?: BinPaths;
-  ports?: SshPlatformaPorts;
+  ports?: SshPlPorts;
   generatedConfig?: SshPlConfigGenerationResult;
-  connectionInfo?: SshInitReturnTypes;
+  connectionInfo?: ConnectionInfo;
   started?: boolean;
 };

package/src/ssh/pl_paths.ts

@@ -9,11 +9,11 @@ export const supervisordDirName = 'supervisord-0.7.3';
 export const supervisordSubDirName = 'supervisord_0.7.3_Linux_64-bit';
 
 export function workDir(remoteHome: string) {
-  return upath.join(remoteHome, 'platforma_ssh');
+  return upath.join(remoteHome, '.platforma_ssh');
 }
 
 export function binariesDir(remoteHome: string) {
-  return upath.join(remoteHome, 'platforma_ssh', 'binaries');
+  return upath.join(workDir(remoteHome), 'binaries');
 }
 
 export function platformaBaseDir(remoteHome: string, arch: string) {
@@ -28,6 +28,10 @@ export function platformaBin(remoteHome: string, arch: string) {
   return upath.join(platformaDir(remoteHome, arch), 'platforma');
 }
 
+export function platformaConf(remoteHome: string): string {
+  return upath.join(workDir(remoteHome), 'config.yaml');
+}
+
 export function platformaFreePortBin(remoteHome: string, arch: string): string {
   return upath.join(platformaDir(remoteHome, arch), 'free-port');
 }

package/src/ssh/ssh.ts

@@ -314,12 +314,6 @@ export class SshClient {
     });
   }
 
-  delay(delay: number): Promise<void> {
-    return new Promise((res, rej) => {
-      setTimeout(() => res(), delay);
-    });
-  }
-
   public async withSftp<R>(callback: (sftp: SFTPWrapper) => Promise<R>): Promise<R> {
     return new Promise((resolve, reject) => {
       this.client.sftp((err, sftp) => {
@@ -441,9 +435,9 @@ export class SshClient {
   async checkFileExists(remotePath: string) {
     return this.withSftp(async (sftp) => {
       return new Promise((resolve, reject) => {
-        sftp.stat(remotePath, (err, stats) => {
+        sftp.stat(remotePath, (err: Error | undefined, stats) => {
           if (err) {
-            if ((err as Error & { code: number }).code === 2) {
+            if ((err as unknown as { code?: number })?.code === 2) {
               return resolve(false);
             }
             return reject(new Error(`ssh.checkFileExists: err ${err}`));
@@ -540,8 +534,12 @@ export class SshClient {
   public async uploadDirectory(localDir: string, remoteDir: string, mode: number = 0o660): Promise<void> {
     return new Promise((resolve, reject) => {
       this.withSftp(async (sftp: SFTPWrapper) => {
-        await this.__uploadDirectory(sftp, localDir, remoteDir, mode);
-        resolve();
+        try {
+          await this.__uploadDirectory(sftp, localDir, remoteDir, mode);
+          resolve();
+        } catch (e: unknown) {
+          reject(new Error(`ssh.uploadDirectory: ${e}`));
+        }
       });
     });
   }

package/src/ssh/supervisord.ts

@@ -2,7 +2,7 @@
 
 import type { MiLogger } from '@milaboratories/ts-helpers';
 import * as plpath from './pl_paths';
-import type { SshClient } from './ssh';
+import type { SshClient, SshExecResult } from './ssh';
 import { randomBytes } from 'crypto';
 
 export async function supervisorCtlStart(
@@ -27,31 +27,45 @@ export async function supervisorStop(
   }
 }
 
-type SupervisorStatus = {
-  platforma: boolean;
-  minio: boolean;
+/** Provides a simple true/false response got from supervisord status
+ * along with a debug info that could be showed in error logs (raw response from the command, parsed response etc). */
+export type SupervisorStatus = {
+  platforma?: boolean;
+  minio?: boolean;
+  allAlive: boolean; // true when both pl and minio are alive.
+  rawResult?: SshExecResult;
+  execError?: string;
 };
 
 export async function supervisorStatus(
   logger: MiLogger,
   sshClient: SshClient,
   remoteHome: string, arch: string,
-): Promise<boolean> {
-  const result = await supervisorExec(sshClient, remoteHome, arch, 'ctl status');
+): Promise<SupervisorStatus> {
+  let result: SshExecResult;
+  try {
+    result = await supervisorExec(sshClient, remoteHome, arch, 'ctl status');
+  } catch (e: unknown) {
+    return { execError: String(e), allAlive: false };
+  }
 
   if (result.stderr) {
     logger.info(`supervisord ctl status: stderr occurred: ${result.stderr}, stdout: ${result.stdout}`);
 
-    return false;
+    return { rawResult: result, allAlive: false };
   }
 
+  const platforma = isProgramRunning(result.stdout, 'platforma');
+  const minio = isProgramRunning(result.stdout, 'minio');
   const status: SupervisorStatus = {
-    platforma: isProgramRunning(result.stdout, 'platforma'),
-    minio: isProgramRunning(result.stdout, 'minio'),
+    rawResult: result,
+    platforma,
+    minio,
+    allAlive: platforma && minio,
   };
 
-  if (status.platforma && status.minio) {
-    return true;
+  if (status.allAlive) {
+    return status;
   }
 
   if (!status.minio) {
@@ -62,7 +76,7 @@ export async function supervisorStatus(
     logger.warn('Platforma is not running on the server');
   }
 
-  return false;
+  return status;
 }
 
 export function generateSupervisordConfig(