graphile-presigned-url-plugin 1.11.3 → 1.12.0

package/default-bucket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+/**
+ * The resolved bucket coordinate.
+ *
+ * `physicalName` is the recorded S3 bucket name, or null when the logical
+ * bucket has never been provisioned — the caller mints and records it then.
+ */
+export interface ResolvedBucketCoordinate {
+    bucketId: string;
+    resolvedKey: string;
+    bucketType: 'public' | 'private' | 'temp';
+    physicalName: string | null;
+}
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export declare function resolveDefaultBucket(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, scope: string, entityId: string | null, publicAccess: boolean, bucketKey: string | null): Promise<ResolvedBucketCoordinate>;

package/default-bucket.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDefaultBucket = resolveDefaultBucket;
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('graphile-presigned-url:default-bucket');
+const RESOLVE_DEFAULT_BUCKET_QUERY = `
+  SELECT bucket_id, resolved_key, bucket_type, physical_name
+  FROM function_resolution.resolve_default_bucket($1, $2, $3, $4, $5)
+`;
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+async function resolveDefaultBucket(pgClient, databaseId, scope, entityId, publicAccess, bucketKey) {
+    const result = await pgClient.query({
+        text: RESOLVE_DEFAULT_BUCKET_QUERY,
+        values: [databaseId, scope, entityId, publicAccess, bucketKey],
+    });
+    const row = result.rows[0];
+    if (!row) {
+        // resolve_default_bucket raises on zero and on several matches, so an empty
+        // result means the function did not run as declared rather than "no bucket".
+        throw new Error(`STORAGE_DEFAULT_BUCKET_NO_ROW: resolve_default_bucket returned no row for ` +
+            `database=${databaseId} scope=${scope} public=${publicAccess} key=${bucketKey ?? '<default tag>'}`);
+    }
+    log.debug(`Resolved bucket ${row.resolved_key} (${row.bucket_type}) for database=${databaseId} scope=${scope}`);
+    return {
+        bucketId: row.bucket_id,
+        resolvedKey: row.resolved_key,
+        bucketType: row.bucket_type,
+        physicalName: row.physical_name,
+    };
+}

package/esm/default-bucket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+/**
+ * The resolved bucket coordinate.
+ *
+ * `physicalName` is the recorded S3 bucket name, or null when the logical
+ * bucket has never been provisioned — the caller mints and records it then.
+ */
+export interface ResolvedBucketCoordinate {
+    bucketId: string;
+    resolvedKey: string;
+    bucketType: 'public' | 'private' | 'temp';
+    physicalName: string | null;
+}
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export declare function resolveDefaultBucket(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, scope: string, entityId: string | null, publicAccess: boolean, bucketKey: string | null): Promise<ResolvedBucketCoordinate>;

package/esm/default-bucket.js

@@ -0,0 +1,48 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('graphile-presigned-url:default-bucket');
+const RESOLVE_DEFAULT_BUCKET_QUERY = `
+  SELECT bucket_id, resolved_key, bucket_type, physical_name
+  FROM function_resolution.resolve_default_bucket($1, $2, $3, $4, $5)
+`;
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export async function resolveDefaultBucket(pgClient, databaseId, scope, entityId, publicAccess, bucketKey) {
+    const result = await pgClient.query({
+        text: RESOLVE_DEFAULT_BUCKET_QUERY,
+        values: [databaseId, scope, entityId, publicAccess, bucketKey],
+    });
+    const row = result.rows[0];
+    if (!row) {
+        // resolve_default_bucket raises on zero and on several matches, so an empty
+        // result means the function did not run as declared rather than "no bucket".
+        throw new Error(`STORAGE_DEFAULT_BUCKET_NO_ROW: resolve_default_bucket returned no row for ` +
+            `database=${databaseId} scope=${scope} public=${publicAccess} key=${bucketKey ?? '<default tag>'}`);
+    }
+    log.debug(`Resolved bucket ${row.resolved_key} (${row.bucket_type}) for database=${databaseId} scope=${scope}`);
+    return {
+        bucketId: row.bucket_id,
+        resolvedKey: row.resolved_key,
+        bucketType: row.bucket_type,
+        physicalName: row.physical_name,
+    };
+}

