@push.rocks/qenv 7.0.0 → 8.1.0

package/ts/qenv.classes.qenv.ts

@@ -1,25 +1,60 @@
 import * as plugins from './qenv.plugins.js';
+import {
+  QenvInvalidQenvFileError,
+  type TQenvInvalidQenvFileReason,
+} from './qenv.classes.invalidqenvfileerror.js';
+import { QenvMissingQenvFileError } from './qenv.classes.missingqenvfileerror.js';
+import { QenvMissingRequiredEnvVarsError } from './qenv.classes.missingrequiredenvvarserror.js';
 
+/**
+ * a reference to an environment variable: its name, or an async function that produces the value.
+ * The function form is only honoured by the async getters; the synchronous getter accepts names.
+ */
 export type TEnvVarRef = string | (() => Promise<string>);
-type TKeyValueObject = Record<string, any>;
+
+/** the resolved value of every available required env var, always a string */
+export type TEnvVarValueMap = Record<string, string>;
+
+/** a parsed qenv.yml, env file or secret.json, whose values are whatever the file declared */
+type TParsedFileObject = Record<string, unknown>;
 
 export class Qenv {
+  /** the names listed under `required:` in qenv.yml */
   public requiredEnvVars: string[] = [];
+
+  /** the required names that a source provided */
   public availableEnvVars: string[] = [];
+
+  /** the required names that no source provided */
   public missingEnvVars: string[] = [];
-  public keyValueObject: TKeyValueObject = {};
+
+  /** the resolved value of every available required name */
+  public keyValueObject: TEnvVarValueMap = {};
+
   public logger = new plugins.smartlog.ConsoleLog();
 
   public qenvFilePathAbsolute = '';
   public envFilePathAbsolute?: string;
 
+  /**
+   * Resolves every name listed under `required:` in qenv.yml while constructing.
+   * @param qenvFileBasePathArg directory that holds qenv.yml
+   * @param envFileBasePathArg directory that holds env.json, env.yml or env.yaml
+   * @param failOnMissing throws a QenvMissingRequiredEnvVarsError when a variable listed under
+   * `required:` in qenv.yml is not provided by any source, a QenvMissingQenvFileError when there
+   * is no qenv.yml to read that list from, and a QenvInvalidQenvFileError when the list cannot be
+   * read as names. Pass false to only record the names in `missingEnvVars` and continue.
+   * @throws QenvMissingQenvFileError
+   * @throws QenvInvalidQenvFileError
+   * @throws QenvMissingRequiredEnvVarsError
+   */
   constructor(
     qenvFileBasePathArg: string = process.cwd(),
     envFileBasePathArg?: string,
     failOnMissing: boolean = true
   ) {
     this.initializeFilePaths(qenvFileBasePathArg, envFileBasePathArg);
-    this.loadRequiredEnvVars();
+    this.loadRequiredEnvVars(failOnMissing);
     this.loadAvailableEnvVars();
     this.checkForMissingEnvVars(failOnMissing);
   }
@@ -29,18 +64,18 @@ export class Qenv {
       plugins.path.resolve(qenvFileBasePathArg),
       'qenv.yml'
     );
-  
+
     if (envFileBasePathArg) {
       const envFileBasePath = plugins.path.resolve(envFileBasePathArg);
-  
+
       const envFileJsonPath = plugins.path.join(envFileBasePath, 'env.json');
       const envFileYmlPath = plugins.path.join(envFileBasePath, 'env.yml');
       const envFileYamlPath = plugins.path.join(envFileBasePath, 'env.yaml');
-  
+
       const envFileJsonExists = this.fileExists(envFileJsonPath);
       const envFileYmlExists = this.fileExists(envFileYmlPath);
       const envFileYamlExists = this.fileExists(envFileYamlPath);
-  
+
       if (envFileJsonExists && (envFileYmlExists || envFileYamlExists)) {
         this.logger.log('warn', 'Both env.json and env.yml files exist! Using env.json');
         this.envFilePathAbsolute = envFileJsonPath;
@@ -54,23 +89,79 @@ export class Qenv {
     }
   }
 
-  private loadRequiredEnvVars() {
-    if (this.fileExists(this.qenvFilePathAbsolute)) {
-      const qenvFile = this.readObjectFromFile(this.qenvFilePathAbsolute);
-      const requiredEnvVars = qenvFile.required;
-      if (Array.isArray(requiredEnvVars)) {
-        this.requiredEnvVars.push(
-          ...requiredEnvVars.filter((envVar): envVar is string => typeof envVar === 'string')
-        );
-      } else {
-        this.logger.log('warn', 'qenv.yml does not contain a "required" Array!');
+  private loadRequiredEnvVars(failOnMissing: boolean) {
+    if (!this.fileExists(this.qenvFilePathAbsolute)) {
+      if (failOnMissing) {
+        // enforcing without the file that declares what to enforce would pass every check by
+        // accident: a deployable that forgot to ship qenv.yml must be refused by name, not
+        // silently exempted
+        throw new QenvMissingQenvFileError({
+          qenvFilePathAbsolute: this.qenvFilePathAbsolute,
+          qenvDir: plugins.path.dirname(this.qenvFilePathAbsolute),
+        });
       }
+      return;
+    }
+    const qenvFile = this.readObjectFromFile(this.qenvFilePathAbsolute);
+    const declaredRequirements = qenvFile['required'];
+    if (declaredRequirements === undefined || declaredRequirements === null) {
+      // a qenv.yml that lists no requirement legitimately requires nothing
+      return;
     }
+    if (!Array.isArray(declaredRequirements)) {
+      this.refuseInvalidQenvFile(failOnMissing, 'requiredNotAnArray', declaredRequirements);
+      return;
+    }
+    const declaredEntries: unknown[] = declaredRequirements;
+    const invalidEntryIndex = declaredEntries.findIndex((entry) => typeof entry !== 'string');
+    if (invalidEntryIndex !== -1) {
+      this.refuseInvalidQenvFile(
+        failOnMissing,
+        'requiredEntryNotAString',
+        declaredEntries[invalidEntryIndex]
+      );
+    }
+    this.requiredEnvVars.push(
+      ...declaredEntries.filter((entry): entry is string => typeof entry === 'string')
+    );
+  }
+
+  /**
+   * Refuses a qenv.yml whose `required:` cannot be read as names: it enforces nothing, which is
+   * the fail-open a missing qenv.yml would be. A caller that opted out of failing keeps running,
+   * but hears the same named reason instead of losing the requirement silently.
+   */
+  private refuseInvalidQenvFile(
+    failOnMissing: boolean,
+    reason: TQenvInvalidQenvFileReason,
+    invalidValue: unknown
+  ) {
+    const invalidQenvFileError = new QenvInvalidQenvFileError({
+      qenvFilePathAbsolute: this.qenvFilePathAbsolute,
+      reason,
+      invalidValueTypeName: this.describeValueType(invalidValue),
+    });
+    if (failOnMissing) {
+      throw invalidQenvFileError;
+    }
+    this.logger.log('warn', invalidQenvFileError.message);
+  }
+
+  /** names the type of a value without rendering it: a value in a name's place may be a secret */
+  private describeValueType(valueArg: unknown): string {
+    if (valueArg === null) {
+      return 'null';
+    }
+    return Array.isArray(valueArg) ? 'array' : typeof valueArg;
   }
 
   private loadAvailableEnvVars() {
+    // resolved synchronously: a required env var is always a name, and every source a name can come
+    // from - process environment, env file, Docker secrets - is a synchronous read. Resolving it
+    // here as a promise would store a pending promise instead of a value and make the check below
+    // pass for every name.
     for (const envVar of this.requiredEnvVars) {
-      const value = this.getEnvVarOnDemand(envVar);
+      const value = this.tryGetEnvVarSync(envVar);
       if (value !== undefined) {
         this.availableEnvVars.push(envVar);
         this.keyValueObject[envVar] = value;
@@ -83,18 +174,30 @@ export class Qenv {
       (envVar) => !this.availableEnvVars.includes(envVar)
     );
 
-    if (this.missingEnvVars.length > 0) {
-      console.info('Required Env Vars are:', this.requiredEnvVars);
-      console.error('Missing Env Vars:', this.missingEnvVars);
-      if (failOnMissing) {
-        this.logger.log('error', 'Exiting due to missing env vars!');
-        process.exit(1);
-      } else {
-        this.logger.log('warn', 'qenv is not set to fail on missing environment variables');
-      }
+    if (this.missingEnvVars.length === 0) {
+      return;
+    }
+
+    if (failOnMissing) {
+      // a library must not end the process: the caller decides what an incomplete environment means
+      throw new QenvMissingRequiredEnvVarsError({
+        missingEnvVars: this.missingEnvVars,
+        requiredEnvVars: this.requiredEnvVars,
+        qenvFilePathAbsolute: this.qenvFilePathAbsolute,
+      });
     }
+
+    this.logger.log(
+      'warn',
+      `qenv is not set to fail on missing environment variables. Missing: ${this.missingEnvVars.join(', ')}`
+    );
   }
 
+  /**
+   * Resolves an env var from the process environment, the env file and the Docker secrets, in that
+   * order. An array is tried left to right and the first defined value wins.
+   * @param envVarNameOrNames a name, an async resolver function, or a list of either
+   */
   public async getEnvVarOnDemand(
     envVarNameOrNames: TEnvVarRef | TEnvVarRef[]
   ): Promise<string | undefined> {
@@ -112,23 +215,25 @@ export class Qenv {
   }
 
   /**
-   * Like getEnvVarOnDemand, but throws an error if the env var is not set.
-   * @param envVarNameOrNames 
-   * @returns 
+   * Like getEnvVarOnDemand, but throws when no source provides a value.
+   * @param envVarNameOrNames a name, an async resolver function, or a list of either
    */
   public async getEnvVarOnDemandStrict(
     envVarNameOrNames: TEnvVarRef | TEnvVarRef[]
   ): Promise<string> {
     const value = await this.getEnvVarOnDemand(envVarNameOrNames);
     if (value === undefined) {
-      throw new Error(`Env var ${envVarNameOrNames} is not set!`);
+      throw new Error(`Env var ${this.describeEnvVarRefs(envVarNameOrNames)} is not set!`);
     }
     return value;
   }
 
+  /**
+   * The synchronous counterpart of getEnvVarOnDemand. It resolves names only: an async resolver
+   * function cannot be awaited here, so the function form of TEnvVarRef is not accepted.
+   * @param envVarNameOrNames a name or a list of names
+   */
   public getEnvVarOnDemandSync(envVarNameOrNames: string | string[]): string | undefined {
-    console.warn('requesting env var sync leaves out potentially important async env sources.');
-
     if (Array.isArray(envVarNameOrNames)) {
       for (const envVarName of envVarNameOrNames) {
         const value = this.tryGetEnvVarSync(envVarName);
@@ -142,7 +247,14 @@ export class Qenv {
     }
   }
 
-  public async getEnvVarOnDemandAsObject(envVarNameOrNames: string | string[]): Promise<any> {
+  /**
+   * Resolves an env var whose value was stored as a base64 encoded object and decodes it. A plain
+   * value is returned as the string it is, so the caller narrows what it gets.
+   * @param envVarNameOrNames a name or a list of names
+   */
+  public async getEnvVarOnDemandAsObject(
+    envVarNameOrNames: string | string[]
+  ): Promise<unknown> {
     const rawValue = await this.getEnvVarOnDemand(envVarNameOrNames);
     if (rawValue && rawValue.startsWith('base64Object:')) {
       const base64Part = rawValue.split('base64Object:')[1];
@@ -156,39 +268,43 @@ export class Qenv {
       return await envVarRefArg();
     }
 
-    const sources = [
-      this.getFromEnvironmentVariable(envVarRefArg),
-      this.getFromEnvYamlOrJsonFile(envVarRefArg),
-      this.getFromDockerSecret(envVarRefArg),
-      this.getFromDockerSecretJson(envVarRefArg)
-    ];
-    
-    for (const value of sources) {
-      if (value !== undefined) {
-        return value;
-      }
-    }
-    
-    return undefined;
+    // a name resolves from synchronous sources only, so both getters share one resolution order
+    return this.tryGetEnvVarSync(envVarRefArg);
   }
 
   private tryGetEnvVarSync(envVarName: string): string | undefined {
-    const sources = [
-      this.getFromEnvironmentVariable(envVarName),
-      this.getFromEnvYamlOrJsonFile(envVarName),
-      this.getFromDockerSecret(envVarName),
-      this.getFromDockerSecretJson(envVarName)
+    // read lazily: a source is only touched once every earlier one came back undefined, so a name
+    // the process environment answers never opens a secret file, and a malformed secret.json only
+    // ever affects the names that actually reach it
+    const sources: Array<() => string | undefined> = [
+      () => this.getFromEnvironmentVariable(envVarName),
+      () => this.getFromEnvYamlOrJsonFile(envVarName),
+      () => this.getFromDockerSecret(envVarName),
+      () => this.getFromDockerSecretJson(envVarName),
     ];
-    
-    for (const value of sources) {
+
+    for (const readSource of sources) {
+      const value = readSource();
       if (value !== undefined) {
         return value;
       }
     }
-    
+
     return undefined;
   }
 
+  /** renders env var references for an error message, naming a resolver function where it has one */
+  private describeEnvVarRefs(envVarNameOrNames: TEnvVarRef | TEnvVarRef[]): string {
+    const envVarRefs = Array.isArray(envVarNameOrNames) ? envVarNameOrNames : [envVarNameOrNames];
+    return envVarRefs
+      .map((envVarRef) =>
+        typeof envVarRef === 'function'
+          ? `${envVarRef.name || 'anonymous'}()`
+          : envVarRef
+      )
+      .join(', ');
+  }
+
   private getFromEnvironmentVariable(envVarName: string): string | undefined {
     return process.env[envVarName];
   }
@@ -212,8 +328,16 @@ export class Qenv {
     }
   }
 
+  /**
+   * the directory Docker mounts secrets into. It is a method so a test can point both secret
+   * readers at a directory it is allowed to create; a process can never write /run/secrets itself.
+   */
+  protected getDockerSecretsDirectoryPath(): string {
+    return '/run/secrets';
+  }
+
   private getFromDockerSecret(envVarName: string): string | undefined {
-    const secretPath = `/run/secrets/${envVarName}`;
+    const secretPath = plugins.path.join(this.getDockerSecretsDirectoryPath(), envVarName);
     if (this.fileExists(secretPath)) {
       return plugins.fs.readFileSync(secretPath, 'utf8');
     }
@@ -221,11 +345,14 @@ export class Qenv {
   }
 
   private getFromDockerSecretJson(envVarName: string): string | undefined {
-    if (this.directoryExists('/run/secrets')) {
-      const availableSecrets = plugins.fs.readdirSync('/run/secrets');
+    const secretsDirectoryPath = this.getDockerSecretsDirectoryPath();
+    if (this.directoryExists(secretsDirectoryPath)) {
+      const availableSecrets = plugins.fs.readdirSync(secretsDirectoryPath);
       for (const secret of availableSecrets) {
         if (secret.includes('secret.json')) {
-          const secretObject = this.readObjectFromFile(`/run/secrets/${secret}`);
+          const secretObject = this.readObjectFromFile(
+            plugins.path.join(secretsDirectoryPath, secret)
+          );
           const value = secretObject[envVarName];
           if (value === undefined) {
             continue;
@@ -240,12 +367,12 @@ export class Qenv {
     return undefined;
   }
 
-  private encodeBase64(data: any): string {
+  private encodeBase64(data: unknown): string {
     const jsonString = JSON.stringify(data);
     return Buffer.from(jsonString).toString('base64');
   }
 
-  private decodeBase64(encodedString: string): any {
+  private decodeBase64(encodedString: string): unknown {
     const decodedString = Buffer.from(encodedString, 'base64').toString('utf-8');
     return JSON.parse(decodedString);
   }
@@ -265,11 +392,13 @@ export class Qenv {
     }
   }
 
-  private readObjectFromFile(filePath: string): TKeyValueObject {
+  private readObjectFromFile(filePath: string): TParsedFileObject {
     const fileString = plugins.fs.readFileSync(filePath, 'utf8');
-    const parsedObject = filePath.endsWith('.json')
+    const parsedObject: unknown = filePath.endsWith('.json')
       ? JSON.parse(fileString)
       : plugins.yaml.parse(fileString);
-    return typeof parsedObject === 'object' && parsedObject !== null ? parsedObject : {};
+    return typeof parsedObject === 'object' && parsedObject !== null
+      ? (parsedObject as TParsedFileObject)
+      : {};
   }
 }