@heroku/heroku-cli-util 10.0.0-beta.2 → 10.0.0

package/dist/utils/pg/bastion.js

@@ -1,17 +1,95 @@
-import { ux } from '@oclif/core';
 import debug from 'debug';
-import * as EventEmitter from 'node:events';
+import { EventEmitter } from 'node:events';
 import { promisify } from 'node:util';
 import * as createTunnel from 'tunnel-ssh';
 import host from './host.js';
 const pgDebug = debug('pg');
-export const bastionKeyPlan = (a) => Boolean(/private/.test(a.addon.plan.name));
-export const env = (db) => {
-    const baseEnv = {
-        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
+ */
+export 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
+ */
+export async function fetchBastionConfig(heroku, addon) {
+    const { body: bastionConfig } = await heroku.get(`/client/v11/databases/${encodeURIComponent(addon.id)}/bastion`, { hostname: host() });
+    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
+ */
+export 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 {};
+};
+/**
+ * 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
+ */
+export 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',
@@ -19,52 +97,53 @@ export const env = (db) => {
         PGPORT: 'port',
         PGUSER: 'user',
     };
+    const baseEnv = {
+        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;
-};
-export async function fetchConfig(heroku, db) {
-    return heroku.get(`/client/v11/databases/${encodeURIComponent(db.id)}/bastion`, {
-        hostname: host(),
-    });
 }
-export 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 } : {};
-};
-export function getConfigs(db) {
-    const dbEnv = 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() * (65_535 - 49_152)) + 49_152);
     return {
-        dbEnv,
-        dbTunnelConfig,
+        dstHost: connectionDetails.host,
+        dstPort: Number.parseInt(connectionDetails.port, 10),
+        host: connectionDetails.bastionHost,
+        localHost,
+        localPort,
+        privateKey: connectionDetails.bastionKey,
+        username: 'bastion',
     };
 }
-export async function sshTunnel(db, dbTunnelConfig, timeout = 10_000) {
-    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
+ */
+export async function sshTunnel(connectionDetails, dbTunnelConfig, timeout = 10_000, createSSHTunnel = promisify(createTunnel.default)) {
+    if (!connectionDetails.bastionKey) {
+        return;
     }
     const timeoutInstance = new Timeout(timeout, 'Establishing a secure tunnel timed out');
-    const createSSHTunnel = promisify(createTunnel.default);
     try {
         return await Promise.race([
             timeoutInstance.promise(),
@@ -73,44 +152,50 @@ export async function sshTunnel(db, dbTunnelConfig, timeout = 10_000) {
     }
     catch (error) {
         pgDebug(error);
-        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();
     }
 }
-export function tunnelConfig(db) {
-    const localHost = '127.0.0.1';
-    const localPort = Math.floor((Math.random() * (65_535 - 49_152)) + 49_152);
-    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 {
-    events = new EventEmitter.EventEmitter();
+    // eslint-disable-next-line unicorn/prefer-event-target
+    events = new EventEmitter();
     message;
     timeout;
     timer;
+    /**
+     * 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) {
         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 new Promise(resolve => {
+            await new Promise((resolve, reject) => {
                 this.events.once('cancelled', () => resolve());
+                this.events.once('timeout', () => reject(new Error(this.message)));
             });
         }
         finally {

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.js';
-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.js';
+/**
+ * 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,28 +1,62 @@
 import { color } from '@heroku-cli/color';
-import { ux } from '@oclif/core';
-const responseByAppId = new Map();
-export 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.
+ */
+export const 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
+ */
+export async function getConfig(heroku, appId) {
+    let promise = configVarsByAppIdCache.get(appId);
+    if (!promise) {
+        promise = heroku.get(`/apps/${appId}/config-vars`);
+        configVarsByAppIdCache.set(appId, promise);
     }
-    const result = await responseByAppId.get(app);
-    return result?.body;
+    const { body: config } = await promise;
+    return config;
 }
-export 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'
+ */
+export 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
+ */
 export function getConfigVarNameFromAttachment(attachment, config = {}) {
-    const configVars = attachment.addon.config_vars?.filter((cv) => config[cv]?.startsWith('postgres://')) ?? [];
-    if (configVars.length === 0) {
-        ux.error(`No config vars found for ${attachment.name}; perhaps they were removed as a side effect of ${color.cmd('heroku rollback')}? Use ${color.cmd('heroku addons:attach')} to create a new attachment and then ${color.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 => config[cvn]?.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.cmd('heroku rollback')}? Use ${color.cmd('heroku addons:attach')} to create a new attachment and `
+            + `then ${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.js';
+import type { ExtendedAddonAttachment } from '../../types/pg/data-api.js';
 import type { ConnectionDetails, ConnectionDetailsWithAttachment } from '../../types/pg/tunnel.js';
-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.js';
+import { getConfig } from './config-vars.js';
+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;
+}