Merge pull request #7 from devcodex-labs/cursor/gridfs-error-policy-5906

fix(gridfs): map driver errors and match write-path iid

Author: rockyshi1993

changelogs/unreleased.md

@@ -4,6 +4,9 @@
 
 - Add GridFS buckets on `msq.gridfs()` and `model.gridfs()`, including upload, download, ranges, `ensureIndexes`, and phase-1 resumable upload. `writePathPolicy` gains a `gridfs` field and category. Policy violations stay `INVALID_OPERATION` with `reason: 'WRITE_PATH_POLICY'`. These notes stage the work after 3.4.0; the npm package version is unchanged and this file is not a 3.5.0 release. The Search index lifecycle API remains in the [3.4.0 versioned notes](./v3.4.0.md).
 - Raise the CJS and ESM runtime package budgets for GridFS 3.5.0. `gridfs()` stays synchronous, so the single-file build keeps that code in the main bundle. The CJS ceiling is 873000 bytes after `contentType` moved onto file metadata.
+- Map driver failures from GridFS `getFile`, `findFiles`, `abortResumableUpload`, and index creation to `MONGODB_ERROR`, with the driver error kept as `cause`. Existing `GRIDFS_*` errors stay unchanged.
+- Pass the collection-style internal instance id (`iid`) into GridFS `writePathPolicy` matching. Model-only reads stay allowed, and writes still require `gridfs: 'allow'`.
+- Raise the CJS runtime ceiling from 873000 to 874000 bytes and the ESM ceiling from 870000 to 871000 bytes for that driver-error mapping and iid matching. The CLI budget stays 50000 bytes.
 
 ## Archived preparation notes for the 3.3.2 candidate
 

config/package-budget.json

@@ -1,8 +1,8 @@
 {
-  "comment": "GridFS 3.5.0 stays in the main bundle: sync gridfs() cannot be split out of the single-file build.",
+  "comment": "GridFS 3.5.0 stays in the main bundle: sync gridfs() cannot be split out of the single-file build. CJS 874000 and ESM 871000 cover driver-error mapping and write-path iid matching.",
   "artifacts": {
-    "dist/cjs/index.cjs": 873000,
-    "dist/esm/index.mjs": 870000,
+    "dist/cjs/index.cjs": 874000,
+    "dist/esm/index.mjs": 871000,
     "dist/cjs/cli/data-task.cjs": 50000
   }
 }

src/capabilities/gridfs/bucket.ts

