Add initializeBucketCapacity to seed empty-bucket metrics

Add a MongoClientInterface method that idempotently inserts a
zero-value bucket capacity document into __infostore when none
exists (upsert with $setOnInsert, so an existing count-items
document with real values is never overwritten). Exposed through
MetadataWrapper (no-op for non-mongodb backends).

This lets CloudServer seed a metric document at bucket creation
(or when a quota is enabled on an empty bucket) so bucket quota
checks are served before the periodic count-items job runs.

Issue: ARSN-610

Author: delthas

lib/storage/metadata/MetadataWrapper.js

@@ -462,6 +462,16 @@ class MetadataWrapper {
         return this.client.getUUID(log, cb);
     }
 
+    initializeBucketCapacity(bucketName, creationDate, log, cb) {
+        if (!this.client.initializeBucketCapacity) {
+            log.debug('initializeBucketCapacity not supported by backend, skipping', {
+                implName: this.implName,
+            });
+            return cb(null);
+        }
+        return this.client.initializeBucketCapacity(bucketName, creationDate, log, cb);
+    }
+
     getDiskUsage(log, cb) {
         if (!this.client.getDiskUsage) {
             log.debug('returning empty disk usage as fallback', {

lib/storage/metadata/mongoclient/MongoClientInterface.ts

@@ -151,63 +151,75 @@ export type InternalListObjectParams = {
     gt?: undefined;
 };
 
+export interface UsedCapacityMetrics {
+    current: Long | number;
+    nonCurrent: Long | number;
+    _currentCold: Long | number;
+    _nonCurrentCold: Long | number;
+    _currentRestored: Long | number;
+    _currentRestoring: Long | number;
+    _nonCurrentRestored: Long | number;
+    _nonCurrentRestoring: Long | number;
+    _incompleteMPUParts: Long | number;
+    // present on per-location and inflight-tagged bucket entries
+    _inflightsPreScan?: Long | number;
+}
+
+export interface ObjectCountMetrics {
+    current: Long | number;
+    nonCurrent: Long | number;
+    deleteMarker: Long | number;
+    _currentCold: Long | number;
+    _nonCurrentCold: Long | number;
+    _currentRestored: Long | number;
+    _currentRestoring: Long | number;
+    _nonCurrentRestored: Long | number;
+    _nonCurrentRestoring: Long | number;
+    _incompleteMPUUploads: Long | number;
+}
+
 export interface InfostoreDocument extends Document {
     _id: string | 'uuid';
     value?: string | ObjectMDStats;
     measuredOn?: string;
-    objectCount?: {
-        current: Long | number;
-        _currentCold: Long | number;
-        deleteMarker: Long | number;
-        nonCurrent: Long | number;
-        _nonCurrentCold: Long | number;
-        _currentRestored: Long | number;
-        _currentRestoring: Long | number;
-        _nonCurrentRestored: Long | number;
-        _nonCurrentRestoring: Long | number;
-        _incompleteMPUUploads: Long | number;
-    };
-    usedCapacity?: {
-        current: Long | number;
-        _currentCold: Long | number;
-        nonCurrent: Long | number;
-        _nonCurrentCold: Long | number;
-        _currentRestored: Long | number;
-        _currentRestoring: Long | number;
-        _nonCurrentRestored: Long | number;
-        _nonCurrentRestoring: Long | number;
-        _incompleteMPUParts: Long | number;
-    };
+    objectCount?: ObjectCountMetrics;
+    usedCapacity?: UsedCapacityMetrics;
     locations: {
         [key: string]: {
-            usedCapacity: {
-                current: Long | number;
-                nonCurrent: Long | number;
-                _currentCold: Long | number;
-                _nonCurrentCold: Long | number;
-                _currentRestored: Long | number;
-                _currentRestoring: Long | number;
-                _nonCurrentRestored: Long | number;
-                _nonCurrentRestoring: Long | number;
-                _inflightsPreScan: Long | number;
-                _incompleteMPUParts: Long | number;
-            };
-            objectCount: {
-                current: Long | number;
-                nonCurrent: Long | number;
-                _currentCold: Long | number;
-                _nonCurrentCold: Long | number;
-                _currentRestored: Long | number;
-                _currentRestoring: Long | number;
-                _nonCurrentRestored: Long | number;
-                _nonCurrentRestoring: Long | number;
-                _incompleteMPUUploads: Long | number;
-                deleteMarker: Long | number;
-            };
+            usedCapacity: UsedCapacityMetrics;
+            objectCount: ObjectCountMetrics;
         };
     };
 }
 
+// Canonical zero-value capacity/count metrics for an empty bucket, matching the
+// structure downstream metric readers expect.
+const emptyBucketCapacityMetrics: { usedCapacity: UsedCapacityMetrics; objectCount: ObjectCountMetrics } = {
+    usedCapacity: {
+        current: 0,
+        nonCurrent: 0,
+        _currentCold: 0,
+        _nonCurrentCold: 0,
+        _currentRestored: 0,
+        _currentRestoring: 0,
+        _nonCurrentRestored: 0,
+        _nonCurrentRestoring: 0,
+        _incompleteMPUParts: 0,
+    },
+    objectCount: {
+        current: 0,
+        nonCurrent: 0,
+        deleteMarker: 0,
+        _currentCold: 0,
+        _nonCurrentCold: 0,
+        _currentRestored: 0,
+        _currentRestoring: 0,
+        _nonCurrentRestored: 0,
+        _nonCurrentRestoring: 0,
+        _incompleteMPUUploads: 0,
+    },
+};
+
 export type ObjectMDStats = {
     versions: number;
     objects: any;
@@ -2711,6 +2723,57 @@ class MongoClientInterface {
             });
     }
 
+    /**
+     * Initialize a zero-value bucket capacity metric document in the
+     * `__infostore` collection, unless one already exists. This lets quota
+     * checks be served for a freshly created (or newly quota-enabled empty)
+     * bucket before the periodic metrics job has produced real values.
+     *
+     * Idempotent: an existing document (e.g. one already holding real metrics)
+     * is never overwritten, thanks to `$setOnInsert`.
+     *
+     * @param bucketName - name of the bucket
+     * @param creationDate - bucket creation date used to build the metric id;
+     *   must match the id the metrics job uses so lookups resolve to the same
+     *   document
+     * @param log - logger instance
+     * @param cb - callback
+     * @returns undefined
+     */
+    initializeBucketCapacity(
+        bucketName: string,
+        creationDate: string,
+        log: werelogs.Logger,
+        cb: ArsenalCallback<void>,
+    ) {
+        const i = this.getCollection<InfostoreDocument>(INFOSTORE);
+        if (!i) {
+            log.error('initializeBucketCapacity: error getting infostore collection');
+            return cb(errors.InternalError);
+        }
+        const timestamp = new Date(creationDate).getTime();
+        if (Number.isNaN(timestamp)) {
+            log.error('initializeBucketCapacity: invalid creationDate', { bucketName, creationDate });
+            return cb(errors.InternalError);
+        }
+        const _id = `bucket_${bucketName}_${timestamp}`;
+        const doc = <InfostoreDocument>{
+            _id,
+            measuredOn: new Date().toJSON(),
+            ...emptyBucketCapacityMetrics,
+        };
+        return i
+            .updateOne({ _id }, { $setOnInsert: doc }, { upsert: true })
+            .then(() => cb(null))
+            .catch(err => {
+                log.error('initializeBucketCapacity: error initializing bucket capacity', {
+                    error: err.message,
+                    bucketName,
+                });
+                return cb(errors.InternalError);
+            });
+    }
+
     /*
      * we always try to generate a new UUID in order to be atomic in
      * case of concurrency. The write will fail if it already exists.

tests/unit/storage/metadata/mongoclient/MongoClientInterface.spec.js

@@ -1609,6 +1609,73 @@ describe('MongoClientInterface, readUUID', () => {
     });
 });
 
+describe('MongoClientInterface, initializeBucketCapacity', () => {
+    let client;
+    let sandbox;
+
+    beforeEach(async () => {
+        sandbox = sinon.createSandbox();
+        client = createClient();
+        await promisify(client.setup).bind(client)();
+    });
+
+    afterEach(async () => {
+        sandbox.restore();
+        if (client) {
+            await promisify(client.close).bind(client)();
+        }
+    });
+
+    it('should insert a zero-value bucket capacity document', async () => {
+        const bucketName = 'init-capacity-bucket';
+        const creationDate = new Date('2023-03-08T14:13:28.000Z').toJSON();
+        const expectedId = `bucket_${bucketName}_${new Date(creationDate).getTime()}`;
+        await promisify(client.initializeBucketCapacity).bind(client)(bucketName, creationDate, logger);
+        const doc = await client.getCollection('__infostore').findOne({ _id: expectedId });
+        assert(doc, 'Expected the capacity document to be inserted');
+        assert.strictEqual(doc.usedCapacity.current, 0);
+        assert.strictEqual(doc.usedCapacity.nonCurrent, 0);
+        assert.strictEqual(doc.objectCount.current, 0);
+        assert.strictEqual(doc.objectCount.deleteMarker, 0);
+        assert(doc.measuredOn, 'Expected measuredOn to be set');
+    });
+
+    it('should not overwrite an existing capacity document (idempotent)', async () => {
+        const bucketName = 'existing-capacity-bucket';
+        const creationDate = new Date('2023-03-08T14:13:28.000Z').toJSON();
+        const expectedId = `bucket_${bucketName}_${new Date(creationDate).getTime()}`;
+        const coll = client.getCollection('__infostore');
+        await coll.insertOne({
+            _id: expectedId,
+            measuredOn: new Date().toJSON(),
+            usedCapacity: { current: 12345, nonCurrent: 0 },
+            objectCount: { current: 7, deleteMarker: 0 },
+        });
+        await promisify(client.initializeBucketCapacity).bind(client)(bucketName, creationDate, logger);
+        const doc = await coll.findOne({ _id: expectedId });
+        assert.strictEqual(doc.usedCapacity.current, 12345, 'Existing capacity must not be overwritten');
+        assert.strictEqual(doc.objectCount.current, 7);
+    });
+
+    it('should return InternalError when the update fails', async () => {
+        const mockCollection = {
+            updateOne: sandbox.stub().rejects(new Error('Simulated MongoDB error')),
+        };
+        sandbox.stub(client, 'getCollection').returns(mockCollection);
+        await assert.rejects(
+            promisify(client.initializeBucketCapacity).bind(client)('b', new Date().toJSON(), logger),
+            err => err.code === 500,
+        );
+    });
+
+    it('should return InternalError when creationDate is invalid', async () => {
+        await assert.rejects(
+            promisify(client.initializeBucketCapacity).bind(client)('b', 'not-a-date', logger),
+            err => err.code === 500,
+        );
+    });
+});
+
 describe('MongoClientInterface, writeUUIDIfNotExists', () => {
     let client;
     let sandbox;