graphile-bucket-provisioner-plugin 1.18.1 → 1.19.0

package/README.md

@@ -5,7 +5,7 @@ queueing storage reconciliation.
 
 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
+This plugin resolves the logical bucket under RLS and requests that job; it
 does not call S3 or derive a physical name.
 
 ## Installation
@@ -32,16 +32,18 @@ mutation {
     bucketId
     bucketKey
     physicalName
-    jobId
+    provisionRequestedAt
   }
 }
 ```
 
-`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.
+`provisionBucket` resolves the bucket row under RLS and calls the storage
+module's `<buckets>_provision(bucket_id)`, which stamps the row's
+`provision_requested_at` as the caller and returns the row. The bucket's UPDATE
+job trigger then enqueues the same `storage:provision_bucket` job used on
+INSERT, keyed `storage:provision_bucket:<uuid>` on the `bucket:<uuid>` queue, so
+repeated requests while a job is waiting collapse into it. Failures are
+returned as GraphQL errors.
 
 The payload fields are:
 
@@ -50,7 +52,7 @@ The payload fields are:
 | `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 |
+| `provisionRequestedAt` | When reconciliation was last requested |
 
 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,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/esm/index.js

@@ -1,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/esm/plugin.d.ts

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -19,7 +20,7 @@ import type { GraphileConfig } from 'graphile-config';
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */

package/esm/plugin.js

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -108,19 +109,21 @@ async function resolveDatabaseId(pgClient) {
     return result.rows[0]?.id ?? null;
 }
 /**
- * Enqueue reconciliation through the storage module's generated
- * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role: it
- * locks the bucket row FOR UPDATE under the buckets table's own RLS, then
- * enqueues exactly the job the buckets INSERT trigger does.
+ * Request reconciliation through the storage module's generated
+ * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role and
+ * stamps the bucket's `provision_requested_at` under the buckets table's own
+ * RLS; the bucket's UPDATE job trigger then enqueues the reconciler (keyed and
+ * queued on the bucket, so repeated requests collapse into one pending job).
+ * It returns the updated bucket row.
  */
-async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
+async function requestReconciliation(pgClient, storageModule, bucket) {
     const provisionFunction = QuoteUtils.quoteQualifiedIdentifier(storageModule.private_schema, `${storageModule.buckets_table}_provision`);
-    const result = await runQuery(pgClient, `SELECT ${provisionFunction}($1::uuid) AS id`, [bucket.id]);
-    const jobId = result.rows[0]?.id;
-    if (!jobId) {
-        throw new Error(`STORAGE_BUCKET_JOB_ID_MISSING: bucket ${bucket.id}`);
+    const result = await runQuery(pgClient, `SELECT id, key, physical_name, to_json(provision_requested_at) #>> '{}' AS provision_requested_at FROM ${provisionFunction}($1::uuid)`, [bucket.id]);
+    const row = result.rows[0];
+    if (!row?.id) {
+        throw new Error(`STORAGE_BUCKET_PROVISION_EMPTY: bucket ${bucket.id}`);
     }
-    return jobId;
+    return row;
 }
 // --- Plugin factory ---
 /**
@@ -129,7 +132,7 @@ async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */
@@ -148,22 +151,23 @@ export function createBucketProvisionerPlugin() {
       }
 
       type ProvisionBucketPayload {
-        """The logical bucket row that was queued for reconciliation."""
+        """The logical bucket row whose reconciliation was requested."""
         bucketId: UUID!
         bucketKey: String!
         """The physical bucket name already recorded, or null when reconciliation has not completed."""
         physicalName: String
-        """The reconciler job enqueued to provision this bucket."""
-        jobId: UUID!
+        """When reconciliation was last requested for this bucket."""
+        provisionRequestedAt: Datetime!
       }
 
       extend type Mutation {
         """
         Reconcile an S3 bucket for a logical bucket in the database.
-        Reads the bucket config via RLS, then enqueues the same
-        storage:provision_bucket job used by the INSERT trigger. This is
-        idempotent for an already-reconciled bucket; enqueue failures become
-        GraphQL errors.
+        Records the request on the bucket row via RLS; the bucket's job
+        trigger then enqueues the same storage:provision_bucket job used on
+        INSERT, and repeated requests collapse into one pending job. This is
+        idempotent for an already-reconciled bucket; failures become GraphQL
+        errors.
         """
         provisionBucket(
           input: ProvisionBucketInput!
@@ -199,12 +203,12 @@ export function createBucketProvisionerPlugin() {
                                 throw new Error('BUCKET_NOT_FOUND');
                             }
                             const { storageModule, bucket } = resolution;
-                            const jobId = await enqueueReconciliationJob(pgClient, storageModule, bucket);
+                            const provisioned = await requestReconciliation(pgClient, storageModule, bucket);
                             return {
-                                bucketId: bucket.id,
-                                bucketKey: bucket.key,
-                                physicalName: bucket.physical_name,
-                                jobId,
+                                bucketId: provisioned.id,
+                                bucketKey: provisioned.key,
+                                physicalName: provisioned.physical_name,
+                                provisionRequestedAt: provisioned.provision_requested_at,
                             };
                         });
                     });

package/esm/types.d.ts

