From 4e7968e2ed0c2962a4fc2274a336b6295cf592a3 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 16 May 2024 10:11:58 +0000 Subject: [PATCH] Add: function docs for the SshHost class --- package.json | 2 +- src/SshHost.ts | 121 +++++++++++++++++++++++++++++++++++++------------ 2 files changed, 94 insertions(+), 29 deletions(-) diff --git a/package.json b/package.json index c29ee2e..909685d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hivessh", - "version": "0.3.3", + "version": "0.3.4", "description": "HiveSsh simplifies SSH2 connections via promise-based task execution on Linux servers with built-in server utilities and powerful command execution functions", "main": "dist/index.js", "type": "module", diff --git a/src/SshHost.ts b/src/SshHost.ts index 7fd0723..294f940 100644 --- a/src/SshHost.ts +++ b/src/SshHost.ts @@ -15,6 +15,12 @@ export class SshHost { sftp: SFTPPromiseWrapper = undefined as any release: OsRelease = undefined as any + /** + * + * @description The only public function to create a SshHost object. + * @param options Connection options for the ssh host + * @returns A promise that resolves when the connection is established and the promise provides you an SshHost object + */ static async connect( options: SshHostOptions, ): Promise { @@ -29,30 +35,6 @@ export class SshHost { public settings: SshHostSettings ) { } - private emergencyClose(err: Error | string) { - if (typeof err == "string") { - err = new Error(err) - } - - this.connected = false - if (!this.closeErr) { - this.closeErr = err - } - this.ssh.destroy() - } - - throwCloseError(): void | never { - if (!this.connected) { - if (this.closeErr) { - throw this.closeErr - } - - throw new Error( - "SshHost is not connected!" - ) - } - } - private async connect(): Promise { this.ssh = await handleHops(this.settings) this.connected = true @@ -98,6 +80,37 @@ export class SshHost { } + private emergencyClose(err: Error | string) { + if (typeof err == "string") { + err = new Error(err) + } + + this.connected = false + if (!this.closeErr) { + this.closeErr = err + } + this.ssh.destroy() + } + + /** + * @description If the SshHost socket is closed because of an error this method throws that error. + * @throws Ssh socket close reason + */ + throwCloseError(): void | never { + if (!this.connected) { + if (this.closeErr) { + throw this.closeErr + } + + throw new Error( + "SshHost is not connected!" + ) + } + } + + /** + * @description Closes the ssh socket if still connected + */ close(): void { if (this.connected) { this.ssh.end() @@ -105,6 +118,13 @@ export class SshHost { this.connected = false } + /** + * + * @param cmd Command string to execute + * @param options Command channel execution options + * @description Opens a ssh channel to handle a command execution by yourself + * @returns A promise that resolves when the command begins execution and the promise provides you with the SshChannel to process the command output + */ execChannel( cmd: string, options?: CmdChannelOptions @@ -118,6 +138,13 @@ export class SshHost { ) } + /** + * + * @param cmd Command string to execute + * @param options Command execution options + * @description Opens an SSH channel to execute the command and resolves the promise as soon as the exit code is available for the executed command + * @returns A promise that resolves when the command begins execution and the promise provides you the process some runtime, stdout, stderr and some exit data + */ async exec( cmd: string, options?: CmdExecOptions @@ -146,6 +173,13 @@ export class SshHost { } } + /** + * + * @param pwd Inital path of the session + * @param sudo Defines if commands should be prefied as sudo + * @param timeoutMillis Default command timeout milliseconds + * @returns The new created ExecSession object + */ session( pwd: string, sudo?: boolean, @@ -169,6 +203,12 @@ export class SshHost { return trimAll(result.out) } + /** + * + * @param cmd Command to check if it cmdExists + * @description Function that checks if a spisific command exists on the remote ssh host + * @returns True if command exists and false if not + */ async cmdExists( cmd: string ): Promise { @@ -186,10 +226,22 @@ export class SshHost { } cachedOsRelease: OsRelease | undefined - fetchOsRelease(): Awaitable { + + /** + * + * @description Resolves all releases files from '/etc/*-release' on the remove ssh host and maps them. Also tries to detect the distro name and version. + * @param useCache The return value of this function get cached for the next function call. Set this to false to disable the caching. + * @returns Returns an object that maps all values of all '/etc/*-release' files. + */ + fetchOsRelease( + useCache: boolean = true, + ): Awaitable { this.throwCloseError() - if (this.cachedOsRelease) { + if ( + useCache && + this.cachedOsRelease + ) { return this.cachedOsRelease } @@ -201,10 +253,23 @@ export class SshHost { } cachedApm: AbstractPackageManager | undefined - getApm(): Awaitable { + + /** + * + * @description Checks one of the predefined package mangers is installed (apt, dnf, yum or a custom one) and returns a abstract interface for that package manager. + * @param useCache The return value of this function get cached for the next function call. Set this to false to disable the caching. + * @throws Throws an error if the package manager cant be detected. + * @returns The abstract interface of the hosts package manager (if found). + */ + getApm( + useCache: boolean = true, + ): Awaitable { this.throwCloseError() - if (this.cachedApm) { + if ( + useCache && + this.cachedApm + ) { return this.cachedApm }