npm - graphile-presigned-url-plugin - Versions diffs - 1.15.0 → 1.16.0 - Mend

graphile-presigned-url-plugin 1.15.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/esm/index.d.ts CHANGED Viewed

@@ -38,6 +38,7 @@ export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, re
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
+export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
 export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';

package/esm/index.js CHANGED Viewed

@@ -36,5 +36,6 @@ export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, re
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { withRequestPgClient } from './request-pg-client';
+export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';

package/esm/managed-upload.d.ts CHANGED Viewed

@@ -68,11 +68,19 @@ export interface ManagedUploadTarget {
  *   * a registered column names its storage module, and either a logical bucket
  *     key or the reserved default tag for its declared publicness;
  *   * an unregistered column (a bare `image`/`upload` on a database provisioned
- *     before the registry) falls back to the app-scope module and the same
- *     reserved default tag. That is a *tenant* default, not an environment one.
+ *     before the registry) falls back to the database's single global storage
+ *     plane and the same reserved default tag. That is a *tenant* default, not
+ *     an environment one.
  *
- * A database with no storage module raises: there is nowhere tenant-owned to put
- * the bytes, and the deployment's configured bucket is not an answer.
+ * The fallback is by shape, not by scope name: a global plane is one with no
+ * entity key (`entity_table_id IS NULL`), which is what a database-wide plane is
+ * whether it registered as 'database', 'platform', or 'app'. Matching the name
+ * instead sent every tenant whose plane registers as 'database' — i.e. every
+ * database-scope plane — to STORAGE_MODULE_NOT_FOUND.
+ *
+ * A database with no global plane raises, and so does one with several: there is
+ * nowhere unambiguously tenant-owned to put the bytes, and the deployment's
+ * configured bucket is not an answer.
  */
 export declare function resolveManagedUploadTarget(args: {
     options: PresignedUrlPluginOptions;

package/esm/managed-upload.js CHANGED Viewed

@@ -55,11 +55,19 @@ export function buildFileProjection(file, bucket, s3) {
  *   * a registered column names its storage module, and either a logical bucket
  *     key or the reserved default tag for its declared publicness;
  *   * an unregistered column (a bare `image`/`upload` on a database provisioned
- *     before the registry) falls back to the app-scope module and the same
- *     reserved default tag. That is a *tenant* default, not an environment one.
+ *     before the registry) falls back to the database's single global storage
+ *     plane and the same reserved default tag. That is a *tenant* default, not
+ *     an environment one.
  *
- * A database with no storage module raises: there is nowhere tenant-owned to put
- * the bytes, and the deployment's configured bucket is not an answer.
+ * The fallback is by shape, not by scope name: a global plane is one with no
+ * entity key (`entity_table_id IS NULL`), which is what a database-wide plane is
+ * whether it registered as 'database', 'platform', or 'app'. Matching the name
+ * instead sent every tenant whose plane registers as 'database' — i.e. every
+ * database-scope plane — to STORAGE_MODULE_NOT_FOUND.
+ *
+ * A database with no global plane raises, and so does one with several: there is
+ * nowhere unambiguously tenant-owned to put the bytes, and the deployment's
+ * configured bucket is not an answer.
  */
 export async function resolveManagedUploadTarget(args) {
     const { options, withPgClient, pgSettings, databaseId, field, defaultPublicAccess } = args;
@@ -71,7 +79,7 @@ export async function resolveManagedUploadTarget(args) {
         }
         catch (err) {
             // An unregistered column is a legitimate state (it predates the registry)
-            // and falls back to the tenant's app-scope default below. Any other
+            // and falls back to the tenant's global plane below. Any other
             // failure — a broken connection, a missing registry table — is not.
             if (err?.name === 'FileRefFieldNotRegisteredError')
                 return null;
@@ -79,15 +87,24 @@ export async function resolveManagedUploadTarget(args) {
         }
     });
     const allConfigs = await withPgClient(null, (pgClient) => loadAllStorageModules(pgClient, databaseId));
+    const globalConfigs = allConfigs.filter((c) => c.entityTableId === null);
+    if (!binding && globalConfigs.length > 1) {
+        // Several global planes and no registry row to disambiguate: picking one is
+        // picking a tenant's bucket at random. Name them and refuse.
+        throw new Error(`STORAGE_MODULE_AMBIGUOUS: ${field.schemaName}.${field.tableName}.${field.columnName} is an ` +
+            `unregistered upload column and database ${databaseId} has ${globalConfigs.length} global ` +
+            `storage planes (scopes: ${globalConfigs.map((c) => c.scope).join(', ')}); register the column ` +
+            'so it names the plane it writes to');
+    }
     const storageConfig = binding
         ? allConfigs.find((c) => c.id === binding.storageModuleId)
-        : allConfigs.find((c) => c.scope === 'app');
+        : globalConfigs[0];
     if (!storageConfig) {
         throw new Error(binding
             ? `STORAGE_MODULE_NOT_FOUND: file_ref_field ${binding.id} names storage module ` +
                 `${binding.storageModuleId}, which database ${databaseId} does not have`
             : `STORAGE_MODULE_NOT_FOUND: ${field.schemaName}.${field.tableName}.${field.columnName} is an ` +
-                `unregistered upload column and database ${databaseId} has no app-scope storage module to ` +
+                `unregistered upload column and database ${databaseId} has no global storage plane to ` +
                 'default to; there is no environment bucket to fall back to');
     }
     if (storageConfig.entityTableId !== null) {

package/esm/physical-bucket.js CHANGED Viewed

@@ -10,6 +10,7 @@
  */
 import { Logger } from '@pgpmjs/logger';
 import { withRequestPgClient } from './request-pg-client';
+import { s3FailureError } from './s3-failure';
 import { isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:physical-bucket');
 /**
@@ -91,7 +92,15 @@ export async function provisionAndRecordPhysicalBucket(options, withPgClient, st
     const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
     if (options.ensureBucketProvisioned && !isS3BucketProvisioned(s3BucketName)) {
         log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        try {
+            await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        }
+        catch (err) {
+            // The first upload to a bucket is where an unreachable object store is
+            // discovered, and the transport's own message is routinely empty: name the
+            // endpoint it could not reach so the response says what is misconfigured.
+            throw s3FailureError('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
+        }
         markS3BucketProvisioned(s3BucketName);
         log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
     }

package/esm/s3-failure.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/**
+ * Turning an S3 transport failure into a reason a caller can act on.
+ *
+ * The AWS SDK routinely fails with an **empty** `message`: an unreachable
+ * endpoint arrives as an `AggregateError` whose own message is `''` and whose
+ * per-address `errors` hold the `ECONNREFUSED`, and a hung socket arrives as a
+ * bare wrapper around its `cause`. Anything that reports `err.message` verbatim
+ * therefore hands the client a blank reason — which is how a server signing
+ * against the wrong endpoint (a missing `CDN_ENDPOINT`, so the library default
+ * `http://localhost:9000`, i.e. the pod's own loopback) presents as an upload
+ * that fails with nothing to diagnose.
+ *
+ * So a failure is described by walking to where the words actually are, and
+ * re-thrown naming the coordinates it was talking to, with the original kept as
+ * `cause` for the server log.
+ */
+/**
+ * Describe a thrown S3 error in one line, including the nested errors an
+ * `AggregateError` (or a `cause` chain) hides its actual reason in.
+ */
+export declare function describeS3Failure(err: unknown, depth?: number): string;
+/**
+ * Wrap a failed S3 call as an error whose message carries the operation, the
+ * coordinates it used, and the underlying reason — with the original as `cause`.
+ *
+ * `context` is rendered as `key=value` pairs in the order given; entries with no
+ * value are dropped, so a connection without an explicit endpoint (real AWS)
+ * does not print an empty one.
+ */
+export declare function s3FailureError(operation: string, context: Record<string, string | number | undefined | null>, err: unknown): Error;

package/esm/s3-failure.js ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * Turning an S3 transport failure into a reason a caller can act on.
+ *
+ * The AWS SDK routinely fails with an **empty** `message`: an unreachable
+ * endpoint arrives as an `AggregateError` whose own message is `''` and whose
+ * per-address `errors` hold the `ECONNREFUSED`, and a hung socket arrives as a
+ * bare wrapper around its `cause`. Anything that reports `err.message` verbatim
+ * therefore hands the client a blank reason — which is how a server signing
+ * against the wrong endpoint (a missing `CDN_ENDPOINT`, so the library default
+ * `http://localhost:9000`, i.e. the pod's own loopback) presents as an upload
+ * that fails with nothing to diagnose.
+ *
+ * So a failure is described by walking to where the words actually are, and
+ * re-thrown naming the coordinates it was talking to, with the original kept as
+ * `cause` for the server log.
+ */
+/** How far to walk `errors` / `cause` before the chain stops being informative. */
+const MAX_DEPTH = 4;
+/**
+ * Describe a thrown S3 error in one line, including the nested errors an
+ * `AggregateError` (or a `cause` chain) hides its actual reason in.
+ */
+export function describeS3Failure(err, depth = 0) {
+    if (err === null || err === undefined)
+        return 'unknown error';
+    if (typeof err !== 'object')
+        return String(err);
+    const e = err;
+    const name = typeof e.name === 'string' && e.name !== 'Error' ? e.name : '';
+    const message = typeof e.message === 'string' ? e.message : '';
+    const head = message.length > 0 ? [name, message].filter(Boolean).join(': ') : name;
+    const status = e.$metadata?.httpStatusCode ? `HTTP ${e.$metadata.httpStatusCode}` : '';
+    let detail = '';
+    if (depth < MAX_DEPTH) {
+        const nested = Array.isArray(e.errors) ? e.errors : e.cause !== undefined ? [e.cause] : [];
+        const described = nested
+            .map((inner) => describeS3Failure(inner, depth + 1))
+            .filter((text) => text.length > 0 && text !== 'unknown error');
+        if (described.length > 0)
+            detail = `(${described.join('; ')})`;
+    }
+    const described = [head, status, detail].filter((part) => part.length > 0).join(' ');
+    return described.length > 0 ? described : 'unknown error';
+}
+/**
+ * Wrap a failed S3 call as an error whose message carries the operation, the
+ * coordinates it used, and the underlying reason — with the original as `cause`.
+ *
+ * `context` is rendered as `key=value` pairs in the order given; entries with no
+ * value are dropped, so a connection without an explicit endpoint (real AWS)
+ * does not print an empty one.
+ */
+export function s3FailureError(operation, context, err) {
+    const coordinates = Object.entries(context)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([key, value]) => `${key}=${value}`)
+        .join(' ');
+    const prefix = coordinates.length > 0 ? `${operation}: ${coordinates}` : operation;
+    return new Error(`${prefix}: ${describeS3Failure(err)}`, { cause: err });
+}

package/esm/s3-signer.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { Logger } from '@pgpmjs/logger';
+import { s3FailureError } from './s3-failure';
 const log = new Logger('graphile-presigned-url:s3');
 /**
  * Generate a presigned PUT URL for uploading a file to S3.
@@ -23,7 +24,13 @@ export async function generatePresignedPutUrl(s3Config, key, contentType, conten
         ContentType: contentType,
         ContentLength: contentLength,
     });
-    const url = await getSignedUrl(s3Config.client, command, { expiresIn });
+    let url;
+    try {
+        url = await getSignedUrl(s3Config.client, command, { expiresIn });
+    }
+    catch (err) {
+        throw s3FailureError('PRESIGN_PUT_FAILED', { endpoint: s3Config.endpoint, bucket: s3Config.bucket, key, contentType }, err);
+    }
     log.debug(`Generated presigned PUT URL for key=${key}, contentType=${contentType}, expires=${expiresIn}s`);
     return url;
 }
@@ -49,7 +56,13 @@ export async function generatePresignedGetUrl(s3Config, key, expiresIn = 3600, f
         params.ResponseContentDisposition = `attachment; filename="${sanitized}"`;
     }
     const command = new GetObjectCommand(params);
-    const url = await getSignedUrl(s3Config.client, command, { expiresIn });
+    let url;
+    try {
+        url = await getSignedUrl(s3Config.client, command, { expiresIn });
+    }
+    catch (err) {
+        throw s3FailureError('PRESIGN_GET_FAILED', { endpoint: s3Config.endpoint, bucket: s3Config.bucket, key }, err);
+    }
     log.debug(`Generated presigned GET URL for key=${key}, expires=${expiresIn}s`);
     return url;
 }

package/index.d.ts CHANGED Viewed

@@ -38,6 +38,7 @@ export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, re
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
+export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
 export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';

package/index.js CHANGED Viewed

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
+exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.s3FailureError = exports.describeS3Failure = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
 var confirm_upload_1 = require("./confirm-upload");
 Object.defineProperty(exports, "CONFIRM_PREFIX_BYTES", { enumerable: true, get: function () { return confirm_upload_1.CONFIRM_PREFIX_BYTES; } });
 Object.defineProperty(exports, "confirmUploadedBytes", { enumerable: true, get: function () { return confirm_upload_1.confirmUploadedBytes; } });
@@ -59,6 +59,9 @@ var preset_1 = require("./preset");
 Object.defineProperty(exports, "PresignedUrlPreset", { enumerable: true, get: function () { return preset_1.PresignedUrlPreset; } });
 var request_pg_client_1 = require("./request-pg-client");
 Object.defineProperty(exports, "withRequestPgClient", { enumerable: true, get: function () { return request_pg_client_1.withRequestPgClient; } });
+var s3_failure_1 = require("./s3-failure");
+Object.defineProperty(exports, "describeS3Failure", { enumerable: true, get: function () { return s3_failure_1.describeS3Failure; } });
+Object.defineProperty(exports, "s3FailureError", { enumerable: true, get: function () { return s3_failure_1.s3FailureError; } });
 var s3_signer_1 = require("./s3-signer");
 Object.defineProperty(exports, "copyS3Object", { enumerable: true, get: function () { return s3_signer_1.copyS3Object; } });
 Object.defineProperty(exports, "deleteS3Object", { enumerable: true, get: function () { return s3_signer_1.deleteS3Object; } });

package/managed-upload.d.ts CHANGED Viewed

@@ -68,11 +68,19 @@ export interface ManagedUploadTarget {
  *   * a registered column names its storage module, and either a logical bucket
  *     key or the reserved default tag for its declared publicness;
  *   * an unregistered column (a bare `image`/`upload` on a database provisioned
- *     before the registry) falls back to the app-scope module and the same
- *     reserved default tag. That is a *tenant* default, not an environment one.
+ *     before the registry) falls back to the database's single global storage
+ *     plane and the same reserved default tag. That is a *tenant* default, not
+ *     an environment one.
  *
- * A database with no storage module raises: there is nowhere tenant-owned to put
- * the bytes, and the deployment's configured bucket is not an answer.
+ * The fallback is by shape, not by scope name: a global plane is one with no
+ * entity key (`entity_table_id IS NULL`), which is what a database-wide plane is
+ * whether it registered as 'database', 'platform', or 'app'. Matching the name
+ * instead sent every tenant whose plane registers as 'database' — i.e. every
+ * database-scope plane — to STORAGE_MODULE_NOT_FOUND.
+ *
+ * A database with no global plane raises, and so does one with several: there is
+ * nowhere unambiguously tenant-owned to put the bytes, and the deployment's
+ * configured bucket is not an answer.
  */
 export declare function resolveManagedUploadTarget(args: {
     options: PresignedUrlPluginOptions;

package/managed-upload.js CHANGED Viewed

@@ -61,11 +61,19 @@ function buildFileProjection(file, bucket, s3) {
  *   * a registered column names its storage module, and either a logical bucket
  *     key or the reserved default tag for its declared publicness;
  *   * an unregistered column (a bare `image`/`upload` on a database provisioned
- *     before the registry) falls back to the app-scope module and the same
- *     reserved default tag. That is a *tenant* default, not an environment one.
+ *     before the registry) falls back to the database's single global storage
+ *     plane and the same reserved default tag. That is a *tenant* default, not
+ *     an environment one.
  *
- * A database with no storage module raises: there is nowhere tenant-owned to put
- * the bytes, and the deployment's configured bucket is not an answer.
+ * The fallback is by shape, not by scope name: a global plane is one with no
+ * entity key (`entity_table_id IS NULL`), which is what a database-wide plane is
+ * whether it registered as 'database', 'platform', or 'app'. Matching the name
+ * instead sent every tenant whose plane registers as 'database' — i.e. every
+ * database-scope plane — to STORAGE_MODULE_NOT_FOUND.
+ *
+ * A database with no global plane raises, and so does one with several: there is
+ * nowhere unambiguously tenant-owned to put the bytes, and the deployment's
+ * configured bucket is not an answer.
  */
 async function resolveManagedUploadTarget(args) {
     const { options, withPgClient, pgSettings, databaseId, field, defaultPublicAccess } = args;
@@ -77,7 +85,7 @@ async function resolveManagedUploadTarget(args) {
         }
         catch (err) {
             // An unregistered column is a legitimate state (it predates the registry)
-            // and falls back to the tenant's app-scope default below. Any other
+            // and falls back to the tenant's global plane below. Any other
             // failure — a broken connection, a missing registry table — is not.
             if (err?.name === 'FileRefFieldNotRegisteredError')
                 return null;
@@ -85,15 +93,24 @@ async function resolveManagedUploadTarget(args) {
         }
     });
     const allConfigs = await withPgClient(null, (pgClient) => (0, storage_module_cache_1.loadAllStorageModules)(pgClient, databaseId));
+    const globalConfigs = allConfigs.filter((c) => c.entityTableId === null);
+    if (!binding && globalConfigs.length > 1) {
+        // Several global planes and no registry row to disambiguate: picking one is
+        // picking a tenant's bucket at random. Name them and refuse.
+        throw new Error(`STORAGE_MODULE_AMBIGUOUS: ${field.schemaName}.${field.tableName}.${field.columnName} is an ` +
+            `unregistered upload column and database ${databaseId} has ${globalConfigs.length} global ` +
+            `storage planes (scopes: ${globalConfigs.map((c) => c.scope).join(', ')}); register the column ` +
+            'so it names the plane it writes to');
+    }
     const storageConfig = binding
         ? allConfigs.find((c) => c.id === binding.storageModuleId)
-        : allConfigs.find((c) => c.scope === 'app');
+        : globalConfigs[0];
     if (!storageConfig) {
         throw new Error(binding
             ? `STORAGE_MODULE_NOT_FOUND: file_ref_field ${binding.id} names storage module ` +
                 `${binding.storageModuleId}, which database ${databaseId} does not have`
             : `STORAGE_MODULE_NOT_FOUND: ${field.schemaName}.${field.tableName}.${field.columnName} is an ` +
-                `unregistered upload column and database ${databaseId} has no app-scope storage module to ` +
+                `unregistered upload column and database ${databaseId} has no global storage plane to ` +
                 'default to; there is no environment bucket to fall back to');
     }
     if (storageConfig.entityTableId !== null) {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl mutation and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -62,5 +62,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "d10fe91ede80a4c2dfe2c1c6dcf6fe7193784eba"
+  "gitHead": "df6b6613c844b505813e5d02d3a4afd918b74eab"
 }

package/physical-bucket.js CHANGED Viewed

@@ -16,6 +16,7 @@ exports.resolveS3ForDatabase = resolveS3ForDatabase;
 exports.provisionAndRecordPhysicalBucket = provisionAndRecordPhysicalBucket;
 const logger_1 = require("@pgpmjs/logger");
 const request_pg_client_1 = require("./request-pg-client");
+const s3_failure_1 = require("./s3-failure");
 const storage_module_cache_1 = require("./storage-module-cache");
 const log = new logger_1.Logger('graphile-presigned-url:physical-bucket');
 /**
@@ -97,7 +98,15 @@ async function provisionAndRecordPhysicalBucket(options, withPgClient, storageCo
     const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
     if (options.ensureBucketProvisioned && !(0, storage_module_cache_1.isS3BucketProvisioned)(s3BucketName)) {
         log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        try {
+            await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        }
+        catch (err) {
+            // The first upload to a bucket is where an unreachable object store is
+            // discovered, and the transport's own message is routinely empty: name the
+            // endpoint it could not reach so the response says what is misconfigured.
+            throw (0, s3_failure_1.s3FailureError)('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
+        }
         (0, storage_module_cache_1.markS3BucketProvisioned)(s3BucketName);
         log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
     }

package/s3-failure.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/**
+ * Turning an S3 transport failure into a reason a caller can act on.
+ *
+ * The AWS SDK routinely fails with an **empty** `message`: an unreachable
+ * endpoint arrives as an `AggregateError` whose own message is `''` and whose
+ * per-address `errors` hold the `ECONNREFUSED`, and a hung socket arrives as a
+ * bare wrapper around its `cause`. Anything that reports `err.message` verbatim
+ * therefore hands the client a blank reason — which is how a server signing
+ * against the wrong endpoint (a missing `CDN_ENDPOINT`, so the library default
+ * `http://localhost:9000`, i.e. the pod's own loopback) presents as an upload
+ * that fails with nothing to diagnose.
+ *
+ * So a failure is described by walking to where the words actually are, and
+ * re-thrown naming the coordinates it was talking to, with the original kept as
+ * `cause` for the server log.
+ */
+/**
+ * Describe a thrown S3 error in one line, including the nested errors an
+ * `AggregateError` (or a `cause` chain) hides its actual reason in.
+ */
+export declare function describeS3Failure(err: unknown, depth?: number): string;
+/**
+ * Wrap a failed S3 call as an error whose message carries the operation, the
+ * coordinates it used, and the underlying reason — with the original as `cause`.
+ *
+ * `context` is rendered as `key=value` pairs in the order given; entries with no
+ * value are dropped, so a connection without an explicit endpoint (real AWS)
+ * does not print an empty one.
+ */
+export declare function s3FailureError(operation: string, context: Record<string, string | number | undefined | null>, err: unknown): Error;

package/s3-failure.js ADDED Viewed

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Turning an S3 transport failure into a reason a caller can act on.
+ *
+ * The AWS SDK routinely fails with an **empty** `message`: an unreachable
+ * endpoint arrives as an `AggregateError` whose own message is `''` and whose
+ * per-address `errors` hold the `ECONNREFUSED`, and a hung socket arrives as a
+ * bare wrapper around its `cause`. Anything that reports `err.message` verbatim
+ * therefore hands the client a blank reason — which is how a server signing
+ * against the wrong endpoint (a missing `CDN_ENDPOINT`, so the library default
+ * `http://localhost:9000`, i.e. the pod's own loopback) presents as an upload
+ * that fails with nothing to diagnose.
+ *
+ * So a failure is described by walking to where the words actually are, and
+ * re-thrown naming the coordinates it was talking to, with the original kept as
+ * `cause` for the server log.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeS3Failure = describeS3Failure;
+exports.s3FailureError = s3FailureError;
+/** How far to walk `errors` / `cause` before the chain stops being informative. */
+const MAX_DEPTH = 4;
+/**
+ * Describe a thrown S3 error in one line, including the nested errors an
+ * `AggregateError` (or a `cause` chain) hides its actual reason in.
+ */
+function describeS3Failure(err, depth = 0) {
+    if (err === null || err === undefined)
+        return 'unknown error';
+    if (typeof err !== 'object')
+        return String(err);
+    const e = err;
+    const name = typeof e.name === 'string' && e.name !== 'Error' ? e.name : '';
+    const message = typeof e.message === 'string' ? e.message : '';
+    const head = message.length > 0 ? [name, message].filter(Boolean).join(': ') : name;
+    const status = e.$metadata?.httpStatusCode ? `HTTP ${e.$metadata.httpStatusCode}` : '';
+    let detail = '';
+    if (depth < MAX_DEPTH) {
+        const nested = Array.isArray(e.errors) ? e.errors : e.cause !== undefined ? [e.cause] : [];
+        const described = nested
+            .map((inner) => describeS3Failure(inner, depth + 1))
+            .filter((text) => text.length > 0 && text !== 'unknown error');
+        if (described.length > 0)
+            detail = `(${described.join('; ')})`;
+    }
+    const described = [head, status, detail].filter((part) => part.length > 0).join(' ');
+    return described.length > 0 ? described : 'unknown error';
+}
+/**
+ * Wrap a failed S3 call as an error whose message carries the operation, the
+ * coordinates it used, and the underlying reason — with the original as `cause`.
+ *
+ * `context` is rendered as `key=value` pairs in the order given; entries with no
+ * value are dropped, so a connection without an explicit endpoint (real AWS)
+ * does not print an empty one.
+ */
+function s3FailureError(operation, context, err) {
+    const coordinates = Object.entries(context)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([key, value]) => `${key}=${value}`)
+        .join(' ');
+    const prefix = coordinates.length > 0 ? `${operation}: ${coordinates}` : operation;
+    return new Error(`${prefix}: ${describeS3Failure(err)}`, { cause: err });
+}

package/s3-signer.js CHANGED Viewed

@@ -9,6 +9,7 @@ exports.headObject = headObject;
 const client_s3_1 = require("@aws-sdk/client-s3");
 const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
 const logger_1 = require("@pgpmjs/logger");
+const s3_failure_1 = require("./s3-failure");
 const log = new logger_1.Logger('graphile-presigned-url:s3');
 /**
  * Generate a presigned PUT URL for uploading a file to S3.
@@ -31,7 +32,13 @@ async function generatePresignedPutUrl(s3Config, key, contentType, contentLength
         ContentType: contentType,
         ContentLength: contentLength,
     });
-    const url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    let url;
+    try {
+        url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    }
+    catch (err) {
+        throw (0, s3_failure_1.s3FailureError)('PRESIGN_PUT_FAILED', { endpoint: s3Config.endpoint, bucket: s3Config.bucket, key, contentType }, err);
+    }
     log.debug(`Generated presigned PUT URL for key=${key}, contentType=${contentType}, expires=${expiresIn}s`);
     return url;
 }
@@ -57,7 +64,13 @@ async function generatePresignedGetUrl(s3Config, key, expiresIn = 3600, filename
         params.ResponseContentDisposition = `attachment; filename="${sanitized}"`;
     }
     const command = new client_s3_1.GetObjectCommand(params);
-    const url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    let url;
+    try {
+        url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    }
+    catch (err) {
+        throw (0, s3_failure_1.s3FailureError)('PRESIGN_GET_FAILED', { endpoint: s3Config.endpoint, bucket: s3Config.bucket, key }, err);
+    }
     log.debug(`Generated presigned GET URL for key=${key}, expires=${expiresIn}s`);
     return url;
 }