@@ -18,6 +18,12 @@ import type {
 import { deleteFile, downloadFile, dropBucket, findFiles, getFile, openDownloadStream, openUploadStream, renameFile, uploadFile } from './operations';
 import { abortResumableUpload, appendChunks, beginResumableUpload, finalizeResumableUpload } from './resumable';
 
+/** Same iid as collection write paths (`instanceId` prefix, then `pool:db.collection` or `db:collection`). */
+function collectionWritePathIid(instanceId: string | undefined, poolName: string | undefined, dbName: string, collection: string): string {
+    const scopedName = poolName ? `${poolName}:${dbName}.${collection}` : `${dbName}:${collection}`;
+    return instanceId ? `${instanceId}:${scopedName}` : scopedName;
+}
+
 export class MonSQLizeGridFSBucketImpl {
     constructor(private readonly ctx: GridFSContext) {}
 
@@ -96,12 +102,14 @@ export class MonSQLizeGridFSBucketImpl {
     }
 
     private assertAllowed(operation: string, category: 'gridfs' | 'management'): void {
+        const collection = `${this.ctx.bucketName}.files`;
         assertWritePathAllowed({
             policy: this.ctx.policy,
             namespace: {
+                iid: collectionWritePathIid(this.ctx.instanceId, this.ctx.poolName, this.ctx.dbName, collection),
                 ...(this.ctx.poolName ? { pool: this.ctx.poolName } : {}),
                 db: this.ctx.dbName,
-                collection: `${this.ctx.bucketName}.files`,
+                collection,
             },
             source: this.ctx.source,
             operation,

src/capabilities/gridfs/errors.ts

@@ -130,6 +130,7 @@ export function isDriverFileNotFound(error: unknown): boolean {
 
 export function mapDriverError(error: unknown, operation: string, ctx: Pick<GridFSContext, 'bucketName'>, target: { id?: ObjectId; filename?: string; uploadId?: ObjectId } = {}): MonSQLizeError {
     if (isGridFSDomainError(error)) return error;
+    if (error instanceof Error && (error as MonSQLizeError).code === ErrorCodes.MONGODB_ERROR) return error as MonSQLizeError;
     const cause = error instanceof Error ? error : new Error(String(error));
     if (isDriverFileNotFound(error)) {
         return fileNotFound(operation, ctx, target);

src/capabilities/gridfs/index.ts

@@ -12,6 +12,7 @@ export interface CreateGridFSBucketDeps {
     bucketName: string;
     dbName: string;
     poolName?: string;
+    instanceId?: string;
     chunkSizeBytes?: number;
     source: 'db' | 'model';
     policy?: NormalizedWritePathPolicy;
@@ -30,6 +31,7 @@ export function createMonSQLizeGridFSBucket(deps: CreateGridFSBucketDeps): MonSQ
         bucketName: deps.bucketName,
         dbName: deps.dbName,
         poolName: deps.poolName,
+        instanceId: deps.instanceId,
         chunkSizeBytes,
         source: deps.source,
         policy: deps.policy,

src/capabilities/gridfs/indexes.ts

@@ -1,6 +1,7 @@
 import type { Db } from 'mongodb';
-import { UPLOADS_TTL_SECONDS } from './types';
+import { mapDriverError } from './errors';
 import { chunksCollectionName, filesCollectionName, uploadsCollectionName } from './normalize';
+import { UPLOADS_TTL_SECONDS } from './types';
 
 /**
  * Idempotent GridFS indexes for one bucket instance.
@@ -28,9 +29,13 @@ export class GridFSIndexLatch {
         const files = this.db.collection(filesCollectionName(this.bucketName));
         const chunks = this.db.collection(chunksCollectionName(this.bucketName));
         const uploads = this.db.collection(uploadsCollectionName(this.bucketName));
-        await files.createIndex({ filename: 1, uploadDate: 1 });
-        await chunks.createIndex({ files_id: 1, n: 1 }, { unique: true });
-        await files.createIndex({ 'metadata.sha256': 1 });
-        await uploads.createIndex({ createdAt: 1 }, { expireAfterSeconds: UPLOADS_TTL_SECONDS });
+        try {
+            await files.createIndex({ filename: 1, uploadDate: 1 });
+            await chunks.createIndex({ files_id: 1, n: 1 }, { unique: true });
+            await files.createIndex({ 'metadata.sha256': 1 });
+            await uploads.createIndex({ createdAt: 1 }, { expireAfterSeconds: UPLOADS_TTL_SECONDS });
+        } catch (error) {
+            throw mapDriverError(error, 'ensureIndexes', { bucketName: this.bucketName });
+        }
     }
 }

src/capabilities/gridfs/operations.ts

@@ -157,19 +157,27 @@ export function openDownloadStream(ctx: GridFSContext, idOrName: GridFSIdOrName,
 
 export async function getFile(ctx: GridFSContext, id: ObjectId): Promise<GridFSFileInfo | null> {
     assertObjectId(id, 'getFile', 'id');
-    const doc = await ctx.db.collection(filesCollectionName(ctx.bucketName)).findOne({ _id: id });
-    return doc ? toFileInfo(doc as Record<string, unknown>) : null;
+    try {
+        const doc = await ctx.db.collection(filesCollectionName(ctx.bucketName)).findOne({ _id: id });
+        return doc ? toFileInfo(doc as Record<string, unknown>) : null;
+    } catch (error) {
+        throw mapDriverError(error, 'getFile', ctx, { id });
+    }
 }
 
 export async function findFiles(ctx: GridFSContext, filter?: GridFSFindFilesFilter, opts?: GridFSFindFilesOptions): Promise<GridFSFileInfo[]> {
     const query = sanitizeFilter(filter, 'findFiles');
     assertFindOptions(opts);
-    let cursor = ctx.db.collection(filesCollectionName(ctx.bucketName)).find(query);
-    if (opts?.sort) cursor = cursor.sort(opts.sort as Sort);
-    if (opts?.skip) cursor = cursor.skip(opts.skip);
-    if (opts?.limit) cursor = cursor.limit(opts.limit);
-    const docs = await cursor.toArray();
-    return docs.map((doc) => toFileInfo(doc as Record<string, unknown>));
+    try {
+        let cursor = ctx.db.collection(filesCollectionName(ctx.bucketName)).find(query);
+        if (opts?.sort) cursor = cursor.sort(opts.sort as Sort);
+        if (opts?.skip) cursor = cursor.skip(opts.skip);
+        if (opts?.limit) cursor = cursor.limit(opts.limit);
+        const docs = await cursor.toArray();
+        return docs.map((doc) => toFileInfo(doc as Record<string, unknown>));
+    } catch (error) {
+        throw mapDriverError(error, 'findFiles', ctx);
+    }
 }
 
 export async function deleteFile(ctx: GridFSContext, id: ObjectId, opts?: GridFSDeleteOptions): Promise<void> {

src/capabilities/gridfs/resumable.ts

@@ -177,17 +177,21 @@ export async function finalizeResumableUpload(ctx: GridFSContext, uploadId: Obje
 
 export async function abortResumableUpload(ctx: GridFSContext, uploadId: ObjectId): Promise<void> {
     assertObjectId(uploadId, 'abortResumableUpload', 'uploadId');
-    const uploads = ctx.db.collection(uploadsCollectionName(ctx.bucketName));
-    const session = await uploads.findOne({ _id: uploadId });
-    if (!session || session.status === 'aborted' || session.status === 'finalized') return;
-    const visible = await ctx.db.collection(filesCollectionName(ctx.bucketName)).findOne(
-        { _id: uploadId },
-        { projection: { _id: 1 } },
-    );
-    if (!visible) {
-        await ctx.db.collection(chunksCollectionName(ctx.bucketName)).deleteMany({ files_id: uploadId });
+    try {
+        const uploads = ctx.db.collection(uploadsCollectionName(ctx.bucketName));
+        const session = await uploads.findOne({ _id: uploadId });
+        if (!session || session.status === 'aborted' || session.status === 'finalized') return;
+        const visible = await ctx.db.collection(filesCollectionName(ctx.bucketName)).findOne(
+            { _id: uploadId },
+            { projection: { _id: 1 } },
+        );
+        if (!visible) {
+            await ctx.db.collection(chunksCollectionName(ctx.bucketName)).deleteMany({ files_id: uploadId });
+        }
+        await uploads.deleteOne({ _id: uploadId });
+    } catch (error) {
+        throw mapDriverError(error, 'abortResumableUpload', ctx, { uploadId });
     }
-    await uploads.deleteOne({ _id: uploadId });
 }
 
 async function payloadBytes(data: Buffer | Uint8Array | Readable): Promise<Buffer> {

src/capabilities/gridfs/types.ts

@@ -114,6 +114,8 @@ export interface GridFSContext {
     bucketName: string;
     dbName: string;
     poolName?: string;
+    /** Configured namespace instance id. The write-path iid is derived the same way as collection writes. */
+    instanceId?: string;
     chunkSizeBytes: number;
     source: Extract<WritePathSource, 'db' | 'model'>;
     policy?: NormalizedWritePathPolicy;

src/entry/runtime-gridfs.ts

@@ -64,6 +64,7 @@ function openGridFS(runtime: unknown, request: {
         bucketName,
         dbName,
         poolName: request.poolName,
+        instanceId: state._runtimeDefaults?.namespace?.instanceId,
         chunkSizeBytes: request.chunkSizeBytes,
         source: request.source,
         policy: state._runtimeDefaults?.writePathPolicy,