package/esm/file-ref-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `file_ref_field` registry: which storage module and bucket a managed
+ * document column writes into.
+ *
+ * An `image`/`upload` column is a projection of a files row, and the decision of
+ * *where* those bytes live is a property of the field declaration, not of the
+ * request. The registry records that intent per (table, column) — a storage
+ * module plus either a logical bucket key, a tag selector, or nothing at all
+ * (meaning the reserved default tag for the declared publicness).
+ *
+ * This module answers one question — "what does a write to this column bind
+ * to?" — and answers it loudly: an unregistered column raises rather than
+ * falling back to a server-global bucket, because a silent fallback is how the
+ * unmanaged lane produced objects no tenant owned.
+ */
+/**
+ * A field's recorded storage intent.
+ *
+ * `bucketKey` and `bucketTags` are mutually exclusive by table constraint, and
+ * both may be absent — resolution then uses the reserved default tag for
+ * `isPublic`. Nothing here is a physical bucket name or id: the concrete bucket
+ * is resolved per written row, inside the tenant.
+ */
+export interface FileRefFieldBinding {
+    id: string;
+    storageModuleId: string;
+    bucketKey: string | null;
+    bucketTags: string[] | null;
+    isPublic: boolean | null;
+    enforceFk: boolean;
+}
+export declare class FileRefFieldNotRegisteredError extends Error {
+    readonly databaseId: string;
+    readonly schemaName: string;
+    readonly tableName: string;
+    readonly columnName: string;
+    constructor(databaseId: string, schemaName: string, tableName: string, columnName: string);
+}
+/**
+ * Look up the storage binding for a document column, or throw.
+ *
+ * The read runs on whichever client the caller passes. The registry is schema
+ * metadata rather than tenant rows, so callers resolve it in the system lane —
+ * the RLS that matters is on the files table the upload eventually writes.
+ */
+export declare function getFileRefFieldBinding(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, field: {
+    schemaName: string;
+    tableName: string;
+    columnName: string;
+}): Promise<FileRefFieldBinding>;
+/**
+ * Drop cached bindings. Used by tests and after a re-provision.
+ */
+export declare function clearFileRefFieldCache(): void;

package/esm/file-ref-registry.js

