graphile-bucket-provisioner-plugin 1.14.2 → 1.15.0

package/README.md

@@ -1,27 +1,12 @@
 # graphile-bucket-provisioner-plugin
 
-<p align="center" width="100%">
-  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
-</p>
+PostGraphile v5 plugin that exposes a `provisionBucket` mutation for manually
+queueing storage reconciliation.
 
-<p align="center" width="100%">
-  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
-    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
-  </a>
-   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
-   <a href="https://www.npmjs.com/package/graphile-bucket-provisioner-plugin"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-bucket-provisioner-plugin%2Fpackage.json"/></a>
-</p>
-
-PostGraphile v5 plugin that explicitly provisions S3-compatible buckets through a GraphQL mutation using [`@constructive-io/bucket-provisioner`](../packages/bucket-provisioner).
-
-## Features
-
-- **Explicit `provisionBucket` mutation** — GraphQL mutation for manual/retry provisioning of any bucket
-- **3-tier CORS resolution** — Bucket-level `allowed_origins` → storage module-level `allowed_origins` → plugin config `allowedOrigins`
-- **Wildcard CORS** — Set `allowed_origins = ['*']` on a bucket for fully open CDN/public deployments
-- **Per-database overrides** — Reads `endpoint`, `provider`, `public_url_prefix`, and `allowed_origins` from the `storage_module` table for multi-tenant setups
-- **Lazy S3 config** — Connection config can be a function (evaluated once, cached) to avoid eager env-var reads at import time
-- **Deployment-controlled naming** — Requires a `resolveBucketName` policy for tenant-aware physical bucket names
+The constructive-db `storage:provision_bucket` job is the only component that
+mints physical S3 bucket names, provisions S3, and records `physical_name`.
+This plugin resolves the logical bucket under RLS and enqueues that job; it
+does not call S3 or derive a physical name.
 
 ## Installation
 
@@ -29,140 +14,46 @@ PostGraphile v5 plugin that explicitly provisions S3-compatible buckets through
 pnpm add graphile-bucket-provisioner-plugin
 ```
 
-## Quick Start
-
-```typescript
-import { createBucketProvisionerPlugin } from 'graphile-bucket-provisioner-plugin';
-
-const BucketProvisionerPlugin = createBucketProvisionerPlugin({
-  connection: {
-    provider: 'minio',
-    region: 'us-east-1',
-    endpoint: 'http://minio:9000',
-    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
-  },
-  allowedOrigins: ['https://app.example.com'],
-});
-
-// Add to your PostGraphile preset
-const preset: GraphileConfig.Preset = {
-  plugins: [BucketProvisionerPlugin],
-};
-```
-
-Or use the convenience preset:
+## Usage
 
 ```typescript
 import { BucketProvisionerPreset } from 'graphile-bucket-provisioner-plugin';
 
