chore: add additional jsdoc comments

nathanklick · nathanklick · commit 011af3c0dc2d · 2024-11-19T22:46:35.000-06:00
Signed-off-by: Nathan Klick &lt;nathan@swirldslabs.com&gt;
diff --git a/src/core/lease/lease_holder.ts b/src/core/lease/lease_holder.ts
@@ -19,11 +19,28 @@ import { MissingArgumentError } from '../errors.ts'
 import os from 'node:os'
 import process from 'node:process'
 
+/**
+ * A representation of a leaseholder who is identified by a username, hostname, and process id (PID). This implementation
+ * is serializable to/from a JSON object and is comparable to other leaseholders.
+ */
 export class LeaseHolder {
+    /** The user's identity which is typically the OS login username. */
     private readonly _username: string
+
+    /** The machine's identity which is typically the hostname. */
     private readonly _hostname: string
+
+    /** The process identifier which is typically the OS PID. */
     private readonly _processId: number
 
+    /**
+     * Constructs a new leaseholder with the given username, hostname, and process id. This constructor is private and
+     * should not be called directly. Use the static factory methods to create a new instance.
+     *
+     * @param username - the user's identity.
+     * @param hostname - the machine's identity.
+     * @param processId - the process identifier.
+     */
     private constructor (username: string, hostname: string, processId: number) {
         if (!username) throw new MissingArgumentError('username is required')
         if (!hostname) throw new MissingArgumentError('hostname is required')
@@ -34,26 +51,54 @@ export class LeaseHolder {
         this._processId = processId
     }
 
+    /**
+     * Creates a new leaseholder with the given username. The hostname is set to the current machine's hostname and the
+     * process id is set to the current process's PID.
+     * @param username - the user's identity.
+     * @returns a new leaseholder instance.
+     */
     public static of (username: string): LeaseHolder {
         return new LeaseHolder(username, os.hostname(), process.pid)
     }
 
+    /**
+     * Creates a new leaseholder by retrieving the current user's identity, the current machine's hostname, and the
+     * current process's PID.
+     * @returns a new leaseholder instance.
+     */
     public static default (): LeaseHolder {
         return LeaseHolder.of(os.userInfo().username)
     }
 
+    /**
+     * The user's identity which is typically the OS login username.
+     * @returns the user's identity.
+     */
     public get username (): string {
         return this._username
     }
 
+
+    /**
+     * The machine's identity which is typically the hostname.
+     * @returns the machine's identity.
+     */
     public get hostname (): string {
         return this._hostname
     }
 
+    /**
+     * The process identifier which is typically the OS PID.
+     * @returns the process identifier.
+     */
     public get processId (): number {
         return this._processId
     }
 
+    /**
+     * Returns a plain object representation of this leaseholder. This object may be serialized to JSON.
+     * @returns a plain object representation of this leaseholder.
+     */
     public toObject (): any {
         return {
             username: this._username,
@@ -62,14 +107,31 @@ export class LeaseHolder {
         }
     }
 
+    /**
+     * Compares this leaseholder to another leaseholder to determine if they are equal. Two leaseholders are equal if
+     * their username, hostname, and process id are the same.
+     * @param other - the other leaseholder to compare.
+     * @returns true if the leaseholders are equal; false otherwise.
+     */
     public equals (other: LeaseHolder): boolean {
         return this.username === other.username && this.hostname === other.hostname && this.processId === other.processId
     }
 
+    /**
+     * Compares this leaseholder to another leaseholder to determine if they are the same machine. Two leaseholders are
+     * the same machine if their username and hostname are the same.
+     * @param other - the other leaseholder to compare.
+     * @returns true if the leaseholders are the same machine; false otherwise.
+     */
     public isSameMachineIdentity (other: LeaseHolder): boolean {
         return this.username === other.username && this.hostname === other.hostname
     }
 
+    /**
+     * Determines if the process associated with this leaseholder is still alive. This method will return false if the
+     * process is not alive or an error occurs while checking the process status.
+     * @returns true if the process is alive; false otherwise.
+     */
     public isProcessAlive (): boolean {
         try {
             return process.kill(this.processId, 0)
@@ -78,10 +140,19 @@ export class LeaseHolder {
         }
     }
 
+    /**
+     * Serializes this leaseholder to a JSON string representation.
+     * @returns a JSON string representation of this leaseholder.
+     */
     public toJson (): string {
         return JSON.stringify(this.toObject())
     }
 
+    /**
+     * Deserializes a JSON string representation of a leaseholder into a new leaseholder instance.
+     * @param json - the JSON string representation of a leaseholder.
+     * @returns a new leaseholder instance.
+     */
     public static fromJson (json: string): LeaseHolder {
         const obj: ReturnType<LeaseHolder['toObject']> = JSON.parse(json)
         return new LeaseHolder(obj.username, obj.hostname, obj.pid)
diff --git a/src/core/lease/lease_manager.ts b/src/core/lease/lease_manager.ts
@@ -24,55 +24,90 @@ import { Lease } from './lease.ts'
 import { LeaseHolder } from './lease_holder.ts'
 import { LeaseAcquisitionError } from './lease_errors.ts'
 
+/**
+ * Manages the acquisition and renewal of leases.
+ */
 export class LeaseManager {
 
-  private readonly _logger: SoloLogger
-  private readonly _renewalService: LeaseRenewalService
-
-  constructor (
-    private readonly k8: K8,
-    private readonly configManager: ConfigManager,
-    logger: SoloLogger,
-    renewalService: LeaseRenewalService
-  ) {
-    if (!k8) throw new MissingArgumentError('an instance of core/K8 is required')
-    if (!logger) throw new MissingArgumentError('an instance of core/SoloLogger is required')
-    if (!configManager) throw new MissingArgumentError('an instance of core/ConfigManager is required')
-    if (!renewalService) throw new MissingArgumentError('an instance of core/LeaseRenewalService is required')
+    /** The injected logger instance. */
+    private readonly _logger: SoloLogger
 
-    this._logger = logger
-    this._renewalService = renewalService
-  }
+    /** The injected lease renewal service instance. */
+    private readonly _renewalService: LeaseRenewalService
 
-  public async create (): Promise<Lease> {
-    return new Lease(this.k8, this._renewalService, LeaseHolder.default(), await this.currentNamespace())
-  }
+    /**
+     * Creates a new lease manager.
+     *
+     * @param k8 - the Kubernetes client.
+     * @param configManager - the configuration manager.
+     * @param logger - the logger.
+     * @param renewalService - the lease renewal service.
+     */
+    constructor (
+        private readonly k8: K8,
+        private readonly configManager: ConfigManager,
+        logger: SoloLogger,
+        renewalService: LeaseRenewalService
+    ) {
+        if (!k8) throw new MissingArgumentError('an instance of core/K8 is required')
+        if (!logger) throw new MissingArgumentError('an instance of core/SoloLogger is required')
+        if (!configManager) throw new MissingArgumentError('an instance of core/ConfigManager is required')
+        if (!renewalService) throw new MissingArgumentError('an instance of core/LeaseRenewalService is required')
 
-  public get renewalService (): LeaseRenewalService {
-    return this._renewalService
-  }
+        this._logger = logger
+        this._renewalService = renewalService
+    }
 
-  public get logger (): SoloLogger {
-    return this._logger
-  }
+    /**
+     * Creates a new lease. This lease is not acquired until the `acquire` method is called.
+     *
+     * @returns a new lease instance.
+     */
+    public async create (): Promise<Lease> {
+        return new Lease(this.k8, this._renewalService, LeaseHolder.default(), await this.currentNamespace())
+    }
 
-  private async currentNamespace (): Promise<string> {
-    const deploymentNamespace = this.configManager.getFlag<string>(flags.namespace)
-    const clusterSetupNamespace = this.configManager.getFlag<string>(flags.clusterSetupNamespace)
+    /**
+     * Retrieves the renewal service implementation.
+     *
+     * @returns the lease renewal service.
+     */
+    public get renewalService (): LeaseRenewalService {
+        return this._renewalService
+    }
 
-    if (!deploymentNamespace && !clusterSetupNamespace) {
-      return null
+    /**
+     * Retrieves the logger instance.
+     *
+     * @returns the logger.
+     */
+    public get logger (): SoloLogger {
+        return this._logger
     }
-    const namespace = deploymentNamespace ? deploymentNamespace : clusterSetupNamespace
 
-    if (!await this.k8.hasNamespace(namespace)) {
-      await this.k8.createNamespace(namespace)
+    /**
+     * Retrieves the user or configuration supplied namespace to use for lease acquisition.
+     *
+     * @returns the namespace to use for lease acquisition or null if no namespace is specified.
+     * @throws LeaseAcquisitionError if the namespace does not exist and cannot be created.
+     */
+    private async currentNamespace (): Promise<string> {
+        const deploymentNamespace = this.configManager.getFlag<string>(flags.namespace)
+        const clusterSetupNamespace = this.configManager.getFlag<string>(flags.clusterSetupNamespace)
 
-      if (!await this.k8.hasNamespace(namespace)) {
-        throw new LeaseAcquisitionError(`failed to create the '${namespace}' namespace`)
-      }
-    }
+        if (!deploymentNamespace && !clusterSetupNamespace) {
+            return null
+        }
+        const namespace = deploymentNamespace ? deploymentNamespace : clusterSetupNamespace
+
+        if (!await this.k8.hasNamespace(namespace)) {
+            await this.k8.createNamespace(namespace)
 
-    return namespace
-  }
+            if (!await this.k8.hasNamespace(namespace)) {
+                throw new LeaseAcquisitionError(`failed to create the '${namespace}' namespace`)
+            }
+        }
+
+        return namespace
+    }
 }
diff --git a/src/core/lease/lease_renewal.ts b/src/core/lease/lease_renewal.ts
@@ -17,25 +17,79 @@
 import { type Lease } from './lease.ts'
 import { SECONDS } from '../constants.ts'
 
+/**
+ * A service for managing cancellable lease renewals.
+ */
 export interface LeaseRenewalService {
+    /**
+     * Determines if a lease renewal is scheduled.
+     * @param scheduleId - the unique identifier of the scheduled lease renewal.
+     * @returns true if the lease renewal is scheduled; false otherwise.
+     */
     isScheduled (scheduleId: number): Promise<boolean>
+
+    /**
+     * Schedules a lease renewal.
+     * @param lease - the lease to be renewed.
+     * @returns the unique identifier of the scheduled lease renewal.
+     */
     schedule (lease: Lease): Promise<number>
+
+    /**
+     * Cancels a scheduled lease renewal.
+     * @param scheduleId - the unique identifier of the scheduled lease renewal.
+     * @returns true if the lease renewal was successfully cancelled; false otherwise.
+     */
     cancel (scheduleId: number): Promise<boolean>
+
+    /**
+     * Cancels all scheduled lease renewals.
+     * @returns a map of the unique identifiers of the scheduled lease renewals and their cancellation status.
+     */
     cancelAll (): Promise<Map<number, boolean>>
+
+    /**
+     * Calculates the delay before the next lease renewal.
+     * @param lease - the lease to be renewed.
+     * @returns the delay in milliseconds.
+     */
     calculateRenewalDelay (lease: Lease): number
 }
 
+/**
+ * Implements a lease renewal service which utilizes a setInterval() based approach to renew leases at regular intervals.
+ * The renewal delay is calculated as half the duration of the lease in seconds.
+ */
 export class IntervalLeaseRenewalService implements LeaseRenewalService {
+
+    /** The internal registry used to track all non-cancelled lease renewals. */
     private readonly _scheduledLeases: Map<number, Lease>
 
+    /**
+     * Constructs a new interval lease renewal service.
+     */
     constructor () {
         this._scheduledLeases = new Map<number, Lease>()
     }
 
+    /**
+     * Determines if a lease renewal is scheduled.
+     * This implementation uses the internal registry to track all non-cancelled lease renewals.
+     *
+     * @param scheduleId - the unique identifier of the scheduled lease renewal.
+     * @returns true if the lease renewal is scheduled; false otherwise.
+     */
     public async isScheduled (scheduleId: number): Promise<boolean> {
         return this._scheduledLeases.has(scheduleId)
     }
 
+    /**
+     * Schedules a lease renewal.
+     * This implementation uses the setInterval() method to renew the lease at regular intervals.
+     *
+     * @param lease - the lease to be renewed.
+     * @returns the unique identifier of the scheduled lease renewal. The unique identifier is the ID of the setInterval() timeout.
+     */
     public async schedule (lease: Lease): Promise<number> {
         const renewalDelay = this.calculateRenewalDelay(lease)
         const timeout = setInterval(() => lease.tryRenew(), renewalDelay)
@@ -45,6 +99,15 @@ export class IntervalLeaseRenewalService implements LeaseRenewalService {
         return scheduleId
     }
 
+    /**
+     * Cancels a scheduled lease renewal.
+     * This implementation uses the clearInterval() method to cancel the scheduled lease renewal.
+     * Due to the nature of the setInterval()/clearInterval() methods, the scheduled event may still fire at least once
+     * after the cancellation.
+     *
+     * @param scheduleId - the unique identifier of the scheduled lease renewal. The unique identifier is the ID of the setInterval() timeout.
+     * @returns true if the lease renewal was previously scheduled; false otherwise.
+     */
     public async cancel (scheduleId: number): Promise<boolean> {
         if (!scheduleId) return false
 
@@ -55,6 +118,11 @@ export class IntervalLeaseRenewalService implements LeaseRenewalService {
         return this._scheduledLeases.delete(scheduleId)
     }
 
+    /**
+     * Cancels all scheduled lease renewals.
+     * This implementation cancels all scheduled lease renewals by iterating over the internal registry and clearing each timeout.
+     * @returns a map of the unique identifiers of the scheduled lease renewals and their cancellation status.
+     */
     public async cancelAll (): Promise<Map<number, boolean>> {
         const result = new Map<number, boolean>()
         const keys = Array.from(this._scheduledLeases.keys())
@@ -66,6 +134,13 @@ export class IntervalLeaseRenewalService implements LeaseRenewalService {
         return result
     }
 
+    /**
+     * Calculates the delay before the next lease renewal.
+     * This implementation calculates the renewal delay as half the duration of the lease.
+     *
+     * @param lease - the lease to be renewed.
+     * @returns the delay in milliseconds.
+     */
     public calculateRenewalDelay (lease: Lease): number {
         return Math.round(lease.durationSeconds * 0.5) * SECONDS
     }
diff --git a/src/core/lease/listr_lease.ts b/src/core/lease/listr_lease.ts
