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

package/dist/utils/pg/databases.js

@@ -1,128 +1,193 @@
 import { color } from '@heroku-cli/color';
 import { HerokuAPIError } from '@heroku-cli/command/lib/api-client.js';
 import debug from 'debug';
-import { env } from 'node:process';
-import { AmbiguousError } from '../../types/errors/ambiguous.js';
-import { appAttachment } from '../addons/resolve.js';
-import { bastionKeyPlan, fetchConfig, getBastion } from './bastion.js';
+import { AmbiguousError } from '../../errors/ambiguous.js';
+import AddonAttachmentResolver from '../addons/resolve.js';
+import { bastionKeyPlan, fetchBastionConfig, getBastionConfig } from './bastion.js';
 import { getConfig, getConfigVarName, getConfigVarNameFromAttachment } from './config-vars.js';
 const pgDebug = debug('pg');
-async function allAttachments(heroku, appId) {
-    const { body: attachments } = await heroku.get(`/apps/${appId}/addon-attachments`, {
-        headers: { 'Accept-Inclusion': 'addon:plan,config_vars' },
-    });
-    return attachments.filter((a) => a.addon.plan?.name?.startsWith('heroku-postgresql'));
-}
-export async function getAttachment(heroku, app, db = 'DATABASE_URL', namespace = '') {
-    const matchesOrError = await matchesHelper(heroku, app, db, namespace);
-    let { matches } = matchesOrError;
-    const { error } = matchesOrError;
-    // happy path where the resolver matches just one
-    if (matches && matches.length === 1) {
-        return matches[0];
+export default class DatabaseResolver {
+    heroku;
+    getConfigFn;
+    fetchBastionConfigFn;
+    addonAttachmentResolver;
+    attachmentHeaders = {
+        Accept: 'application/vnd.heroku+json; version=3.sdk',
+        'Accept-Inclusion': 'addon:plan,config_vars',
+    };
+    constructor(heroku, getConfigFn = getConfig, fetchBastionConfigFn = fetchBastionConfig) {
+        this.heroku = heroku;
+        this.getConfigFn = getConfigFn;
+        this.fetchBastionConfigFn = fetchBastionConfigFn;
+        this.addonAttachmentResolver = new AddonAttachmentResolver(this.heroku);
     }
-    // case for 404 where there are implicit attachments
-    if (!matches) {
-        const appConfigMatch = /^(.+?)::(.+)/.exec(db);
+    /**
+     * 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
+     */
+    async getAttachment(appId, attachmentId = 'DATABASE_URL', namespace) {
+        // handle the case where the user passes an app::database format, overriding any app name option values.
+        const appConfigMatch = /^(.+?)::(.+)/.exec(attachmentId);
         if (appConfigMatch) {
-            app = appConfigMatch[1];
-            db = appConfigMatch[2];
+            appId = appConfigMatch[1];
+            attachmentId = appConfigMatch[2];
         }
-        if (!db.endsWith('_URL')) {
-            db += '_URL';
+        const { error, matches } = await this.matchesHelper(appId, attachmentId, namespace);
+        // happy path where the resolver matches just one
+        if (matches && matches.length === 1) {
+            return matches[0];
         }
-        const [config = {}, attachments] = await Promise.all([
-            getConfig(heroku, app),
-            allAttachments(heroku, app),
-        ]);
-        if (attachments.length === 0) {
-            throw new Error(`${color.app(app)} has no databases`);
+        // handle the case where the resolver didn't find any matches for the given database and show valid options.
+        if (!matches) {
+            const attachments = await this.allPostgresAttachments(appId);
+            if (attachments.length === 0) {
+                throw new Error(`${color.app(appId)} has no databases`);
+            }
+            else {
+                const validOptions = attachments.map(attachment => getConfigVarName(attachment.config_vars));
+                throw new Error(`Unknown database: ${attachmentId}. Valid options are: ${validOptions.join(', ')}`);
+            }
         }
-        matches = attachments.filter(attachment => config[db] && config[db] === config[getConfigVarName(attachment.config_vars)]);
-        if (matches.length === 0) {
-            const validOptions = attachments.map(attachment => getConfigVarName(attachment.config_vars));
-            throw new Error(`Unknown database: ${db}. Valid options are: ${validOptions.join(', ')}`);
+        // handle the case where the resolver found multiple matches for the given database.
+        const first = matches[0];
+        // return the first attachment when all ambiguous attachments are equivalent (basically target the same database)
+        if (matches.every(match => first.addon.id === match.addon.id && first.app.id === match.app.id)) {
+            const config = await this.getConfigFn(this.heroku, first.app.name);
+            if (matches.every(match => config[getConfigVarName(first.config_vars)] === config[getConfigVarName(match.config_vars)])) {
+                return first;
+            }
         }
+        throw error;
     }
-    // case for multiple attachments with passedDb
-    const first = matches[0];
-    // case for 422 where there are ambiguous attachments that are equivalent
-    if (matches.every(match => first.addon?.id === match.addon?.id && first.app?.id === match.app?.id)) {
-        const config = await getConfig(heroku, first.app.name) ?? {};
-        if (matches.every(match => config[getConfigVarName(first.addon.config_vars)] === config[getConfigVarName(match.config_vars)])) {
-            return first;
+    /**
+     * 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
+     */
+    async getDatabase(appId, attachmentId, namespace) {
+        const attached = await this.getAttachment(appId, attachmentId, namespace);
+        const config = await this.getConfigFn(this.heroku, attached.app.name);
+        const database = this.getConnectionDetails(attached, config);
+        // Add bastion configuration if it's a non-shielded Private Space add-on and we still don't have the config.
+        if (bastionKeyPlan(attached) && !database.bastionKey) {
+            const bastionConfig = await this.fetchBastionConfigFn(this.heroku, attached.addon);
+            Object.assign(database, bastionConfig);
         }
+        return database;
     }
-    throw error;
-}
-export const getConnectionDetails = (attachment, configVars = {}) => {
-    const connStringVar = getConfigVarNameFromAttachment(attachment, configVars);
-    // remove _URL from the end of the config var name
-    const baseName = connStringVar.slice(0, -4);
-    // build the default payload for non-bastion dbs
-    pgDebug(`Using "${connStringVar}" to connect to your database…`);
-    const conn = parsePostgresConnectionString(configVars[connStringVar]);
-    const payload = {
-        attachment,
-        database: conn.database,
-        host: conn.host,
-        password: conn.password,
-        pathname: conn.pathname,
-        port: conn.port,
-        url: conn.url,
-        user: conn.user,
-    };
-    // If bastion creds exist, graft it into the payload
-    const bastion = getBastion(configVars, baseName);
-    if (bastion) {
-        Object.assign(payload, bastion);
+    /**
+     * 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) {
+        const dbPath = /:\/\//.test(connStringOrDbName) ? connStringOrDbName : `postgres:///${connStringOrDbName}`;
+        const url = new URL(dbPath);
+        const { hostname, password, pathname, port, username } = url;
+        return {
+            database: pathname.slice(1), // remove the leading slash from the pathname
+            host: hostname,
+            password,
+            pathname,
+            port: port || process.env.PGPORT || (hostname && '5432'),
+            url: dbPath,
+            user: username,
+        };
     }
-    return payload;
-};
-export async function getDatabase(heroku, app, db, namespace) {
-    const attached = await getAttachment(heroku, app, db, namespace);
-    // would inline this as well but in some cases attachment pulls down config
-    // as well, and we would request twice at the same time but I did not want
-    // to push this down into attachment because we do not always need config
-    const config = await getConfig(heroku, attached.app.name);
-    const database = getConnectionDetails(attached, config);
-    if (bastionKeyPlan(attached.addon) && !database.bastionKey) {
-        const { body: bastionConfig } = await fetchConfig(heroku, attached.addon);
-        const bastionHost = bastionConfig.host;
-        const bastionKey = bastionConfig.private_key;
-        Object.assign(database, { bastionHost, bastionKey });
+    /**
+     * 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
+     */
+    async allPostgresAttachments(appId) {
+        const addonService = process.env.HEROKU_POSTGRESQL_ADDON_NAME || 'heroku-postgresql';
+        const { body: attachments } = await this.heroku.get(`/apps/${appId}/addon-attachments`, {
+            headers: this.attachmentHeaders,
+        });
+        return attachments.filter(a => a.addon.plan.name.split(':', 2)[0] === addonService);
     }
-    return database;
-}
-async function matchesHelper(heroku, app, db, namespace) {
-    debug(`fetching ${db} on ${app}`);
-    const addonService = process.env.HEROKU_POSTGRESQL_ADDON_NAME || 'heroku-postgresql';
-    debug(`addon service: ${addonService}`);
-    try {
-        const attached = await appAttachment(heroku, app, db, { addon_service: addonService, namespace });
-        return ({ matches: [attached] });
+    /**
+     * 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
+     */
+    getConnectionDetails(attachment, config = {}) {
+        const connStringVar = getConfigVarNameFromAttachment(attachment, config);
+        // build the default payload for non-bastion dbs
+        pgDebug(`Using "${connStringVar}" to connect to your database…`);
+        const conn = this.parsePostgresConnectionString(config[connStringVar]);
+        const payload = {
+            attachment,
+            database: conn.database,
+            host: conn.host,
+            password: conn.password,
+            pathname: conn.pathname,
+            port: conn.port,
+            url: conn.url,
+            user: conn.user,
+        };
+        // This handles injection of bastion creds into the payload if they exist as config vars (Shield-tier databases).
+        const baseName = connStringVar.slice(0, -4);
+        const bastion = getBastionConfig(config, baseName);
+        if (bastion) {
+            Object.assign(payload, bastion);
+        }
+        return payload;
     }
-    catch (error) {
-        if (error instanceof AmbiguousError && error.body?.id === 'multiple_matches' && error.matches) {
-            return { error, matches: error.matches };
+    /**
+     * 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
+     */
+    async matchesHelper(appId, attachmentId, namespace) {
+        debug(`fetching ${attachmentId} on ${appId}`);
+        const addonService = process.env.HEROKU_POSTGRESQL_ADDON_NAME || 'heroku-postgresql';
+        debug(`addon service: ${addonService}`);
+        try {
+            const attached = await this.addonAttachmentResolver.resolve(appId, attachmentId, { addonService, namespace });
+            return { error: undefined, matches: [attached] };
         }
-        if (error instanceof HerokuAPIError && error.http.statusCode === 404 && error.body && error.body.id === 'not_found') {
-            return { error, matches: null };
+        catch (error) {
+            if (error instanceof AmbiguousError && error.body.id === 'multiple_matches' && error.matches) {
+                return { error, matches: error.matches };
+            }
+            // This handles the case where the resolver returns a 404 error when making the request, but not the case
+            // where it returns a NotFound error because there were no matches after filtering by namespace.
+            if (error instanceof HerokuAPIError
+                && error.http.statusCode === 404
+                && error.body && error.body.id === 'not_found') {
+                return { error, matches: null };
+            }
+            // This re-throws a NotFound error or any other HerokuAPIError except for the 404 case which is handled above.
+            throw error;
         }
-        throw error;
     }
 }
-export const parsePostgresConnectionString = (db) => {
-    const dbPath = /:\/\//.test(db) ? db : `postgres:///${db}`;
-    const url = new URL(dbPath);
-    const { hostname, password, pathname, port, username } = url;
-    return {
-        database: pathname.charAt(0) === '/' ? pathname.slice(1) : pathname,
-        host: hostname,
-        password,
-        pathname,
-        port: port || env.PGPORT || (hostname && '5432'),
-        url: dbPath,
-        user: username,
-    };
-};

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

@@ -1,28 +1,116 @@
-import { type ChildProcess, type SpawnOptions, type SpawnOptionsWithStdioTuple } from 'node:child_process';
-import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
 import { Server } from 'node:net';
-import { Stream } from 'node:stream';
-import { ConnectionDetails, TunnelConfig } from '../../types/pg/tunnel.js';
-export declare function consumeStream(inputStream: Stream): Promise<unknown>;
-export declare function exec(db: ConnectionDetails, query: string, cmdArgs?: string[]): Promise<string>;
-export declare function psqlQueryOptions(query: string, dbEnv: NodeJS.ProcessEnv, cmdArgs?: string[]): {
-    childProcessOptions: SpawnOptionsWithStdioTuple<"ignore", "pipe", "inherit">;
-    dbEnv: NodeJS.ProcessEnv;
-    psqlArgs: string[];
-};
-export declare function execPSQL({ childProcessOptions, dbEnv, psqlArgs }: {
-    childProcessOptions: SpawnOptions;
-    dbEnv: NodeJS.ProcessEnv;
-    psqlArgs: string[];
-}): ChildProcess;
-export declare function runWithTunnel(db: ConnectionDetails, tunnelConfig: TunnelConfig, options: Parameters<typeof execPSQL>[0]): Promise<string>;
-export declare const trapAndForwardSignalsToChildProcess: (childProcess: ChildProcess) => () => void;
-export declare function waitForPSQLExit(psql: EventEmitter): Promise<void>;
+import { ConnectionDetailsWithAttachment, TunnelConfig } from '../../types/pg/tunnel.js';
+import { getPsqlConfigs, sshTunnel } from './bastion.js';
+/**
+ * A small wrapper around tunnel-ssh so that other code doesn't have to worry about whether there is or is not a tunnel.
+ */
 export declare class Tunnel {
     private readonly bastionTunnel;
     private readonly events;
-    constructor(bastionTunnel: Server);
-    static connect(db: ConnectionDetails, tunnelConfig: TunnelConfig): Promise<Tunnel>;
+    /**
+     * Creates a new Tunnel instance.
+     *
+     * @param bastionTunnel - The SSH tunnel server or void if no tunnel is needed
+     */
+    constructor(bastionTunnel: Server | void);
+    /**
+     * Creates and connects to an SSH tunnel.
+     *
+     * @param connectionDetails - The database connection details with attachment information
+     * @param tunnelConfig - The tunnel configuration object
+     * @param tunnelFn - The function to create the SSH tunnel (default: sshTunnel)
+     * @returns Promise that resolves to a new Tunnel instance
+     */
+    static connect(connectionDetails: ConnectionDetailsWithAttachment, tunnelConfig: TunnelConfig, tunnelFn: typeof sshTunnel): Promise<Tunnel>;
+    /**
+     * Closes the tunnel if it exists, or emits a fake close event if no tunnel is needed.
+     *
+     * @returns void
+     */
     close(): void;
+    /**
+     * Waits for the tunnel to close.
+     *
+     * @returns Promise that resolves when the tunnel closes
+     * @throws Error if the secure tunnel fails
+     */
     waitForClose(): Promise<void>;
 }
+export default class PsqlService {
+    private readonly connectionDetails;
+    private readonly getPsqlConfigsFn;
+    private readonly spawnFn;
+    private readonly tunnelFn;
+    constructor(connectionDetails: ConnectionDetailsWithAttachment, getPsqlConfigsFn?: typeof getPsqlConfigs, spawnFn?: typeof spawn, tunnelFn?: typeof sshTunnel);
+    /**
+     * Executes a PostgreSQL query using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the query.
+     *
+     * @param query - The SQL query to execute
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    execQuery(query: string, psqlCmdArgs?: string[]): Promise<string>;
+    /**
+     * Consumes a stream and returns its content as a string.
+     *
+     * @param inputStream - The input stream to consume
+     * @returns Promise that resolves to the stream content as a string
+     */
+    private consumeStream;
+    /**
+     * Kills a child process if it hasn't been killed already.
+     * According to node.js docs, sending a kill to a process won't cause an error
+     * but could have unintended consequences if the PID gets reassigned.
+     * To be on the safe side, check if the process was already killed before sending the signal.
+     *
+     * @param childProcess - The child process to kill
+     * @param signal - The signal to send to the process
+     * @returns void
+     */
+    private kill;
+    /**
+     * Creates the options for spawning the psql process.
+     *
+     * @param query - The SQL query to execute
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
+     */
+    private psqlQueryOptions;
+    /**
+     * Runs the psql command with tunnel support.
+     *
+     * @param tunnelConfig - The tunnel configuration object
+     * @param options - The options for spawning the psql process
+     * @returns Promise that resolves to the query result as a string
+     */
+    private runWithTunnel;
+    /**
+     * Spawns the psql process with the given options.
+     *
+     * @param options - The options for spawning the psql process
+     * @returns The spawned child process
+     */
+    private spawnPsql;
+    /**
+     * Traps SIGINT so that ctrl+c can be used by psql without killing the parent node process.
+     * You can use ctrl+c in psql to kill running queries while keeping the psql process open.
+     * This code is to stop the parent node process (heroku CLI) from exiting.
+     * If the parent Heroku CLI node process exits, then psql will exit as it is a child process.
+     *
+     * @param childProcess - The child process to forward signals to
+     * @returns Function to restore the original signal handlers
+     */
+    private trapAndForwardSignalsToChildProcess;
+    /**
+     * Waits for the psql process to exit and handles any errors.
+     *
+     * @param psql - The psql process event emitter
+     * @throws Error if psql exits with non-zero code or if psql command is not found
+     * @returns Promise that resolves to void when psql exits
+     */
+    private waitForPSQLExit;
+}