graphile-presigned-url-plugin 0.2.0

package/esm/storage-module-cache.js

@@ -0,0 +1,180 @@
+import { Logger } from '@pgpmjs/logger';
+import { LRUCache } from 'lru-cache';
+const log = new Logger('graphile-presigned-url:cache');
+// --- Defaults ---
+const DEFAULT_UPLOAD_URL_EXPIRY_SECONDS = 900; // 15 minutes
+const DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS = 3600; // 1 hour
+const DEFAULT_MAX_FILE_SIZE = 200 * 1024 * 1024; // 200MB
+const DEFAULT_MAX_FILENAME_LENGTH = 1024;
+const DEFAULT_CACHE_TTL_SECONDS = process.env.NODE_ENV === 'development' ? 300 : 3600;
+const FIVE_MINUTES_MS = 1000 * 60 * 5;
+const ONE_HOUR_MS = 1000 * 60 * 60;
+/**
+ * LRU cache for per-database StorageModuleConfig.
+ *
+ * Each PostGraphile instance serves a single database, but the presigned URL
+ * plugin needs to know the generated table names (buckets, files,
+ * upload_requests) and their schemas. This cache avoids re-querying metaschema
+ * on every request.
+ *
+ * Pattern: same as graphile-cache's LRU with TTL-based eviction.
+ */
+const storageModuleCache = new LRUCache({
+    max: 50,
+    ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
+    updateAgeOnGet: true,
+});
+/**
+ * SQL query to resolve storage module config for a database.
+ *
+ * Joins storage_module → table → schema to get fully-qualified table names.
+ */
+const STORAGE_MODULE_QUERY = `
+  SELECT
+    sm.id,
+    bs.schema_name AS buckets_schema,
+    bt.name AS buckets_table,
+    fs.schema_name AS files_schema,
+    ft.name AS files_table,
+    urs.schema_name AS upload_requests_schema,
+    urt.name AS upload_requests_table,
+    sm.upload_url_expiry_seconds,
+    sm.download_url_expiry_seconds,
+    sm.default_max_file_size,
+    sm.max_filename_length,
+    sm.cache_ttl_seconds
+  FROM metaschema_modules_public.storage_module sm
+  JOIN metaschema_public.table bt ON bt.id = sm.buckets_table_id
+  JOIN metaschema_public.schema bs ON bs.id = bt.schema_id
+  JOIN metaschema_public.table ft ON ft.id = sm.files_table_id
+  JOIN metaschema_public.schema fs ON fs.id = ft.schema_id
+  JOIN metaschema_public.table urt ON urt.id = sm.upload_requests_table_id
+  JOIN metaschema_public.schema urs ON urs.id = urt.schema_id
+  WHERE sm.database_id = $1
+  LIMIT 1
+`;
+/**
+ * Resolve the storage module config for a database, using the LRU cache.
+ *
+ * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
+ * @param databaseId - The metaschema database UUID
+ * @returns StorageModuleConfig or null if no storage module is provisioned
+ */
+export async function getStorageModuleConfig(pgClient, databaseId) {
+    const cacheKey = `storage:${databaseId}`;
+    const cached = storageModuleCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    log.debug(`Cache miss for database ${databaseId}, querying metaschema...`);
+    const result = await pgClient.query(STORAGE_MODULE_QUERY, [databaseId]);
+    if (result.rows.length === 0) {
+        log.warn(`No storage module found for database ${databaseId}`);
+        return null;
+    }
+    const row = result.rows[0];
+    const cacheTtlSeconds = row.cache_ttl_seconds ?? DEFAULT_CACHE_TTL_SECONDS;
+    const config = {
+        id: row.id,
+        bucketsQualifiedName: `"${row.buckets_schema}"."${row.buckets_table}"`,
+        filesQualifiedName: `"${row.files_schema}"."${row.files_table}"`,
+        uploadRequestsQualifiedName: `"${row.upload_requests_schema}"."${row.upload_requests_table}"`,
+        schemaName: row.buckets_schema,
+        bucketsTableName: row.buckets_table,
+        filesTableName: row.files_table,
+        uploadRequestsTableName: row.upload_requests_table,
+        uploadUrlExpirySeconds: row.upload_url_expiry_seconds ?? DEFAULT_UPLOAD_URL_EXPIRY_SECONDS,
+        downloadUrlExpirySeconds: row.download_url_expiry_seconds ?? DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS,
+        defaultMaxFileSize: row.default_max_file_size ?? DEFAULT_MAX_FILE_SIZE,
+        maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
+        cacheTtlSeconds,
+    };
+    storageModuleCache.set(cacheKey, config);
+    log.debug(`Cached storage config for database ${databaseId}: ${config.bucketsQualifiedName}`);
+    return config;
+}
+// --- Bucket metadata cache ---
+/**
+ * LRU cache for per-database bucket metadata.
+ *
+ * Buckets are essentially static config — created once and rarely changed.
+ * Caching avoids a DB query on every requestUploadUrl call. The bucket
+ * lookup in the plugin runs under RLS, but since AuthzEntityMembership
+ * grants all org members access to all org buckets, and the cached data
+ * is just config (mime types, size limits), bypassing RLS on cache hits
+ * is safe. The important RLS is on the files table (INSERT/UPDATE),
+ * which is never cached.
+ *
+ * Keys: `bucket:${databaseId}:${bucketKey}`
+ * TTL: same as storage module cache (5min dev / 1hr prod)
+ */
+const bucketCache = new LRUCache({
+    max: 500, // many buckets across many databases
+    ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
+    updateAgeOnGet: true,
+});
+/**
+ * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
+ *
+ * On cache miss, queries the bucket table (RLS-enforced via pgSettings on
+ * the pgClient). On cache hit, returns the cached metadata directly.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param storageConfig - The resolved StorageModuleConfig for this database
+ * @param databaseId - The metaschema database UUID (used as cache key prefix)
+ * @param bucketKey - The bucket key (e.g., "public", "private")
+ * @returns BucketConfig or null if the bucket doesn't exist / isn't accessible
+ */
+export async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
+    const cacheKey = `bucket:${databaseId}:${bucketKey}`;
+    const cached = bucketCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}, querying DB...`);
+    const result = await pgClient.query(`SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size
+     FROM ${storageConfig.bucketsQualifiedName}
+     WHERE key = $1
+     LIMIT 1`, [bucketKey]);
+    if (result.rows.length === 0) {
+        return null;
+    }
+    const row = result.rows[0];
+    const config = {
+        id: row.id,
+        key: row.key,
+        type: row.type,
+        is_public: row.is_public,
+        owner_id: row.owner_id,
+        allowed_mime_types: row.allowed_mime_types,
+        max_file_size: row.max_file_size,
+    };
+    bucketCache.set(cacheKey, config);
+    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id})`);
+    return config;
+}
+/**
+ * Clear the storage module cache AND bucket cache.
+ * Useful for testing or schema changes.
+ */
+export function clearStorageModuleCache() {
+    storageModuleCache.clear();
+    bucketCache.clear();
+}
+/**
+ * Clear cached bucket entries for a specific database.
+ * Useful when bucket config changes are detected.
+ */
+export function clearBucketCache(databaseId) {
+    if (!databaseId) {
+        bucketCache.clear();
+        return;
+    }
+    // Evict all entries for this database
+    const prefix = `bucket:${databaseId}:`;
+    for (const key of bucketCache.keys()) {
+        if (key.startsWith(prefix)) {
+            bucketCache.delete(key);
+        }
+    }
+}