@@ -0,0 +1,115 @@
+/**
+ * The `file_ref_field` registry: which storage module and bucket a managed
+ * document column writes into.
+ *
+ * An `image`/`upload` column is a projection of a files row, and the decision of
+ * *where* those bytes live is a property of the field declaration, not of the
+ * request. The registry records that intent per (table, column) — a storage
+ * module plus either a logical bucket key, a tag selector, or nothing at all
+ * (meaning the reserved default tag for the declared publicness).
+ *
+ * This module answers one question — "what does a write to this column bind
+ * to?" — and answers it loudly: an unregistered column raises rather than
+ * falling back to a server-global bucket, because a silent fallback is how the
+ * unmanaged lane produced objects no tenant owned.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { LRUCache } from 'lru-cache';
+const log = new Logger('graphile-presigned-url:file-ref-registry');
+const FIVE_MINUTES_MS = 1000 * 60 * 5;
+const ONE_HOUR_MS = 1000 * 60 * 60;
+/**
+ * Resolve the registry row for a document column.
+ *
+ * Joined through metaschema rather than keyed by name, because the registry
+ * records field *ids*: the physical (schema, table, column) triple is what the
+ * GraphQL layer knows, and metaschema is the only thing that maps one to the
+ * other.
+ */
+const FILE_REF_FIELD_QUERY = `
+  SELECT
+    frf.id,
+    frf.storage_module_id,
+    frf.bucket_key,
+    frf.bucket_tags::text[] AS bucket_tags,
+    frf.is_public,
+    frf.enforce_fk
+  FROM metaschema_modules_public.file_ref_field frf
+  JOIN metaschema_public.field f ON f.id = frf.field_id
+  JOIN metaschema_public.table t ON t.id = frf.table_id
+  JOIN metaschema_public.schema s ON s.id = t.schema_id
+  WHERE frf.database_id = $1
+    AND s.schema_name = $2
+    AND t.name = $3
+    AND f.name = $4
+  LIMIT 1
+`;
+/**
+ * LRU cache of field bindings.
+ *
+ * A binding is schema, not data: it changes only when a database is
+ * re-provisioned, so it caches on the same terms as the storage module config
+ * next to it. Misses are never cached — an unregistered column is a hard error
+ * every time it is written, not a remembered "no".
+ */
+const bindingCache = new LRUCache({
+    max: 500,
+    ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
+    updateAgeOnGet: true,
+});
+export class FileRefFieldNotRegisteredError extends Error {
+    databaseId;
+    schemaName;
+    tableName;
+    columnName;
+    constructor(databaseId, schemaName, tableName, columnName) {
+        super(`FILE_REF_FIELD_NOT_REGISTERED: ${schemaName}.${tableName}.${columnName} ` +
+            `is not a registered file-reference field in database ${databaseId}. ` +
+            'A managed upload needs the declared storage module and bucket intent; ' +
+            'there is no server-global bucket to fall back to.');
+        this.databaseId = databaseId;
+        this.schemaName = schemaName;
+        this.tableName = tableName;
+        this.columnName = columnName;
+        this.name = 'FileRefFieldNotRegisteredError';
+    }
+}
+/**
+ * Look up the storage binding for a document column, or throw.
+ *
+ * The read runs on whichever client the caller passes. The registry is schema
+ * metadata rather than tenant rows, so callers resolve it in the system lane —
+ * the RLS that matters is on the files table the upload eventually writes.
+ */
+export async function getFileRefFieldBinding(pgClient, databaseId, field) {
+    const cacheKey = `file-ref:${databaseId}:${field.schemaName}.${field.tableName}.${field.columnName}`;
+    const cached = bindingCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const result = await pgClient.query({
+        text: FILE_REF_FIELD_QUERY,
+        values: [databaseId, field.schemaName, field.tableName, field.columnName],
+    });
+    if (result.rows.length === 0) {
+        throw new FileRefFieldNotRegisteredError(databaseId, field.schemaName, field.tableName, field.columnName);
+    }
+    const row = result.rows[0];
+    const binding = {
+        id: row.id,
+        storageModuleId: row.storage_module_id,
+        bucketKey: row.bucket_key,
+        bucketTags: row.bucket_tags,
+        isPublic: row.is_public,
+        enforceFk: row.enforce_fk,
+    };
+    bindingCache.set(cacheKey, binding);
+    log.debug(`Bound ${field.schemaName}.${field.tableName}.${field.columnName} to storage module ` +
+        `${binding.storageModuleId} (bucket_key=${binding.bucketKey ?? '<default tag>'})`);
+    return binding;
+}
+/**
+ * Drop cached bindings. Used by tests and after a re-provision.
+ */
+export function clearFileRefFieldCache() {
+    bindingCache.clear();
+}

package/esm/index.d.ts

@@ -26,9 +26,16 @@
  * };
  * ```
  */
+export type { ResolvedBucketCoordinate } from './default-bucket';
+export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
+export type { FileRefFieldBinding } from './file-ref-registry';
+export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
+export { assertUploadAllowedByBucket, buildFileProjection, type FileProjection, finalizeStagedUpload, type ManagedUploadTarget, resolveManagedUploadTarget, } from './managed-upload';
+export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
-export { deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject } from './s3-signer';
+export { type WithPgClient, withRequestPgClient } from './request-pg-client';
+export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, getStorageModuleConfig, getStorageModuleConfigForOwner, 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

@@ -26,8 +26,13 @@
  * };
  * ```
  */
+export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
+export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
+export { assertUploadAllowedByBucket, buildFileProjection, finalizeStagedUpload, resolveManagedUploadTarget, } from './managed-upload';
+export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
-export { deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject } from './s3-signer';
+export { withRequestPgClient } from './request-pg-client';
+export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, getStorageModuleConfig, getStorageModuleConfigForOwner, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';

