@heroku/heroku-cli-util 9.0.1 → 9.1.0

package/dist/utils/pg/bastion.js

@@ -1,21 +1,104 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBastion = exports.env = exports.bastionKeyPlan = void 0;
-exports.fetchConfig = fetchConfig;
-exports.getConfigs = getConfigs;
+exports.getBastionConfig = void 0;
+exports.bastionKeyPlan = bastionKeyPlan;
+exports.fetchBastionConfig = fetchBastionConfig;
+exports.getPsqlConfigs = getPsqlConfigs;
 exports.sshTunnel = sshTunnel;
-exports.tunnelConfig = tunnelConfig;
-const core_1 = require("@oclif/core");
-const debug_1 = require("debug");
-const EventEmitter = require("node:events");
+const tslib_1 = require("tslib");
+const debug_1 = tslib_1.__importDefault(require("debug"));
+const node_events_1 = require("node:events");
 const node_util_1 = require("node:util");
-const createTunnel = require("tunnel-ssh");
-const host_1 = require("./host");
+const createTunnel = tslib_1.__importStar(require("tunnel-ssh"));
+const host_1 = tslib_1.__importDefault(require("./host"));
 const pgDebug = (0, debug_1.default)('pg');
-const bastionKeyPlan = (a) => Boolean(/private/.test(a.addon.plan.name));
-exports.bastionKeyPlan = bastionKeyPlan;
-const env = (db) => {
-    const baseEnv = Object.assign({ PGAPPNAME: 'psql non-interactive', PGSSLMODE: (!db.host || db.host === 'localhost') ? 'prefer' : 'require' }, process.env);
+/**
+ * Determines whether the attachment belongs to an add-on installed onto a non-shield Private Space.
+ * If true, the bastion information needs to be fetched from the Data API.
+ * For add-ons installed onto a Shield Private Space, the bastion information should be fetched from config vars.
+ *
+ * @param attachment - The add-on attachment to check
+ * @returns True if the attachment belongs to a non-shield Private Space, false otherwise
+ */
+function bastionKeyPlan(attachment) {
+    return Boolean(/private/.test(attachment.addon.plan.name.split(':', 2)[1]));
+}
+/**
+ * Fetches the bastion configuration from the Data API (only relevant for add-ons installed onto a
+ * non-shield Private Space).
+ * For add-ons installed onto a Shield Private Space, the bastion information is stored in the config vars.
+ *
+ * @param heroku - The Heroku API client
+ * @param addon - The add-on information
+ * @returns Promise that resolves to the bastion configuration
+ */
+async function fetchBastionConfig(heroku, addon) {
+    const { body: bastionConfig } = await heroku.get(`/client/v11/databases/${encodeURIComponent(addon.id)}/bastion`, { hostname: (0, host_1.default)() });
+    if (bastionConfig.host && bastionConfig.private_key) {
+        return {
+            bastionHost: bastionConfig.host,
+            bastionKey: bastionConfig.private_key,
+        };
+    }
+    return {};
+}
+/**
+ * Returns the bastion configuration from the config vars for add-ons installed onto Shield
+ * Private Spaces.
+ *
+ * If there are bastions, extracts a host and a key from the config vars.
+ * If there are no bastions, returns an empty Object.
+ *
+ * We assert that _BASTIONS and _BASTION_KEY always exist together.
+ * If either is falsy, pretend neither exist.
+ *
+ * @param config - The configuration variables object
+ * @param baseName - The base name for the configuration variables
+ * @returns The bastion configuration object
+ */
+const getBastionConfig = function (config, baseName) {
+    // <BASE_NAME>_BASTION_KEY contains the private key for the bastion.
+    const bastionKey = config[`${baseName}_BASTION_KEY`];
+    // <BASE_NAME>_BASTIONS contains a comma-separated list of hosts, select one at random.
+    const bastions = (config[`${baseName}_BASTIONS`] || '').split(',');
+    const bastionHost = bastions[Math.floor(Math.random() * bastions.length)];
+    if (bastionKey && bastionHost) {
+        return { bastionHost, bastionKey };
+    }
+    return {};
+};
+exports.getBastionConfig = getBastionConfig;
+/**
+ * Returns both the required environment variables to effect the psql command execution and the tunnel
+ * configuration according to the database connection details.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @returns Object containing database environment variables and tunnel configuration
+ */
+function getPsqlConfigs(connectionDetails) {
+    const dbEnv = baseEnv(connectionDetails);
+    const dbTunnelConfig = tunnelConfig(connectionDetails);
+    // If a tunnel is required, we need to adjust the environment variables for psql to use the tunnel host and port.
+    if (connectionDetails.bastionKey) {
+        Object.assign(dbEnv, {
+            PGHOST: dbTunnelConfig.localHost,
+            PGPORT: dbTunnelConfig.localPort.toString(),
+        });
+    }
+    return {
+        dbEnv,
+        dbTunnelConfig,
+    };
+}
+/**
+ * Returns the base environment variables for the database connection based on the connection details
+ * only, without taking into account if a tunnel is required for connecting to the database through a bastion host.
+ *
+ * @param connectionDetails - The database connection details
+ * @returns The base environment variables for the database connection
+ */
+function baseEnv(connectionDetails) {
+    // Mapping of environment variables to ConnectionDetails properties
     const mapping = {
         PGDATABASE: 'database',
         PGHOST: 'host',
@@ -23,54 +106,49 @@ const env = (db) => {
         PGPORT: 'port',
         PGUSER: 'user',
     };
+    const baseEnv = Object.assign({ PGAPPNAME: 'psql non-interactive', PGSSLMODE: (!connectionDetails.host || connectionDetails.host === 'localhost') ? 'prefer' : 'require' }, process.env);
     for (const envVar of Object.keys(mapping)) {
-        const val = db[mapping[envVar]];
+        const val = connectionDetails[mapping[envVar]];
         if (val) {
             baseEnv[envVar] = val;
         }
     }
     return baseEnv;
-};
-exports.env = env;
-async function fetchConfig(heroku, db) {
-    return heroku.get(`/client/v11/databases/${encodeURIComponent(db.id)}/bastion`, {
-        hostname: (0, host_1.default)(),
-    });
 }
-const getBastion = function (config, baseName) {
-    // If there are bastions, extract a host and a key
-    // otherwise, return an empty Object
-    // If there are bastions:
-    // * there should be one *_BASTION_KEY
-    // * pick one host from the comma-separated list in *_BASTIONS
-    // We assert that _BASTIONS and _BASTION_KEY always exist together
-    // If either is falsy, pretend neither exist
-    const bastionKey = config[`${baseName}_BASTION_KEY`];
-    const bastions = (config[`${baseName}_BASTIONS`] || '').split(',');
-    const bastionHost = bastions[Math.floor(Math.random() * bastions.length)];
-    return (bastionKey && bastionHost) ? { bastionHost, bastionKey } : {};
-};
-exports.getBastion = getBastion;
-function getConfigs(db) {
-    const dbEnv = (0, exports.env)(db);
-    const dbTunnelConfig = tunnelConfig(db);
-    if (db.bastionKey) {
-        Object.assign(dbEnv, {
-            PGHOST: dbTunnelConfig.localHost,
-            PGPORT: dbTunnelConfig.localPort,
-        });
-    }
+/**
+ * Creates a tunnel configuration object based on the connection details.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @returns The tunnel configuration object
+ */
+function tunnelConfig(connectionDetails) {
+    const localHost = '127.0.0.1';
+    const localPort = Math.floor((Math.random() * (65535 - 49152)) + 49152);
     return {
-        dbEnv,
-        dbTunnelConfig,
+        dstHost: connectionDetails.host,
+        dstPort: Number.parseInt(connectionDetails.port, 10),
+        host: connectionDetails.bastionHost,
+        localHost,
+        localPort,
+        privateKey: connectionDetails.bastionKey,
+        username: 'bastion',
     };
 }
-async function sshTunnel(db, dbTunnelConfig, timeout = 10000) {
-    if (!db.bastionKey) {
-        return null;
+/**
+ * Establishes an SSH tunnel to the database using the provided configuration.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @param dbTunnelConfig - The tunnel configuration object
+ * @param timeout - The timeout in milliseconds (default: 10000)
+ * @param createSSHTunnel - The function to create the SSH tunnel (default: promisified createTunnel.default)
+ * @returns Promise that resolves to the tunnel server or null if no bastion key is provided
+ * @throws Error if unable to establish the tunnel
+ */
+async function sshTunnel(connectionDetails, dbTunnelConfig, timeout = 10000, createSSHTunnel = (0, node_util_1.promisify)(createTunnel.default)) {
+    if (!connectionDetails.bastionKey) {
+        return;
     }
     const timeoutInstance = new Timeout(timeout, 'Establishing a secure tunnel timed out');
-    const createSSHTunnel = (0, node_util_1.promisify)(createTunnel);
     try {
         return await Promise.race([
             timeoutInstance.promise(),
@@ -79,41 +157,48 @@ async function sshTunnel(db, dbTunnelConfig, timeout = 10000) {
     }
     catch (error) {
         pgDebug(error);
-        core_1.ux.error('Unable to establish a secure tunnel to your database.');
+        throw new Error(`Unable to establish a secure tunnel to your database: ${error.message}.`);
     }
     finally {
         timeoutInstance.cancel();
     }
 }
-function tunnelConfig(db) {
-    const localHost = '127.0.0.1';
-    const localPort = Math.floor((Math.random() * (65535 - 49152)) + 49152);
-    return {
-        dstHost: db.host || undefined,
-        dstPort: (db.port && Number.parseInt(db.port, 10)) || undefined,
-        host: db.bastionHost,
-        localHost,
-        localPort,
-        privateKey: db.bastionKey,
-        username: 'bastion',
-    };
-}
+/**
+ * A timeout utility class that can be cancelled.
+ */
 class Timeout {
+    /**
+     * Creates a new Timeout instance.
+     *
+     * @param timeout - The timeout duration in milliseconds
+     * @param message - The error message to display when timeout occurs
+     */
     constructor(timeout, message) {
         // eslint-disable-next-line unicorn/prefer-event-target
-        this.events = new EventEmitter();
+        this.events = new node_events_1.EventEmitter();
         this.timeout = timeout;
         this.message = message;
     }
+    /**
+     * Cancels the timeout.
+     *
+     * @returns void
+     */
     cancel() {
         this.events.emit('cancelled');
     }
+    /**
+     * Returns a promise that resolves when the timeout is cancelled or rejects when the timeout occurs.
+     *
+     * @returns Promise that resolves to void when cancelled or rejects with an error when timeout occurs
+     */
     async promise() {
-        this.timer = setTimeout(() => {
-            this.events.emit('error', new Error(this.message));
-        }, this.timeout);
+        this.timer = setTimeout(() => this.events.emit('timeout'), this.timeout);
         try {
-            await EventEmitter.once(this.events, 'cancelled');
+            await new Promise((resolve, reject) => {
+                this.events.once('cancelled', () => resolve());
+                this.events.once('timeout', () => reject(new Error(this.message)));
+            });
         }
         finally {
             clearTimeout(this.timer);

package/dist/utils/pg/config-vars.d.ts

@@ -1,8 +1,34 @@
+import type { HTTP } from '@heroku/http-call';
 import type { APIClient } from '@heroku-cli/command';
-import type { AddOnAttachment } from '@heroku-cli/schema';
-import type { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api';
-export declare function getConfig(heroku: APIClient, app: string): Promise<Record<string, string> | undefined>;
-export declare function getConfigVarName(configVars: string[]): string;
-export declare function getConfigVarNameFromAttachment(attachment: Required<{
-    addon: AddOnAttachmentWithConfigVarsAndPlan;
-} & AddOnAttachment>, config?: Record<string, string>): string;
+import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
+/**
+ * Cache of app config vars.
+ */
+export declare const configVarsByAppIdCache: Map<string, Promise<HTTP<Record<string, string>>>>;
+/**
+ * Returns the app's config vars as a record of key-value pairs, either from the cache or from the API.
+ *
+ * @param heroku - The Heroku API client
+ * @param appId - The ID of the app to get config vars for
+ * @returns Promise resolving to a record of config var key-value pairs
+ */
+export declare function getConfig(heroku: APIClient, appId: string): Promise<Record<string, string>>;
+/**
+ * Returns the attachment's first config var name that has a `_URL` suffix, expected to be the name of the one
+ * that contains the database URL connection string.
+ *
+ * @param configVarNames - Array of config var names from the attachment
+ * @returns The first config var name ending with '_URL'
+ * @throws {Error} When no config var names end with '_URL'
+ */
+export declare function getConfigVarName(configVarNames: ExtendedAddonAttachment['config_vars']): string;
+/**
+ * Returns the config var name that contains the database URL connection string for the given
+ * attachment, based on the contents of the app's config vars.
+ *
+ * @param attachment - The addon attachment to get the config var name for
+ * @param config - Optional record of app config vars (defaults to empty object)
+ * @returns The config var name containing the database URL
+ * @throws {Error} When no config vars are found or when they don't contain a database URL
+ */
+export declare function getConfigVarNameFromAttachment(attachment: ExtendedAddonAttachment, config?: Record<string, string>): string;

package/dist/utils/pg/config-vars.js

@@ -1,34 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.configVarsByAppIdCache = void 0;
 exports.getConfig = getConfig;
 exports.getConfigVarName = getConfigVarName;
 exports.getConfigVarNameFromAttachment = getConfigVarNameFromAttachment;
 const color_1 = require("@heroku-cli/color");
-const core_1 = require("@oclif/core");
-const responseByAppId = new Map();
-async function getConfig(heroku, app) {
-    if (!responseByAppId.has(app)) {
-        const promise = heroku.get(`/apps/${app}/config-vars`);
-        responseByAppId.set(app, promise);
+/**
+ * Cache of app config vars.
+ */
+exports.configVarsByAppIdCache = new Map();
+/**
+ * Returns the app's config vars as a record of key-value pairs, either from the cache or from the API.
+ *
+ * @param heroku - The Heroku API client
+ * @param appId - The ID of the app to get config vars for
+ * @returns Promise resolving to a record of config var key-value pairs
+ */
+async function getConfig(heroku, appId) {
+    let promise = exports.configVarsByAppIdCache.get(appId);
+    if (!promise) {
+        promise = heroku.get(`/apps/${appId}/config-vars`);
+        exports.configVarsByAppIdCache.set(appId, promise);
     }
-    const result = await responseByAppId.get(app);
-    return result === null || result === void 0 ? void 0 : result.body;
+    const { body: config } = await promise;
+    return config;
 }
-function getConfigVarName(configVars) {
-    const connStringVars = configVars.filter(cv => (cv.endsWith('_URL')));
-    if (connStringVars.length === 0)
+/**
+ * Returns the attachment's first config var name that has a `_URL` suffix, expected to be the name of the one
+ * that contains the database URL connection string.
+ *
+ * @param configVarNames - Array of config var names from the attachment
+ * @returns The first config var name ending with '_URL'
+ * @throws {Error} When no config var names end with '_URL'
+ */
+function getConfigVarName(configVarNames) {
+    const urlConfigVarNames = configVarNames.filter(cv => (cv.endsWith('_URL')));
+    if (urlConfigVarNames.length === 0)
         throw new Error('Database URL not found for this addon');
-    return connStringVars[0];
+    return urlConfigVarNames[0];
 }
+/**
+ * Returns the config var name that contains the database URL connection string for the given
+ * attachment, based on the contents of the app's config vars.
+ *
+ * @param attachment - The addon attachment to get the config var name for
+ * @param config - Optional record of app config vars (defaults to empty object)
+ * @returns The config var name containing the database URL
+ * @throws {Error} When no config vars are found or when they don't contain a database URL
+ */
 function getConfigVarNameFromAttachment(attachment, config = {}) {
-    var _a, _b;
-    const configVars = (_b = (_a = attachment.addon.config_vars) === null || _a === void 0 ? void 0 : _a.filter((cv) => { var _a; return (_a = config[cv]) === null || _a === void 0 ? void 0 : _a.startsWith('postgres://'); })) !== null && _b !== void 0 ? _b : [];
-    if (configVars.length === 0) {
-        core_1.ux.error(`No config vars found for ${attachment.name}; perhaps they were removed as a side effect of ${color_1.default.cmd('heroku rollback')}? Use ${color_1.default.cmd('heroku addons:attach')} to create a new attachment and then ${color_1.default.cmd('heroku addons:detach')} to remove the current attachment.`);
+    // Handle the case where no attachment config var names remain after filtering out those that don't contain a
+    // database URL connection string in the app's config vars.
+    const connStringConfigVarNames = attachment.config_vars
+        .filter(cvn => { var _a; return (_a = config[cvn]) === null || _a === void 0 ? void 0 : _a.startsWith('postgres://'); });
+    if (connStringConfigVarNames.length === 0) {
+        throw new Error(`No config vars found for ${attachment.name}; perhaps they were removed as a side effect of`
+            + ` ${color_1.color.cmd('heroku rollback')}? Use ${color_1.color.cmd('heroku addons:attach')} to create a new attachment and `
+            + `then ${color_1.color.cmd('heroku addons:detach')} to remove the current attachment.`);
     }
+    // Generate the default config var name and return it if it contains a database URL connection string.
     const configVarName = `${attachment.name}_URL`;
-    if (configVars.includes(configVarName) && configVarName in config) {
+    if (connStringConfigVarNames.includes(configVarName) && configVarName in config) {
         return configVarName;
     }
-    return getConfigVarName(configVars);
+    // Return the first config var name that has a `_URL` suffix. This might not be needed at all anymore.
+    return getConfigVarName(connStringConfigVarNames);
 }

package/dist/utils/pg/databases.d.ts

@@ -1,12 +1,76 @@
-import type { AddOnAttachment } from '@heroku-cli/schema';
 import { APIClient } from '@heroku-cli/command';
-import type { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api';
+import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
 import type { ConnectionDetails, ConnectionDetailsWithAttachment } from '../../types/pg/tunnel';
-export declare function getAttachment(heroku: APIClient, app: string, db?: string, namespace?: string): Promise<Required<{
-    addon: AddOnAttachmentWithConfigVarsAndPlan;
-} & AddOnAttachment>>;
-export declare const getConnectionDetails: (attachment: Required<{
-    addon: AddOnAttachmentWithConfigVarsAndPlan;
-} & AddOnAttachment>, configVars?: Record<string, string>) => ConnectionDetailsWithAttachment;
-export declare function getDatabase(heroku: APIClient, app: string, db?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
-export declare const parsePostgresConnectionString: (db: string) => ConnectionDetails;
+import { fetchBastionConfig } from './bastion';
+import { getConfig } from './config-vars';
+export default class DatabaseResolver {
+    private readonly heroku;
+    private readonly getConfigFn;
+    private readonly fetchBastionConfigFn;
+    private readonly addonAttachmentResolver;
+    private readonly attachmentHeaders;
+    constructor(heroku: APIClient, getConfigFn?: typeof getConfig, fetchBastionConfigFn?: typeof fetchBastionConfig);
+    /**
+     * Resolves a database attachment based on the provided database identifier
+     * (attachment name, id, or config var name) and namespace (credential).
+     *
+     * @param appId - The ID of the app to get the attachment for
+     * @param attachmentId - The database identifier (defaults to 'DATABASE_URL')
+     * @param namespace - Optional namespace/credential for the attachment
+     * @returns Promise resolving to the database attachment
+     * @throws {Error} When no databases exist or when database identifier is unknown
+     * @throws {AmbiguousError} When multiple matching attachments are found
+     */
+    getAttachment(appId: string, attachmentId?: string, namespace?: string): Promise<ExtendedAddonAttachment>;
+    /**
+     * Returns the connection details for a database attachment resolved through the identifiers passed as
+     * arguments: appId, attachmentId and namespace (credential).
+     *
+     * @param appId - The ID of the app containing the database
+     * @param attachmentId - Optional database identifier (defaults to 'DATABASE_URL')
+     * @param namespace - Optional namespace/credential for the attachment
+     * @returns Promise resolving to connection details with attachment information
+     */
+    getDatabase(appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
+    /**
+     * Parses a PostgreSQL connection string (or a local database name) into a ConnectionDetails object.
+     *
+     * @param connStringOrDbName - PostgreSQL connection string or local database name
+     * @returns Connection details object with parsed connection information
+     */
+    parsePostgresConnectionString(connStringOrDbName: string): ConnectionDetails;
+    /**
+     * Fetches all Heroku PostgreSQL add-on attachments for a given app.
+     *
+     * This is used internally by the `getAttachment` function to get all valid Heroku PostgreSQL add-on attachments
+     * to generate a list of possible valid attachments when the user passes a database name that doesn't match any
+     * attachments.
+     *
+     * @param appId - The ID of the app to get the attachments for
+     * @returns Promise resolving to array of PostgreSQL add-on attachments
+     */
+    private allPostgresAttachments;
+    /**
+     * Returns the connection details for a database attachment according to the app config vars.
+     *
+     * @param attachment - The attachment to get the connection details for
+     * @param config - The record of app config vars with their values
+     * @returns Connection details with attachment information
+     */
+    private getConnectionDetails;
+    /**
+     * Helper function that attempts to find a single addon attachment matching the given database identifier
+     * (attachment name, id, or config var name).
+     *
+     * This is used internally by the `getAttachment` function to handle the lookup of addon attachments.
+     * It returns either a single match, multiple matches (for ambiguous cases), or null if no matches are found.
+     *
+     * The AddonAttachmentResolver uses the Platform API add-on attachment resolver endpoint to get the attachment.
+     *
+     * @param appId - The ID of the app to search for attachments
+     * @param attachmentId - The database identifier to match
+     * @param namespace - Optional namespace/credential filter
+     * @returns Promise resolving to either a single match, multiple matches with error, or no matches with error
+     */
+    private matchesHelper;
+}