package/esm/types.d.ts

@@ -0,0 +1,116 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Per-bucket configuration resolved from the storage_module tables.
+ */
+export interface BucketConfig {
+    id: string;
+    key: string;
+    type: 'public' | 'private' | 'temp';
+    is_public: boolean;
+    owner_id: string;
+    allowed_mime_types: string[] | null;
+    max_file_size: number | null;
+}
+/**
+ * Storage module configuration resolved from metaschema for a given database.
+ */
+export interface StorageModuleConfig {
+    /** The metaschema storage_module row ID */
+    id: string;
+    /** Resolved schema.table for buckets */
+    bucketsQualifiedName: string;
+    /** Resolved schema.table for files */
+    filesQualifiedName: string;
+    /** Resolved schema.table for upload_requests */
+    uploadRequestsQualifiedName: string;
+    /** Schema name (e.g., "app_public") */
+    schemaName: string;
+    /** Buckets table name */
+    bucketsTableName: string;
+    /** Files table name */
+    filesTableName: string;
+    /** Upload requests table name */
+    uploadRequestsTableName: string;
+    /** Presigned PUT URL expiry in seconds (default: 900 = 15 min) */
+    uploadUrlExpirySeconds: number;
+    /** Presigned GET URL expiry in seconds (default: 3600 = 1 hour) */
+    downloadUrlExpirySeconds: number;
+    /** Default max file size in bytes (default: 200MB). Bucket-level max_file_size overrides this. */
+    defaultMaxFileSize: number;
+    /** Max filename length in characters (default: 1024) */
+    maxFilenameLength: number;
+    /** Cache TTL in seconds for this config entry (default: 300 dev / 3600 prod) */
+    cacheTtlSeconds: number;
+}
+/**
+ * Input for the requestUploadUrl mutation.
+ */
+export interface RequestUploadUrlInput {
+    /** Bucket key (e.g., "public", "private") */
+    bucketKey: string;
+    /** SHA-256 content hash computed by the client */
+    contentHash: string;
+    /** MIME type of the file */
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+    /** Original filename (optional, for display/Content-Disposition) */
+    filename?: string;
+}
+/**
+ * Result of the requestUploadUrl mutation.
+ */
+export interface RequestUploadUrlPayload {
+    /** Presigned PUT URL (null if deduplicated) */
+    uploadUrl: string | null;
+    /** The file ID (existing if dedup, new if fresh upload) */
+    fileId: string;
+    /** The S3 key */
+    key: string;
+    /** Whether this file was deduplicated (already exists with same hash) */
+    deduplicated: boolean;
+    /** Presigned URL expiry time (null if deduplicated) */
+    expiresAt: string | null;
+}
+/**
+ * Input for the confirmUpload mutation.
+ */
+export interface ConfirmUploadInput {
+    /** The file ID returned by requestUploadUrl */
+    fileId: string;
+}
+/**
+ * Result of the confirmUpload mutation.
+ */
+export interface ConfirmUploadPayload {
+    /** The confirmed file ID */
+    fileId: string;
+    /** New file status (should be 'ready') */
+    status: string;
+    /** Whether confirmation succeeded */
+    success: boolean;
+}
+/**
+ * S3 configuration for the presigned URL plugin.
+ */
+export interface S3Config {
+    /** S3 client instance */
+    client: S3Client;
+    /** S3 bucket name (the actual S3 bucket, not the logical bucket key) */
+    bucket: string;
+    /** S3 endpoint URL (for MinIO/custom S3) */
+    endpoint?: string;
+    /** S3 region */
+    region?: string;
+    /** Whether to use path-style URLs (required for MinIO) */
+    forcePathStyle?: boolean;
+    /** Public URL prefix for generating download URLs */
+    publicUrlPrefix?: string;
+}
+/**
+ * Plugin options for the presigned URL plugin.
+ */
+export interface PresignedUrlPluginOptions {
+    /** S3 configuration */
+    s3: S3Config;
+}

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Provides presigned URL upload capabilities for PostGraphile v5:
+ * - requestUploadUrl mutation (presigned PUT URL generation)
+ * - confirmUpload mutation (upload verification + status transition)
+ * - downloadUrl computed field (presigned GET URL / public URL)
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-uploads',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
+export { createDownloadUrlPlugin } from './download-url-field';
+export { PresignedUrlPreset } from './preset';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
+export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, PresignedUrlPluginOptions, } from './types';