@@ -14,15 +14,15 @@ export interface ProvisionBucketInput {
     ownerId?: string;
 }
 /**
- * Result of the provisionBucket reconciliation enqueue mutation.
+ * Result of the provisionBucket mutation: the bucket row it stamped.
  */
 export interface ProvisionBucketPayload {
-    /** The logical bucket row queued for reconciliation */
+    /** The logical bucket row whose reconciliation was requested */
     bucketId: string;
     /** The logical bucket key */
     bucketKey: string;
     /** The physical name already recorded, or null while reconciliation is pending */
     physicalName: string | null;
-    /** The queued reconciler job */
-    jobId: string;
+    /** When reconciliation was last requested */
+    provisionRequestedAt: string;
 }

package/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/index.js

@@ -2,7 +2,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-bucket-provisioner-plugin",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "Bucket provisioning plugin for PostGraphile v5 — explicitly provisions S3 buckets via a GraphQL mutation",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -58,5 +58,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.8.0"
   },
-  "gitHead": "0b4ffa11a6d7958ba1068ce8e19616d4b018c0d6"
+  "gitHead": "b6c80da2ba0532a4aaf0d0154901efa7911974d8"
 }

package/plugin.d.ts

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -19,7 +20,7 @@ import type { GraphileConfig } from 'graphile-config';
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */

package/plugin.js

@@ -4,9 +4,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -112,19 +113,21 @@ async function resolveDatabaseId(pgClient) {
     return result.rows[0]?.id ?? null;
 }
 /**
- * Enqueue reconciliation through the storage module's generated
- * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role: it
- * locks the bucket row FOR UPDATE under the buckets table's own RLS, then
- * enqueues exactly the job the buckets INSERT trigger does.
+ * Request reconciliation through the storage module's generated
+ * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role and
+ * stamps the bucket's `provision_requested_at` under the buckets table's own
+ * RLS; the bucket's UPDATE job trigger then enqueues the reconciler (keyed and
+ * queued on the bucket, so repeated requests collapse into one pending job).
+ * It returns the updated bucket row.
  */
-async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
+async function requestReconciliation(pgClient, storageModule, bucket) {
     const provisionFunction = quotes_1.QuoteUtils.quoteQualifiedIdentifier(storageModule.private_schema, `${storageModule.buckets_table}_provision`);
-    const result = await runQuery(pgClient, `SELECT ${provisionFunction}($1::uuid) AS id`, [bucket.id]);
-    const jobId = result.rows[0]?.id;
-    if (!jobId) {
-        throw new Error(`STORAGE_BUCKET_JOB_ID_MISSING: bucket ${bucket.id}`);
+    const result = await runQuery(pgClient, `SELECT id, key, physical_name, to_json(provision_requested_at) #>> '{}' AS provision_requested_at FROM ${provisionFunction}($1::uuid)`, [bucket.id]);
+    const row = result.rows[0];
+    if (!row?.id) {
+        throw new Error(`STORAGE_BUCKET_PROVISION_EMPTY: bucket ${bucket.id}`);
     }
-    return jobId;
+    return row;
 }
 // --- Plugin factory ---
 /**
@@ -133,7 +136,7 @@ async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */
@@ -152,22 +155,23 @@ function createBucketProvisionerPlugin() {
       }
 
       type ProvisionBucketPayload {
-        """The logical bucket row that was queued for reconciliation."""
+        """The logical bucket row whose reconciliation was requested."""
         bucketId: UUID!
         bucketKey: String!
         """The physical bucket name already recorded, or null when reconciliation has not completed."""
         physicalName: String
-        """The reconciler job enqueued to provision this bucket."""
-        jobId: UUID!
+        """When reconciliation was last requested for this bucket."""
+        provisionRequestedAt: Datetime!
       }
 
       extend type Mutation {
         """
         Reconcile an S3 bucket for a logical bucket in the database.
-        Reads the bucket config via RLS, then enqueues the same
-        storage:provision_bucket job used by the INSERT trigger. This is
-        idempotent for an already-reconciled bucket; enqueue failures become
-        GraphQL errors.
+        Records the request on the bucket row via RLS; the bucket's job
+        trigger then enqueues the same storage:provision_bucket job used on
+        INSERT, and repeated requests collapse into one pending job. This is
+        idempotent for an already-reconciled bucket; failures become GraphQL
+        errors.
         """
         provisionBucket(
           input: ProvisionBucketInput!
@@ -203,12 +207,12 @@ function createBucketProvisionerPlugin() {
                                 throw new Error('BUCKET_NOT_FOUND');
                             }
                             const { storageModule, bucket } = resolution;
-                            const jobId = await enqueueReconciliationJob(pgClient, storageModule, bucket);
+                            const provisioned = await requestReconciliation(pgClient, storageModule, bucket);
                             return {
-                                bucketId: bucket.id,
-                                bucketKey: bucket.key,
-                                physicalName: bucket.physical_name,
-                                jobId,
+                                bucketId: provisioned.id,
+                                bucketKey: provisioned.key,
+                                physicalName: provisioned.physical_name,
+                                provisionRequestedAt: provisioned.provision_requested_at,
                             };
                         });
                     });

package/types.d.ts

@@ -14,15 +14,15 @@ export interface ProvisionBucketInput {
     ownerId?: string;
 }
 /**
- * Result of the provisionBucket reconciliation enqueue mutation.
+ * Result of the provisionBucket mutation: the bucket row it stamped.
  */
 export interface ProvisionBucketPayload {
-    /** The logical bucket row queued for reconciliation */
+    /** The logical bucket row whose reconciliation was requested */
     bucketId: string;
     /** The logical bucket key */
     bucketKey: string;
     /** The physical name already recorded, or null while reconciliation is pending */
     physicalName: string | null;
-    /** The queued reconciler job */
-    jobId: string;
+    /** When reconciliation was last requested */
+    provisionRequestedAt: string;
 }