package/esm/managed-upload.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The managed upload lifecycle, shared by both transports.
+ *
+ * Multipart-through-GraphQL and presigned two-step are transports for one
+ * lifecycle, not two data models: either way an object gets a files row, a
+ * server-chosen key, a tenant-resolved bucket, and a projection document that
+ * carries the files row's id. The only difference is who moves the bytes.
+ *
+ * This module owns the parts that are the same:
+ *   * `resolveManagedUploadTarget` — from a document column to a concrete
+ *     (storage module, bucket, physical bucket, S3 config).
+ *   * `finalizeStagedUpload` — from bytes already in S3 under a staging key to a
+ *     files row and a projection document, deduplicating on content hash.
+ *   * `buildFileProjection` — the document shape the column stores.
+ *
+ * Nothing here bakes a presigned URL into a row: `url` is populated only for a
+ * public bucket, where it is a stable CDN address rather than a credential with
+ * an expiry.
+ */
+import { type FileRefFieldBinding } from './file-ref-registry';
+import { type WithPgClient } from './request-pg-client';
+import type { BucketConfig, FileProjection, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+/**
+ * The document a managed `image`/`upload` column stores.
+ *
+ * `id` is the files row — the load-bearing field: it is what makes the column a
+ * projection rather than a second, unmanaged copy of the truth, and it is what
+ * storage GC counts before collecting an object.
+ *
+ * `url` is retained for existing readers of the pre-managed shape and is set
+ * only for public buckets. Prefer `id` plus the files row's `downloadUrl`, which
+ * is late-bound and works for private buckets too.
+ */
+export type { FileProjection } from './types';
+/**
+ * Build the projection document for a files row.
+ *
+ * A public bucket has a stable address, so `url` is a real, durable value there.
+ * A private bucket has no such address — only presigned, expiring ones — so the
+ * field is omitted rather than filled with a URL that dies in an hour.
+ */
+export declare function buildFileProjection(file: {
+    id: string;
+    key: string;
+    bucketId: string;
+    mime: string;
+    size: number;
+    filename?: string | null;
+}, bucket: {
+    is_public: boolean;
+}, s3: S3Config): FileProjection;
+/**
+ * Everything a managed upload needs before bytes move.
+ */
+export interface ManagedUploadTarget {
+    databaseId: string;
+    storageConfig: StorageModuleConfig;
+    bucket: BucketConfig;
+    physicalName: string;
+    s3: S3Config;
+    /** The registry row, or null when the column predates registration. */
+    binding: FileRefFieldBinding | null;
+}
+/**
+ * Resolve where a write to a document column lands.
+ *
+ * Two routes, one rule — the bucket is always resolved inside the tenant:
+ *   * 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.
+ *
+ * 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.
+ */
+export declare function resolveManagedUploadTarget(args: {
+    options: PresignedUrlPluginOptions;
+    withPgClient: WithPgClient;
+    pgSettings: Record<string, string> | null;
+    databaseId: string;
+    field: {
+        schemaName: string;
+        tableName: string;
+        columnName: string;
+    };
+    /** Publicness to use when the column is unregistered. */
+    defaultPublicAccess: boolean;
+}): Promise<ManagedUploadTarget>;
+/**
+ * Validate an upload against the resolved bucket's rules.
+ *
+ * The same rules the presigned lane enforces — a transport must not be a way
+ * around a bucket's mime allowlist or size cap.
+ */
+export declare function assertUploadAllowedByBucket(target: ManagedUploadTarget, contentType: string, size: number): void;
+/**
+ * Turn bytes already staged in S3 into a files row and a projection document.
+ *
+ * The content hash is only known once the stream has been read, so a streaming
+ * transport writes to a staging key first and promotes here:
+ *
+ *   * hash already present in this bucket → drop the staged object, reuse the
+ *     existing files row. Dedup is a property of the object, so it holds no
+ *     matter which transport wrote it first.
+ *   * otherwise → server-side copy to the content-addressed key, drop the staged
+ *     object, insert the files row.
+ *
+ * The row is inserted *after* the bytes land, so the confirm-upload job the
+ * insert trigger enqueues finds the object and completes the
+ * `requested → uploaded` transition without any extra wiring here.
+ *
+ * Every failure path leaves S3 as it found it. Bytes written by this call and
+ * not reachable through a files row would be invisible to storage GC, which
+ * collects objects by walking rows — so an object is only left behind once the
+ * row naming it exists.
+ */
+export declare function finalizeStagedUpload(args: {
+    target: ManagedUploadTarget;
+    withPgClient: WithPgClient;
+    pgSettings: Record<string, string> | null;
+    staged: {
+        stagingKey: string;
+        contentHash: string;
+        contentType: string;
+        size: number;
+        filename?: string | null;
+    };
+}): Promise<{
+    projection: FileProjection;
+    deduplicated: boolean;
+}>;