@heroku/sdk 0.11.0 → 0.11.2

package/dist/core/extensions-proxy.js

@@ -1,5 +1,55 @@
 import createDebug from 'debug';
 const debug = createDebug('heroku:sdk:extensions');
+/**
+ * Re-derive the extension context so that an operation-wide cancellation set
+ * via `sdk.platform.withOptions({signal})` also reaches the clients its
+ * extensions issue requests through `ctx`.
+ *
+ * Extension factories close over `ctx.*` (e.g. `ctx.platform`) to issue their
+ * own — often nested, sometimes cross-service — requests. Without this, a signal
+ * set on a service client would reach generated route methods but never the
+ * requests an extension method makes through `ctx`, so cancellation could not
+ * stop the work an extension started. The derivation is applied to *every*
+ * service client in `ctx` because cancellation is operation-wide and extensions
+ * cross services (e.g. a `data` extension polls through `ctx.platform`).
+ *
+ * Only the operation-wide `signal` / `timeout` are propagated. A `withHeaders`
+ * call, and the `headers` / `body` fields of a `withOptions` call, are
+ * endpoint-specific and must not ride cross-service onto unrelated requests
+ * (e.g. an `Accept-Expansion` header a sibling endpoint rejects), so they stay
+ * on the routes client the caller scoped and are not re-derived here.
+ *
+ * `withOptions` returns a fresh client without mutating the original, and the
+ * derived clients are memoized per key, so sibling derived clients — and the
+ * base client — stay isolated from one another.
+ */
+function deriveCtx(ctx, method, args) {
+    if (method !== 'withOptions')
+        return ctx;
+    const options = args[0];
+    const scoped = {};
+    if (options?.signal !== undefined)
+        scoped.signal = options.signal;
+    if (options?.timeout !== undefined)
+        scoped.timeout = options.timeout;
+    if (Object.keys(scoped).length === 0)
+        return ctx;
+    const cache = new Map();
+    const derived = {};
+    for (const key of Object.keys(ctx)) {
+        Object.defineProperty(derived, key, {
+            enumerable: true,
+            get() {
+                if (!cache.has(key)) {
+                    const client = ctx[key];
+                    cache.set(key, typeof client?.withOptions === 'function' ? client.withOptions(scoped) : client);
+                }
+                return cache.get(key);
+            },
+        });
+    }
+    return derived;
+}
 export function mergeExtensions(client, extensions, ctx) {
     const methodsByResource = new Map();
     for (const ext of extensions) {
@@ -34,7 +84,7 @@ export function mergeExtensions(client, extensions, ctx) {
                 }
                 return (...args) => {
                     const rewrapped = inner.apply(target, args);
-                    return mergeExtensions(rewrapped, extensions, ctx);
+                    return mergeExtensions(rewrapped, extensions, deriveCtx(ctx, resourceKey, args));
                 };
             }
             const extMethods = methodsByResource.get(resourceKey);

package/dist/core/with-signal.d.ts

@@ -0,0 +1,19 @@
+import type { RoutesClientExtras } from './create-client.js';
+/**
+ * Bind a cancellation signal to a routes client so the requests it issues
+ * abort in flight.
+ *
+ * Extension methods receive their signal as a per-call option (e.g.
+ * `addOn.createAndWait(app, body, {signal})`) rather than through the client,
+ * so the signal reaches `wait()`/`throwIfAborted()` checkpoints but not the
+ * in-flight request unless it's pushed onto the client. This returns a derived,
+ * signal-bearing client (the original is never mutated) — or the client
+ * unchanged when no signal is supplied, so a signal-less call stays a no-op.
+ *
+ * Signals do not combine: `withOptions` is last-wins, so binding a per-call
+ * signal here replaces any signal already set on the client (e.g. a
+ * session-level one) for the requests this derived client issues. A caller that
+ * needs both to abort the request must combine them itself (e.g.
+ * `AbortSignal.any([sessionSignal, callSignal])`) before passing one in.
+ */
+export declare function withSignal<T>(client: RoutesClientExtras<T> & T, signal?: AbortSignal): RoutesClientExtras<T> & T;

package/dist/core/with-signal.js

@@ -0,0 +1,20 @@
+/**
+ * Bind a cancellation signal to a routes client so the requests it issues
+ * abort in flight.
+ *
+ * Extension methods receive their signal as a per-call option (e.g.
+ * `addOn.createAndWait(app, body, {signal})`) rather than through the client,
+ * so the signal reaches `wait()`/`throwIfAborted()` checkpoints but not the
+ * in-flight request unless it's pushed onto the client. This returns a derived,
+ * signal-bearing client (the original is never mutated) — or the client
+ * unchanged when no signal is supplied, so a signal-less call stays a no-op.
+ *
+ * Signals do not combine: `withOptions` is last-wins, so binding a per-call
+ * signal here replaces any signal already set on the client (e.g. a
+ * session-level one) for the requests this derived client issues. A caller that
+ * needs both to abort the request must combine them itself (e.g.
+ * `AbortSignal.any([sessionSignal, callSignal])`) before passing one in.
+ */
+export function withSignal(client, signal) {
+    return signal ? client.withOptions({ signal }) : client;
+}

package/dist/resources/data/database.js

@@ -1,34 +1,47 @@
 import { extendResource } from '../../core/extend-resource.js';
+import { withSignal } from '../../core/with-signal.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
 export async function describe(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.info(addon.id);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.info(addon.id);
 }
 export async function upgradeWaitStatus(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.upgradeWaitStatus(addon.id);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.upgradeWaitStatus(addon.id);
 }
 export async function dryRunUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.dryRunUpgrade(addon.id, body);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.dryRunUpgrade(addon.id, body);
 }
 export async function runUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.runUpgrade(addon.id, body);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.runUpgrade(addon.id, body);
 }
 export async function prepareUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.prepareUpgrade(addon.id, body);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.prepareUpgrade(addon.id, body);
 }
 export async function cancelUpgrade(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.database.cancelUpgrade(addon.id);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.database.cancelUpgrade(addon.id);
 }
 export const databaseExtensions = extendResource('data', 'database', ctx => ({
     cancelUpgrade: (appIdentity, addonIdentity, options) => cancelUpgrade(ctx, appIdentity, addonIdentity, options),

package/dist/resources/data/internal/postgres-utils.d.ts

@@ -1,11 +1,15 @@
 import type { AddOn } from '@heroku/types/3.sdk';
-import { ResourceCtx } from '../../../core/extend-resource.js';
-import { AddOnAttachmentWithInclusions } from '../../platform/add-on-attachment/resolve.js';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { AddOnAttachmentWithInclusions } from '../../platform/add-on-attachment/resolve.js';
 /**
- * Returns an arbitrary legacy database add-on based on the provided app name.
+ * Returns the first legacy database add-on on the app.
  */
-export declare function getArbitraryLegacyDB(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string): Promise<AddOn>;
-export declare const getAddonService: () => string;
-export declare const isPostgresAddon: (addon: AddOn | AddOnAttachmentWithInclusions["addon"]) => boolean;
+export declare function findLegacyDatabase(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string): Promise<AddOn>;
+export declare const getPostgresServiceName: () => string;
+/**
+ * `AddOnAttachmentWithInclusions` is an internal type. The public `isPostgresAddon` takes `AddOn` only.
+ */
+export declare const isPostgresAddonInternal: (addon: AddOn | AddOnAttachmentWithInclusions["addon"]) => boolean;
+export declare const isPostgresAddon: (addon: AddOn) => boolean;
 export declare const isAdvancedDatabase: (addon: AddOn) => boolean;
 export declare const isLegacyDatabase: (addon: AddOn) => boolean;

package/dist/resources/data/internal/postgres-utils.js

@@ -1,9 +1,9 @@
 import createDebug from 'debug';
-const debug = createDebug('postgres-utils');
+const debug = createDebug('heroku:sdk:resources:postgres-database');
 /**
- * Returns an arbitrary legacy database add-on based on the provided app name.
+ * Returns the first legacy database add-on on the app.
  */
-export async function getArbitraryLegacyDB(ctx, appIdentity) {
+export async function findLegacyDatabase(ctx, appIdentity) {
     debug(`fetching arbitrary legacy database on ${appIdentity}`);
     const addons = await ctx.platform.addOn.listByApp(appIdentity);
     const addon = addons.find(a => a.app.name === appIdentity && isLegacyDatabase(a));
@@ -11,7 +11,11 @@ export async function getArbitraryLegacyDB(ctx, appIdentity) {
         throw new Error(`No Heroku Postgres legacy database on ${appIdentity}`);
     return addon;
 }
-export const getAddonService = () => process.env.HEROKU_POSTGRESQL_ADDON_NAME || process.env.HEROKU_DATA_SERVICE || 'heroku-postgresql';
-export const isPostgresAddon = (addon) => addon.plan?.name?.split(':', 2)[0] === getAddonService();
-export const isAdvancedDatabase = (addon) => isPostgresAddon(addon) && /^(advanced|performance)/.test(addon.plan?.name?.split(':', 2)[1] ?? '');
-export const isLegacyDatabase = (addon) => isPostgresAddon(addon) && !isAdvancedDatabase(addon);
+export const getPostgresServiceName = () => process.env.HEROKU_POSTGRESQL_ADDON_NAME || process.env.HEROKU_DATA_SERVICE || 'heroku-postgresql';
+/**
+ * `AddOnAttachmentWithInclusions` is an internal type. The public `isPostgresAddon` takes `AddOn` only.
+ */
+export const isPostgresAddonInternal = (addon) => addon.plan?.name?.split(':', 2)[0] === getPostgresServiceName();
+export const isPostgresAddon = (addon) => isPostgresAddonInternal(addon);
+export const isAdvancedDatabase = (addon) => isPostgresAddonInternal(addon) && /^(advanced|performance)/.test(addon.plan?.name?.split(':', 2)[1] ?? '');
+export const isLegacyDatabase = (addon) => isPostgresAddonInternal(addon) && !isAdvancedDatabase(addon);

package/dist/resources/data/internal/resolve-pg-database.d.ts

@@ -10,57 +10,60 @@ export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
     input?: string;
 };
 /**
- * Thrown by `resolvePgDatabase` when the attachment resolution endpoint
- * does not find a match, the matched attachment is not the configured
- * Postgres service, or the app has no Postgres databases at all.
+ * Thrown by `resolvePgDatabase` when a database cannot be resolved: the app
+ * has no Postgres databases, the attachment is not found, or the matched
+ * attachment is not the configured Postgres service.
  */
 export declare class PgDatabaseNotFoundError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
+    readonly name = "PgDatabaseNotFoundError";
 }
 /**
  * Resolve a Heroku Postgres database add-on from an attachment identity.
  *
  * `input` selects the attachment as follows:
- *   - omitted → the `DATABASE_URL` attachment on `appIdentity`.
+ *   - omitted or `''` → the `DATABASE_URL` attachment on `appIdentity`.
  *   - `parent-app::attachment-or-config-var` (e.g. `my-app::DATABASE_URL`)
  *     → an attachment or config var on `parent-app`.
  *   - `parent-app::branch-name` (e.g. `my-app::my-branch`) → branch add-on
  *     name on `parent-app`.
- *   - Both `::` forms are handled the same way here: we split on the first
- *     `::` ourselves and send `app`/`addon` as separate fields, which
- *     works for either shape.
  *   - any other string (attachment name, config var, UUID, or
  *     globally-unique add-on name) → routed through `resolveAddonAttachment`,
  *     scoped to `appIdentity`.
  *
- * This function only uses the attachment resolver. To resolve a database
- * through the add-on resolve endpoint, call `resolveAddon` directly.
+ * This function intentionally relies on the attachment resolve endpoint. To
+ * resolve a database through the add-on resolve endpoint, call `resolveAddon`
+ * directly.
  *
  * The returned add-on is the identity nested on the attachment (`id`,
  * `name`, `app`, and the plan stub), not a full `ResolvedAddOn`. To get
  * that shape, call `resolveAddon` with the returned add-on's `id`.
  *
- * If the resolver finds multiple matches that all point at the same add-on
+ * A single resolver match is returned directly.
+ *
+ * If the resolver finds multiple matches that all point to the same add-on
  * (same `addon.id`/attachment `app.id`) and whose own `_URL` config var
  * resolves to the same value on the app, they're treated as equivalent
  * (e.g. the same database attached under two names) rather than ambiguous.
  *
+ * If the resolver finds no match at all, falls back to treating `input` as
+ * a literal config var name (adding a `_URL` suffix if missing) and looking
+ * for a Postgres attachment on the app whose own `_URL` config var resolves
+ * to the same value. This covers an app config var that is not one of the
+ * attachment's own config vars, but whose value is the same database URL.
+ *
  * Throws a `PgDatabaseNotFoundError` when the resolve endpoint 404s, the matched
  * attachment is not the configured Postgres service, or the app has no databases.
  * Throws an `AddonAttachmentAmbiguousError` when the remaining matches are not
  * the same database. Throws a plain `Error` if `appIdentity` is empty and `input`
  * has no `::`-prefixed app to fall back on.
  *
- * `resolvePgDatabase` should not throw a bare `NotFoundError`.
- * Extensions that use it typically couple it with a second data call
- * (e.g. `data.database.info(addon.id)`) that can also 404. Callers often
- * catch `NotFoundError` to handle that second call's failure specifically.
- * However, if a resolution failure surfaced as a `NotFoundError` too, that
- * catch would swallow it and mislabel it as the second call's failure instead.
- * Resolution failures are reported as `PgDatabaseNotFoundError` so the two stay
- * separable by type.
+ * `resolvePgDatabase` should not throw a bare `NotFoundError`. Extensions that
+ * use it typically couple it with a second data call (e.g. `data.database.info(addon.id)`)
+ * that can also 404. Callers often catch `NotFoundError` to handle that second
+ * call's failure specifically. However, if a resolution failure surfaced as a
+ * `NotFoundError` too, that catch would swallow it and mislabel it as the second
+ * call's failure instead. Resolution failures are reported as `PgDatabaseNotFoundError`
+ * so the two stay separable by type.
  */
 export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options: ResolvePgDatabaseOptions & {
     includeAttachment: true;

package/dist/resources/data/internal/resolve-pg-database.js

@@ -1,135 +1,198 @@
 import { NotFoundError } from '@heroku/heroku-fetch';
 import createDebug from 'debug';
+import { withSignal } from '../../../core/with-signal.js';
 import { AddonAttachmentAmbiguousError, AddonAttachmentNotFoundError, resolveAddonAttachment } from '../../platform/add-on-attachment/resolve.js';
-import { getAddonService, isPostgresAddon } from './postgres-utils.js';
+import { getPostgresServiceName, isPostgresAddonInternal } from './postgres-utils.js';
 const debug = createDebug('heroku:sdk:resources:database');
 const DEFAULT_PG_ATTACHMENT = 'DATABASE_URL';
 /**
- * Thrown by `resolvePgDatabase` when the attachment resolution endpoint
- * does not find a match, the matched attachment is not the configured
- * Postgres service, or the app has no Postgres databases at all.
+ * Thrown by `resolvePgDatabase` when a database cannot be resolved: the app
+ * has no Postgres databases, the attachment is not found, or the matched
+ * attachment is not the configured Postgres service.
  */
 export class PgDatabaseNotFoundError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = 'PgDatabaseNotFoundError';
-    }
+    name = 'PgDatabaseNotFoundError';
 }
 export async function resolvePgDatabase(ctx, appIdentity, options = {}) {
-    const { includeAttachment, input, ...rest } = options;
-    const databaseReference = input ?? DEFAULT_PG_ATTACHMENT;
-    const { addon, app } = databaseReference.includes('::')
-        ? parseBranchReference(databaseReference, appIdentity)
-        : { addon: databaseReference, app: appIdentity };
-    if (!app) {
+    const { includeAttachment, input, signal, ...rest } = options;
+    const databaseReference = input || DEFAULT_PG_ATTACHMENT;
+    const { app: parentApp, attachmentId } = parseDatabaseReference(databaseReference, appIdentity);
+    if (!parentApp) {
         throw new Error('resolvePgDatabase requires a non-empty app identity.');
     }
-    debug('resolve input=%s addon=%s app=%s', input ?? '<default>', addon, app);
+    debug('resolve input=%s attachment=%s app=%s', input ?? '<default>', attachmentId, parentApp);
     let attachment;
     try {
-        attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: getAddonService() });
+        attachment = await resolveAddonAttachment(ctx, parentApp, attachmentId, { ...rest, addonService: getPostgresServiceName(), signal });
     }
     catch (error) {
-        if (error instanceof NotFoundError || error instanceof AddonAttachmentNotFoundError) {
-            throw await buildDatabaseNotFoundError(ctx, app, addon, error, rest.signal);
-        }
-        if (error instanceof AddonAttachmentAmbiguousError) {
-            const equivalent = collapseIfEquivalent(error.matches);
-            if (!equivalent)
-                throw error;
-            let config;
-            try {
-                config = await ctx.platform
-                    .withOptions({ signal: rest.signal })
-                    .configVar.infoForApp(equivalent[0].app.name);
-            }
-            catch (configVarError) {
-                rest.signal?.throwIfAborted();
-                debug('config var lookup failed while collapsing ambiguous matches: %O', configVarError);
-                throw error;
-            }
-            if (!allMatchSameUrl(equivalent, config))
-                throw error;
-            attachment = equivalent[0];
+        attachment = await attachmentResolutionFallback(ctx, parentApp, attachmentId, error, signal);
+    }
+    return includeAttachment ? { addon: attachment.addon, attachment } : attachment.addon;
+}
+/**
+ * Fallback when `resolveAddonAttachment` throws. Returns an attachment when the failure
+ * can be recovered from:
+ *   - `NotFoundError` or `AddonAttachmentNotFoundError` → list the app's Postgres attachments.
+ *     An empty list throws `PgDatabaseNotFoundError`. Otherwise treat `attachmentId` as a config
+ *     var (adding `_URL` if missing) and keep every attachment whose own `_URL` value equals it.
+ *     Those matches already share one `_URL` value by construction, so only a same-add-on check
+ *     is needed before returning the first one. No matches, or matches that span more than one
+ *     add-on, throws `PgDatabaseNotFoundError`.
+ *   - `AddonAttachmentAmbiguousError` → collapse `error.matches` to one attachment via
+ *     `equivalentAttachment` when they're the same database (same add-on, same attachment app,
+ *     and the same non-empty `_URL` value fetched from the app's config vars). Otherwise rethrow.
+ *   - any other error → rethrow.
+ */
+async function attachmentResolutionFallback(ctx, appIdentity, attachmentId, error, signal) {
+    if (isAttachmentNotFoundError(error)) {
+        const attachments = await listPostgresAttachments(ctx, appIdentity, attachmentId, error, signal);
+        if (attachments.length === 0) {
+            throw new PgDatabaseNotFoundError(`${appIdentity} has no ${getPostgresServiceName()} databases`, { cause: error });
         }
-        else {
+        const resolutionError = buildDatabaseNotFoundError(appIdentity, attachmentId, attachments, error);
+        const matches = await resolveAttachmentViaConfigVarName(ctx, appIdentity, attachmentId, attachments, resolutionError, signal);
+        if (matches.length === 0 || !sameAddon(matches))
+            throw resolutionError;
+        return matches[0];
+    }
+    if (error instanceof AddonAttachmentAmbiguousError) {
+        const equivalent = await equivalentAttachment(ctx, error.matches, error, signal);
+        if (!equivalent)
             throw error;
-        }
+        return equivalent;
     }
-    return includeAttachment ? { addon: attachment.addon, attachment } : attachment.addon;
+    throw error;
+}
+/**
+ * Used by `attachmentResolutionFallback` to collapse ambiguous matches to the first
+ * attachment when all matches target the same database: same add-on, same attachment
+ * app, and the same non-empty `_URL` value. Returns `undefined` when the matches are
+ * not equivalent or the first match has no `_URL` value. `matches` must be non-empty.
+ */
+async function equivalentAttachment(ctx, matches, error, signal) {
+    const [first] = matches;
+    if (!sameAddon(matches))
+        return undefined;
+    const appConfig = await listAppConfigVars(ctx, first.app.name, error, signal);
+    const firstUrlValue = getUrlConfigVarValue(first, appConfig);
+    if (!firstUrlValue)
+        return undefined;
+    const sameDatabaseUrl = matches.every(match => getUrlConfigVarValue(match, appConfig) === firstUrlValue);
+    return sameDatabaseUrl ? first : undefined;
 }
-async function buildDatabaseNotFoundError(ctx, appIdentity, attachmentId, error, signal) {
+/**
+ * Used by `attachmentResolutionFallback` to list an app's config vars. An aborted
+ * signal throws the abort error. Any other listing failure throws `error` (the
+ * resolution error for this attempt).
+ */
+async function listAppConfigVars(ctx, appIdentity, error, signal) {
+    try {
+        return await withSignal(ctx.platform, signal)
+            .configVar.infoForApp(appIdentity);
+    }
+    catch (configVarError) {
+        signal?.throwIfAborted();
+        debug('config var lookup failed while attempting to resolve via fallback: %O', configVarError);
+        throw error;
+    }
+}
+/**
+ * Used by `attachmentResolutionFallback` to list all attachments on an app that match the
+ * add-on service filter. Throws `PgDatabaseNotFoundError` if the app does not exist
+ * or the listing fails for any other reason.
+ */
+async function listPostgresAttachments(ctx, appIdentity, attachmentId, error, signal) {
     let attachments;
     try {
-        attachments = await listPostgresAttachments(ctx, appIdentity, signal);
+        attachments = await withSignal(ctx.platform.withHeaders({ 'Accept-Inclusion': 'addon:plan,config_vars' }), signal).addOnAttachment.listByApp(appIdentity);
     }
     catch (listError) {
         signal?.throwIfAborted();
         if (listError instanceof NotFoundError) {
-            // `NotFoundError` from the attachment resolution endpoint is ambiguous.
-            // It could be because the app doesn't exist, or because the attachment
-            // doesn't exist. The endpoint for listing all attachments only 404s when
-            // the app doesn't exist, so we rethrow the error to cover that case.
+            // Listing attachments 404s only when the app does not exist, which would
+            // also be the reason for the attachment resolution failure. Therefore,
+            // we surface this error specifically.
             throw new PgDatabaseNotFoundError(`Couldn't find that app: ${appIdentity}`, { cause: listError });
         }
         debug('listing attachments failed while building not-found error: %O', listError);
         throw new PgDatabaseNotFoundError(`Could not resolve ${stripUrlSuffix(attachmentId)} on ${appIdentity}`, { cause: error });
     }
-    if (attachments.length === 0) {
-        return new PgDatabaseNotFoundError(`${appIdentity} has no ${getAddonService()} databases`, { cause: error });
-    }
+    return attachments.filter(attachment => isPostgresAddonInternal(attachment.addon));
+}
+/**
+ * Used by `attachmentResolutionFallback` to resolve attachments via app config vars
+ * when no matches were found. Treats `attachmentId` as a config var name and
+ * uses its value to filter the attachments. Returns an empty array if the
+ * config var value is not found.
+ */
+async function resolveAttachmentViaConfigVarName(ctx, appIdentity, attachmentId, attachments, error, signal) {
+    const appConfig = await listAppConfigVars(ctx, appIdentity, error, signal);
+    const inputConfigVarName = attachmentId.endsWith('_URL') ? attachmentId : `${attachmentId}_URL`;
+    const inputConfigVarValue = appConfig[inputConfigVarName];
+    if (!inputConfigVarValue)
+        return [];
+    return attachments.filter(attachment => getUrlConfigVarValue(attachment, appConfig) === inputConfigVarValue);
+}
+/**
+ * Builds a `PgDatabaseNotFoundError` when attachment resolution endpoint 404s (NotFoundError)
+ * or attachments did not match the add-on service filter (AddonAttachmentNotFoundError).
+ */
+function buildDatabaseNotFoundError(appIdentity, attachmentId, attachments, error) {
     const validOptions = attachments
         .map(attachment => {
-        const urlVarName = urlConfigVarName(attachment.config_vars);
+        const urlVarName = getUrlConfigVarName(attachment.config_vars);
         return urlVarName ? stripUrlSuffix(urlVarName) : attachment.name;
     })
         .join(', ');
     const databaseName = stripUrlSuffix(attachmentId);
     if (error instanceof AddonAttachmentNotFoundError) {
-        return new PgDatabaseNotFoundError(`${databaseName} is not a ${getAddonService()} database on ${appIdentity}. Valid options are: ${validOptions}`, { cause: error });
+        return new PgDatabaseNotFoundError(`${databaseName} is not a ${getPostgresServiceName()} database on ${appIdentity}. Valid options are: ${validOptions}`, { cause: error });
     }
     return new PgDatabaseNotFoundError(`Unknown database: ${databaseName} on ${appIdentity}. Valid options are: ${validOptions}`, { cause: error });
 }
-async function listPostgresAttachments(ctx, appIdentity, signal) {
-    const attachments = await ctx.platform
-        .withHeaders({ 'Accept-Inclusion': 'addon:plan,config_vars' })
-        .withOptions({ signal })
-        .addOnAttachment.listByApp(appIdentity);
-    return attachments.filter(attachment => isPostgresAddon(attachment.addon));
-}
-function stripUrlSuffix(name) {
-    return name.endsWith('_URL') ? name.slice(0, -4) : name;
-}
 /**
- * Narrows ambiguous matches to a same-add-on group worth comparing by
- * config var value. Returns `undefined` (not worth a config-vars round
- * trip) unless every match shares the same add-on and attachment app.
+ * Returns the first config var name declared on an attachment that holds its connection
+ * URL or `undefined` if no such config var is found.
  */
-function collapseIfEquivalent(matches) {
-    const [first] = matches;
-    const sameAddon = matches.every(match => match.addon.id === first.addon.id && match.app.id === first.app.id);
-    return sameAddon ? matches : undefined;
-}
-/** The first config var name declared on an attachment that holds its connection URL. */
-function urlConfigVarName(configVars) {
+function getUrlConfigVarName(configVars) {
     return configVars.find(name => name.endsWith('_URL'));
 }
-/** Whether every match's own URL config var resolves to the same value in `config`. */
-function allMatchSameUrl(matches, config) {
-    const firstVarName = urlConfigVarName(matches[0].config_vars);
-    const firstValue = firstVarName && config[firstVarName];
-    if (!firstValue) {
-        return false;
-    }
-    return matches.every(match => {
-        const varName = urlConfigVarName(match.config_vars);
-        return varName !== undefined && config[varName] === firstValue;
-    });
+/**
+ * Looks up the value of `attachment`'s own `_URL` config var in `appConfig`, or
+ * `undefined` if the attachment has no `_URL`-suffixed config var.
+ */
+function getUrlConfigVarValue(attachment, appConfig) {
+    const urlVarName = getUrlConfigVarName(attachment.config_vars);
+    return urlVarName ? appConfig[urlVarName] : undefined;
 }
-function parseBranchReference(reference, fallbackApp) {
+/**
+ * Returns true if `error` is a NotFoundError (attachment resolution endpoint 404) or
+ * AddonAttachmentNotFoundError (attachments did not match the add-on service filter).
+ */
+function isAttachmentNotFoundError(error) {
+    return error instanceof AddonAttachmentNotFoundError || error instanceof NotFoundError;
+}
+/**
+ * Splits an `app::database` reference into the app and the attachment id.
+ * A reference with no `::` uses `appIdentity` as the app and the whole
+ * reference as the attachment id.
+ */
+function parseDatabaseReference(reference, appIdentity) {
     const match = reference.match(/^(.+?)::(.+)$/);
     if (match) {
-        return { addon: match[2], app: match[1] };
+        return { app: match[1], attachmentId: match[2] };
     }
-    return { addon: reference, app: fallbackApp };
+    return { app: appIdentity, attachmentId: reference };
+}
+/** Whether every match shares the same add-on and attachment app. */
+function sameAddon(matches) {
+    const [first] = matches;
+    return matches.every(match => match.addon.id === first.addon.id && match.app.id === first.app.id);
+}
+/**
+ * Removes the `_URL` suffix from a config var name if it exists.
+ */
+function stripUrlSuffix(name) {
+    return name.endsWith('_URL') ? name.slice(0, -4) : name;
 }

package/dist/resources/data/maintenance.js

@@ -1,9 +1,12 @@
 import { extendResource } from '../../core/extend-resource.js';
+import { withSignal } from '../../core/with-signal.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
 export async function info(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.maintenance.info(addon.id);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.maintenance.info(addon.id);
 }
 export const maintenanceExtensions = extendResource('data', 'maintenance', ctx => ({
     info: (appIdentity, addonIdentity, options) => info(ctx, appIdentity, addonIdentity, options),

package/dist/resources/data/postgres-database.d.ts

@@ -20,3 +20,4 @@ export declare function listCredentials(ctx: Pick<ResourceCtx, 'data' | 'platfor
 export declare const postgresDatabaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresDatabase", {
     listCredentials: (appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions) => Promise<CredentialInfo[]>;
 }>;
+export { findLegacyDatabase, getPostgresServiceName, isAdvancedDatabase, isLegacyDatabase, isPostgresAddon, } from './internal/postgres-utils.js';

package/dist/resources/data/postgres-database.js

@@ -1,10 +1,14 @@
 import { extendResource } from '../../core/extend-resource.js';
+import { withSignal } from '../../core/with-signal.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
 export async function listCredentials(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
     const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
-    return ctx.data.postgresDatabase.listCredentials(addon.id);
+    // Bind the signal so the request aborts in flight, not just during resolution.
+    const data = withSignal(ctx.data, options.signal);
+    return data.postgresDatabase.listCredentials(addon.id);
 }
 export const postgresDatabaseExtensions = extendResource('data', 'postgresDatabase', ctx => ({
     listCredentials: (appIdentity, addonIdentity, options) => listCredentials(ctx, appIdentity, addonIdentity, options),
 }));
+export { findLegacyDatabase, getPostgresServiceName, isAdvancedDatabase, isLegacyDatabase, isPostgresAddon, } from './internal/postgres-utils.js';