package/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Provides presigned URL upload capabilities for PostGraphile v5:
+ * - requestUploadUrl mutation (presigned PUT URL generation)
+ * - confirmUpload mutation (upload verification + status transition)
+ * - downloadUrl computed field (presigned GET URL / public URL)
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-uploads',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headObject = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.clearBucketCache = exports.clearStorageModuleCache = exports.getBucketConfig = exports.getStorageModuleConfig = exports.PresignedUrlPreset = exports.createDownloadUrlPlugin = exports.createPresignedUrlPlugin = exports.PresignedUrlPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
+Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
+var download_url_field_1 = require("./download-url-field");
+Object.defineProperty(exports, "createDownloadUrlPlugin", { enumerable: true, get: function () { return download_url_field_1.createDownloadUrlPlugin; } });
+var preset_1 = require("./preset");
+Object.defineProperty(exports, "PresignedUrlPreset", { enumerable: true, get: function () { return preset_1.PresignedUrlPreset; } });
+var storage_module_cache_1 = require("./storage-module-cache");
+Object.defineProperty(exports, "getStorageModuleConfig", { enumerable: true, get: function () { return storage_module_cache_1.getStorageModuleConfig; } });
+Object.defineProperty(exports, "getBucketConfig", { enumerable: true, get: function () { return storage_module_cache_1.getBucketConfig; } });
+Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });
+Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
+var s3_signer_1 = require("./s3-signer");
+Object.defineProperty(exports, "generatePresignedPutUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedPutUrl; } });
+Object.defineProperty(exports, "generatePresignedGetUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedGetUrl; } });
+Object.defineProperty(exports, "headObject", { enumerable: true, get: function () { return s3_signer_1.headObject; } });

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "graphile-presigned-url-plugin",
+  "version": "0.2.0",
+  "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl, confirmUpload mutations and downloadUrl computed field",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "graphql",
+    "presigned-url",
+    "upload",
+    "s3"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1009.0",
+    "@aws-sdk/s3-request-presigner": "^3.1009.0",
+    "@pgpmjs/logger": "^2.5.2",
+    "lru-cache": "^11.2.7"
+  },
+  "peerDependencies": {
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphile-utils": "5.0.0",
+    "graphql": "16.13.0",
+    "postgraphile": "5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "makage": "^0.1.10"
+  },
+  "gitHead": "fc23b83307d007a14e54b1d0fc36614b9650a5dc"
+}

package/plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Adds presigned URL upload support to PostGraphile v5:
+ *
+ * 1. `requestUploadUrl` mutation — generates a presigned PUT URL for direct
+ *    client-to-S3 upload. Checks bucket access via RLS, deduplicates by
+ *    content hash, tracks the request in upload_requests.
+ *
+ * 2. `confirmUpload` mutation — confirms a file was uploaded to S3, verifies
+ *    the object exists with correct content-type, transitions file status
+ *    from 'pending' to 'ready'.
+ *
+ * 3. `downloadUrl` computed field on File types — generates presigned GET URLs
+ *    for private files, returns public URL prefix + key for public files.
+ *
+ * Uses the extendSchema + grafast plan pattern (same as PublicKeySignature).
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PresignedUrlPluginOptions } from './types';
+export declare function createPresignedUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
+export declare const PresignedUrlPlugin: typeof createPresignedUrlPlugin;
+export default PresignedUrlPlugin;