fix: handle GridFS write errors to prevent silent file loss

[vshvets-bc]

Description

Fixes silent GridFS write loss. DataBaseHelper.saveFile / saveFileWithId, BaseEntity._createFile, and PolicyImportExport._createFile mint the file _id up front and resolve on end() regardless of the write outcome, with no stream 'error' handler. An async GridFS write failure is therefore swallowed:

• the returned promise hangs (the end callback never fires when the stream errors), or
• an unhandled 'error' event crashes the process, or
• a phantom fileId is recorded with no bytes written, surfacing later as FileNotFound and lost document content (schema / VC / policy-action documents).

Because BaseEntity._createFile is used by every file-backed entity's @BeforeCreate/@BeforeUpdate hook, this affects ~20 entities (vc-document, vp-document, schema, policy, tool, policy-action, etc.).

Changes

All four write sites now:

• register fileStream.on('error', reject) so async write failures reject instead of hanging / crashing / leaving a phantom id;
• resolve with the id only after a successful finish (single-settle guard so 'error' and end can't double-settle);
• reject on null/undefined content (empty buffers remain valid — 0-length file).

Files:

• common/src/models/base-entity.ts — _createFile
• common/src/helpers/db-helper.ts — saveFile, saveFileWithId
• common/src/import-export/policy.ts — _createFile

Tests

common/tests/unit-tests/gridfs-save-error-handling.test.mjs (mocks DataBaseHelper.gridFS):

• resolves with id on successful finish
• rejects (does not hang) on stream 'error' — the core regression
• rejects on null/undefined
• allows an empty buffer

common builds clean; 7/7 tests pass.

Related issue(s)

Silent GridFS write failures leading to FileNotFound / lost document content under load.

[Pyatakov]

While the set of changes itself looks good, I would recommend to refactor these changes to avoid duplication, leaving each call site as a one-liner.

1. common/src/helpers/db-helper.ts

Add GridFSBucketWriteStream to the mongodb import (line 5):

import { Db, GridFSBucket, GridFSBucketWriteStream } from 'mongodb';

Add the shared helper (e.g. just after connectGridFS, before saveFile):

    /**
     * Write content to a GridFS upload stream and resolve with the file id only
     * after a successful finish. Registers an 'error' handler so async write
     * failures reject instead of hanging, crashing, or leaving a phantom id.
     * Rejects on null/undefined content (empty buffers/strings are valid).
     * @param content file content
     * @param label context label for error messages
     * @param openStream opens the target upload stream
     * @returns file Id
     */
    public static writeToGridFS(
        content: string | Buffer,
        label: string,
        openStream: () => GridFSBucketWriteStream
    ): Promise<ObjectId> {
        return new Promise<ObjectId>((resolve, reject) => {
            try {
                if (content === null || content === undefined) {
                    reject(new Error(`GridFS write (${label}): content is null/undefined`));
                    return;
                }
                const stream = openStream();
                const fileId = stream.id;
                let settled = false;
                // resolve only after a successful finish; surface async write errors instead of leaving a phantom id
                const done = (err?: any) => {
                    if (settled) { return; }
                    settled = true;
                    if (err) { reject(err); } else { resolve(fileId); }
                };
                stream.on('error', done);
                stream.write(content);
                stream.end(() => done());
            } catch (error) {
                reject(error);
            }
        });
    }

Replace saveFile and saveFileWithId bodies:

    public static async saveFile(uuid: string, buffer: Buffer): Promise<ObjectId> {
        return DataBaseHelper.writeToGridFS(buffer, uuid, () => DataBaseHelper.gridFS.openUploadStream(uuid));
    }

    public static async saveFileWithId(id: ObjectId, filename: string, buffer: Buffer): Promise<ObjectId> {
        return DataBaseHelper.writeToGridFS(buffer, filename, () => DataBaseHelper.gridFS.openUploadStreamWithId(id, filename));
    }

2. common/src/models/base-entity.ts

    protected _createFile(json: string | Buffer, name: string): Promise<ObjectId> {
        const fileName = `${name}_${this._id?.toString()}_${GenerateUUIDv4()}`;
        return DataBaseHelper.writeToGridFS(json, name, () => DataBaseHelper.gridFS.openUploadStream(fileName));
    }

3. common/src/import-export/policy.ts

    private static _createFile(json: string | Buffer, fileName: string): Promise<ObjectId> {
        return DataBaseHelper.writeToGridFS(json, fileName, () => DataBaseHelper.gridFS.openUploadStream(fileName));
    }

Test coverage

Because all four sites now route through writeToGridFS, the existing saveFile/saveFileWithId regression tests transitively exercise the same code path used by both _createFile methods, closing the coverage gap (BaseEntity._createFile and PolicyImportExport._createFile carry identical logic but aren't tested). If you'd rather assert them directly, you'll be able now unit-test DataBaseHelper.writeToGridFS in isolation.