-const preset: GraphileConfig.Preset = {
-  extends: [
-    BucketProvisionerPreset({
-      connection: () => ({
-        provider: 'minio',
-        region: 'us-east-1',
-        endpoint: process.env.S3_ENDPOINT!,
-        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
-      }),
-      allowedOrigins: ['https://app.example.com'],
-    }),
-  ],
+const preset = {
+  extends: [BucketProvisionerPreset()],
 };
 ```
 
-## How It Works
-
-### Auto-Provisioning (default)
-
-When a `createBucket` mutation runs on a table tagged with `@storageBuckets`:
-
-1. The original resolver runs first (creates the DB row via RLS)
-2. The plugin reads the bucket's `key` and `type` from the mutation input
-3. It reads the `storage_module` config for per-database endpoint/provider overrides
-4. It calls `BucketProvisioner.provision()` to create and configure the S3 bucket
-5. If provisioning fails, the error is logged but the mutation result is returned normally
-
-### Explicit Mutation
-
-The plugin also adds a `provisionBucket` mutation for manual provisioning or retrying failed provisions:
+The mutation accepts a logical bucket key and optionally an owner entity ID:
 
 ```graphql
 mutation {
   provisionBucket(input: { bucketKey: "public" }) {
-    success
-    bucketName
-    accessType
-    provider
-    endpoint
-    error
+    bucketId
+    bucketKey
+    physicalName
+    jobId
   }
 }
 ```
 
-This mutation:
-1. Reads the bucket row from the database (protected by RLS)
-2. Reads the storage module config for the current database
-3. Provisions the S3 bucket with the appropriate settings
-4. Returns a success/error payload
-
-## API
-
-### `createBucketProvisionerPlugin(options)`
-
-Creates the plugin instance. Returns a `GraphileConfig.Plugin`.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `connection` | `StorageConnectionConfig \| () => StorageConnectionConfig` | S3 connection config (static or lazy getter) |
-| `allowedOrigins` | `string[]` | CORS allowed origins for bucket configuration |
-| `resolveBucketName` | `(databaseId, bucketKey) => string` | Deployment policy for deriving a tenant-aware physical bucket name |
-| `versioning` | `boolean?` | Enable S3 versioning on provisioned buckets (default: `false`) |
-
-### `BucketProvisionerPreset(options)`
-
-Convenience function that wraps the plugin in a `GraphileConfig.Preset`.
-
-### Connection Config
-
-```typescript
-interface StorageConnectionConfig {
-  provider: 's3' | 'minio' | 'r2' | 'gcs' | 'spaces';
-  region: string;
-  endpoint?: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-}
-```
-
-### Smart Tag Detection
-
-The plugin detects tables tagged with `@storageBuckets` (set by the storage module generator in constructive-db):
-
-```sql
-COMMENT ON TABLE app_public.buckets IS E'@storageBuckets\nStorage buckets table';
-```
-
-The plugin wraps `create*` mutations for auto-provisioning and `update*` mutations for CORS change detection. Delete mutations are not wrapped.
-
-## Error Handling
-
-The plugin is designed to never break mutations:
-
-- **Auto-provisioning errors** are caught and logged. The mutation result is returned normally. The admin can retry via the `provisionBucket` mutation.
-- **Explicit `provisionBucket` errors** return a structured payload with `success: false` and an `error` message.
-- **Validation errors** (`INVALID_BUCKET_KEY`, `DATABASE_NOT_FOUND`, `STORAGE_MODULE_NOT_PROVISIONED`, `BUCKET_NOT_FOUND`) are thrown as exceptions since they indicate configuration issues.
-
-## Multi-Tenant Support
+`provisionBucket` resolves the bucket row under RLS and enqueues the same
+`storage:provision_bucket` job used by the database INSERT trigger. Database
+scope jobs include `database_id`, use the `bucket:<uuid>` queue, and have
+25 attempts. Platform scope jobs use the platform trigger payload. Enqueue
+failures are returned as GraphQL errors.
 
-The plugin reads per-database overrides from the `storage_module` table:
+The payload fields are:
 
-- `endpoint` — Override the S3 endpoint for this database
-- `provider` — Override the storage provider for this database
-- `public_url_prefix` — CDN/public URL prefix for public buckets
+| Field | Description |
+|-------|-------------|
+| `bucketId` | Logical bucket row ID |
+| `bucketKey` | Logical bucket key |
+| `physicalName` | Recorded physical name, or `null` while reconciliation is pending |
+| `jobId` | ID of the queued reconciler job |
 
-This allows different tenants to use different storage backends while sharing the same plugin configuration.
+There are no plugin options: S3 connection details, naming, CORS, versioning,
+and physical-name recording belong to the reconciler.
 
 ---
 

package/esm/index.d.ts

@@ -1,35 +1,9 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` mutation for PostGraphile v5.
- *
- * @example
- * ```typescript
- * import { BucketProvisionerPreset } from 'graphile-bucket-provisioner-plugin';
- * import { getEnvOptions } from '@constructive-io/graphql-env';
- *
- * // Use a lazy getter so env vars are read at runtime, not import time
- * function getConnection() {
- *   const { cdn } = getEnvOptions();
- *   return {
- *     provider: cdn?.provider || 'minio',
- *     region: cdn?.awsRegion || 'us-east-1',
- *     endpoint: cdn?.endpoint || 'http://minio:9000',
- *     accessKeyId: cdn?.awsAccessKey!,
- *     secretAccessKey: cdn?.awsSecretKey!,
- *   };
- * }
- *
- * const preset = {
- *   extends: [
- *     BucketProvisionerPreset({
- *       connection: getConnection, // pass function ref, NOT getConnection()
- *       allowedOrigins: ['https://app.example.com'],
- *     }),
- *   ],
- * };
- * ```
+ * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';
 export { BucketProvisionerPreset } from './preset';
-export type { BucketAccessType, BucketNameResolver, BucketProvisionerPluginOptions, ConnectionConfigOrGetter, ProvisionBucketInput, ProvisionBucketPayload, ProvisionResult, StorageConnectionConfig, StorageProvider, } from './types';
+export type { ProvisionBucketInput, ProvisionBucketPayload, } from './types';

package/esm/index.js

@@ -1,34 +1,8 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` mutation for PostGraphile v5.
- *
- * @example
- * ```typescript
- * import { BucketProvisionerPreset } from 'graphile-bucket-provisioner-plugin';
- * import { getEnvOptions } from '@constructive-io/graphql-env';
- *
- * // Use a lazy getter so env vars are read at runtime, not import time
- * function getConnection() {
- *   const { cdn } = getEnvOptions();
- *   return {
- *     provider: cdn?.provider || 'minio',
- *     region: cdn?.awsRegion || 'us-east-1',
- *     endpoint: cdn?.endpoint || 'http://minio:9000',
- *     accessKeyId: cdn?.awsAccessKey!,
- *     secretAccessKey: cdn?.awsSecretKey!,
- *   };
- * }
- *
- * const preset = {
- *   extends: [
- *     BucketProvisionerPreset({
- *       connection: getConnection, // pass function ref, NOT getConnection()
- *       allowedOrigins: ['https://app.example.com'],
- *     }),
- *   ],
- * };
- * ```
+ * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';
 export { BucketProvisionerPreset } from './preset';

package/esm/plugin.d.ts

@@ -3,13 +3,9 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly provision an S3 bucket for a
+ * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
  *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then calls BucketProvisioner to create and configure the S3 bucket.
- *
- * This plugin uses `@constructive-io/bucket-provisioner` for the actual
- * S3 operations (bucket creation, Block Public Access, CORS, policies,
- * versioning, lifecycle rules).
+ *    then queues the same storage reconciler job used by the INSERT trigger.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -17,18 +13,16 @@
  *   COMMENT ON TABLE buckets IS E'@storageBuckets\nStorage buckets table';
  */
 import type { GraphileConfig } from 'graphile-config';
-import type { BucketProvisionerPluginOptions } from './types';
 /**
  * Creates the bucket provisioner plugin.
  *
- * This plugin provides one provisioning pathway:
+ * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to provision (or re-provision) the S3 bucket. Protected
- *    by RLS on the buckets table.
+ *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket. Protected by RLS on the buckets table.
  *
- * @param options - Plugin configuration (S3 credentials, CORS origins, naming)
  */
-export declare function createBucketProvisionerPlugin(options: BucketProvisionerPluginOptions): GraphileConfig.Plugin;
+export declare function createBucketProvisionerPlugin(): GraphileConfig.Plugin;
 export declare const BucketProvisionerPlugin: typeof createBucketProvisionerPlugin;
 export default BucketProvisionerPlugin;