kuzzle 2.58.0 → 2.59.0

package/dist/lib/cluster/node.js

@@ -50,6 +50,9 @@ const publisher_1 = __importDefault(require("./publisher"));
 const state_1 = __importDefault(require("./state"));
 const subscriber_1 = __importDefault(require("./subscriber"));
 const debug = (0, debug_1.default)("kuzzle:cluster:sync");
+/** Cluster-wide events carrying the collection write locks (see registerEvents) */
+const COLLECTION_LOCK_EVENT = "core:storage:collection:lock";
+const COLLECTION_UNLOCK_EVENT = "core:storage:collection:unlock";
 /**
  * How long `addNode()` may wait for a joining node's first sync message before
  * it answers that node's handshake anyway.
@@ -888,6 +891,13 @@ class ClusterNode {
         global.kuzzle.on("core:storage:collection:delete:after", ({ collection, index, scope }) => {
             this.onCollectionRemoved(scope, index, collection);
         });
+        // Collection write locks travel as cluster-wide events rather than as
+        // dedicated sync topics: a node evicts the sender of a topic it does not
+        // know, which would turn a rolling upgrade into evictions.
+        global.kuzzle.on("core:storage:collection:lock:after", (payload) => this.broadcast(COLLECTION_LOCK_EVENT, payload));
+        global.kuzzle.on("core:storage:collection:unlock:after", (payload) => this.broadcast(COLLECTION_UNLOCK_EVENT, payload));
+        this.eventEmitter.on(COLLECTION_LOCK_EVENT, ({ collection, index, lock, scope }) => global.kuzzle.ask(`core:storage:${scope}:cache:setLock`, index, collection, lock));
+        this.eventEmitter.on(COLLECTION_UNLOCK_EVENT, ({ collection, index, scope }) => global.kuzzle.ask(`core:storage:${scope}:cache:removeLock`, index, collection));
     }
     /**
      * Triggered whenever a realtime room is created on this node

package/dist/lib/core/storage/clientAdapter.d.ts

@@ -1,6 +1,6 @@
 import type { JSONObject } from "../../types/JSONObject";
 import { Elasticsearch } from "../../service/storage/Elasticsearch";
-import { IndexCache } from "./indexCache";
+import { IndexCache, type CollectionLock } from "./indexCache";
 import type { storeScopeEnum } from "./storeScopeEnum";
 import "../../types/Global";
 /** Where `createIndex` / `createCollection` / `loadMappings` write, and whether
@@ -43,10 +43,44 @@ declare class ClientAdapter {
      * Also checks for duplicated index names.
      */
     populateCache(): Promise<void>;
+    /**
+     * Replaces the cached collection write locks with the cluster-wide ones,
+     * stored in Redis.
+     */
+    loadLocks(): Promise<void>;
+    /**
+     * Write-locks a collection cluster-wide: until it is unlocked, every action
+     * writing to it is rejected with `services.storage.collection_locked`, and
+     * reads are served as usual. Locking a collection again with the same owner
+     * refreshes the lock.
+     *
+     * The other nodes learn about the lock asynchronously (cluster sync): a write
+     * they accepted just before may still land.
+     *
+     * @throws If the collection does not exist, or is locked by another owner
+     */
+    lockCollection(index: string, collection: string, { owner, reason }: {
+        owner: string;
+        reason: string;
+    }): Promise<CollectionLock>;
+    /**
+     * Releases a collection write lock.
+     *
+     * @returns false if the collection was not locked
+     * @throws If the collection is locked by another owner
+     */
+    unlockCollection(index: string, collection: string, owner: string): Promise<boolean>;
+    private get locksKey();
+    private fetchLock;
+    /**
+     * @throws If `lock` is held by someone other than `owner`
+     */
+    private assertLockOwner;
     registerCollectionEvents(): void;
     registerIndexEvents(): void;
     registerDocumentEvents(): void;
     registerMappingEvents(): void;
+    registerLockEvents(): void;
     /**
      * Cache update operations. These events trigger neither any actual change
      * in the storage layer, nor kuzzle events.

package/dist/lib/core/storage/clientAdapter.js

@@ -49,6 +49,12 @@ const kerror = __importStar(require("../../kerror"));
 const mutex_1 = require("../../util/mutex"); // NOSONAR: see loadMappings
 require("../../types/Global");
 const servicesError = kerror.wrap("services", "storage");
+/**
+ * Redis hash holding the collection write locks of a storage scope, the
+ * cluster-wide source of truth that each node mirrors in its index cache.
+ * One field per locked collection: `JSON.stringify([index, collection])`.
+ */
+const LOCKS_KEY_PREFIX = "{core/storage}/collection-locks/";
 /** Hoisted out of the signature: an object literal as a default parameter is
  * re-allocated on every call, and this one is only ever read. */
 const DEFAULT_LOAD_MAPPINGS_OPTIONS = Object.freeze({
@@ -76,6 +82,11 @@ class ClientAdapter {
         this.registerDocumentEvents();
         this.registerMappingEvents();
         this.registerCacheEvents();
+        this.registerLockEvents();
+        // The locks were first loaded with the cache, before this node joined the
+        // cluster: one taken in between was broadcast before this node could hear
+        // it. Reading them again once the cluster is joined closes that gap.
+        global.kuzzle.onPipe("kuzzle:state:live", () => this.loadLocks());
         // Global store events registration
         /**
          * Manually refresh the index cache (e.g. after alias creation)
@@ -111,6 +122,8 @@ class ClientAdapter {
     }
     async createCollection(index, collection, opts, { indexCacheOnly = false, propagate = true } = {}) {
         if (!indexCacheOnly) {
+            // Creating an existing collection updates its mappings and settings
+            this.cache.assertCollectionWritable(index, collection);
             await this.client.createCollection(index, collection, opts);
         }
         this.cache.addCollection(index, collection);
@@ -124,6 +137,7 @@ class ClientAdapter {
     }
     async deleteIndex(index) {
         this.cache.assertIndexExists(index);
+        this.cache.assertIndexWritable(index);
         await this.client.deleteIndex(index);
         this.cache.removeIndex(index);
         global.kuzzle.emit("core:storage:index:delete:after", {
@@ -134,6 +148,7 @@ class ClientAdapter {
     async deleteIndexes(indexes) {
         for (const index of indexes) {
             this.cache.assertIndexExists(index);
+            this.cache.assertIndexWritable(index);
         }
         const deleted = await this.client.deleteIndexes(indexes);
         if (deleted.length > 0) {
@@ -149,6 +164,7 @@ class ClientAdapter {
     }
     async deleteCollection(index, collection) {
         this.cache.assertCollectionExists(index, collection);
+        this.cache.assertCollectionWritable(index, collection);
         await this.client.deleteCollection(index, collection);
         this.cache.removeCollection(index, collection);
         global.kuzzle.emit("core:storage:collection:delete:after", {
@@ -174,6 +190,88 @@ class ClientAdapter {
                 this.cache.addCollection(index, collection);
             }
         }
+        await this.loadLocks();
+    }
+    /**
+     * Replaces the cached collection write locks with the cluster-wide ones,
+     * stored in Redis.
+     */
+    async loadLocks() {
+        const fields = await global.kuzzle.ask("core:cache:internal:execute", "hgetall", this.locksKey);
+        this.cache.clearLocks();
+        for (const [field, value] of Object.entries(fields ?? {})) {
+            const [index, collection] = JSON.parse(field);
+            this.cache.setLock(index, collection, JSON.parse(value));
+        }
+    }
+    /**
+     * Write-locks a collection cluster-wide: until it is unlocked, every action
+     * writing to it is rejected with `services.storage.collection_locked`, and
+     * reads are served as usual. Locking a collection again with the same owner
+     * refreshes the lock.
+     *
+     * The other nodes learn about the lock asynchronously (cluster sync): a write
+     * they accepted just before may still land.
+     *
+     * @throws If the collection does not exist, or is locked by another owner
+     */
+    async lockCollection(index, collection, { owner, reason }) {
+        this.cache.assertCollectionExists(index, collection);
+        const field = JSON.stringify([index, collection]);
+        const lock = { lockedAt: Date.now(), owner, reason };
+        // Redis decides, not the local copy: two nodes locking the same collection
+        // at once must not both win.
+        const created = await global.kuzzle.ask("core:cache:internal:execute", "hsetnx", this.locksKey, field, JSON.stringify(lock));
+        if (created === 0) {
+            this.assertLockOwner(index, collection, await this.fetchLock(field), owner);
+            await global.kuzzle.ask("core:cache:internal:execute", "hset", this.locksKey, field, JSON.stringify(lock));
+        }
+        this.cache.setLock(index, collection, lock);
+        global.kuzzle.emit("core:storage:collection:lock:after", {
+            collection,
+            index,
+            lock,
+            scope: this.scope,
+        });
+        return lock;
+    }
+    /**
+     * Releases a collection write lock.
+     *
+     * @returns false if the collection was not locked
+     * @throws If the collection is locked by another owner
+     */
+    async unlockCollection(index, collection, owner) {
+        const field = JSON.stringify([index, collection]);
+        const current = await this.fetchLock(field);
+        if (current === null) {
+            this.cache.removeLock(index, collection);
+            return false;
+        }
+        this.assertLockOwner(index, collection, current, owner);
+        await global.kuzzle.ask("core:cache:internal:execute", "hdel", this.locksKey, field);
+        this.cache.removeLock(index, collection);
+        global.kuzzle.emit("core:storage:collection:unlock:after", {
+            collection,
+            index,
+            scope: this.scope,
+        });
+        return true;
+    }
+    get locksKey() {
+        return `${LOCKS_KEY_PREFIX}${this.scope}`;
+    }
+    async fetchLock(field) {
+        const value = await global.kuzzle.ask("core:cache:internal:execute", "hget", this.locksKey, field);
+        return value === null ? null : JSON.parse(value);
+    }
+    /**
+     * @throws If `lock` is held by someone other than `owner`
+     */
+    assertLockOwner(index, collection, lock, owner) {
+        if (lock !== null && lock.owner !== owner) {
+            throw servicesError.get("collection_locked", index, collection, lock.owner, lock.reason);
+        }
     }
     registerCollectionEvents() {
         /**
@@ -233,6 +331,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:collection:truncate`, (index, collection) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.truncateCollection(index, collection);
         });
         /**
@@ -244,6 +343,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:collection:update`, (index, collection, changes) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.updateCollection(index, collection, changes);
         });
     }
@@ -299,6 +399,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:bulk`, (index, collection, bulk, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.import(index, collection, bulk, opts);
         });
         /**
@@ -324,6 +425,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:create`, (index, collection, content, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.create(index, collection, content, opts);
         });
         /**
@@ -338,6 +440,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:createOrReplace`, (index, collection, id, content, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.createOrReplace(index, collection, id, content, opts);
         });
         /**
@@ -351,6 +454,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:delete`, (index, collection, id, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.delete(index, collection, id, opts);
         });
         /**
@@ -364,6 +468,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:deleteByQuery`, (index, collection, query, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.deleteByQuery(index, collection, query, opts);
         });
         /**
@@ -378,6 +483,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:deleteFields`, (index, collection, id, fields, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.deleteFields(index, collection, id, fields, opts);
         });
         /**
@@ -433,6 +539,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mCreate`, (index, collection, documents, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mCreate(index, collection, documents, opts);
         });
         /**
@@ -446,6 +553,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mCreateOrReplace`, (index, collection, documents, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mCreateOrReplace(index, collection, documents, opts);
         });
         /**
@@ -459,6 +567,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mDelete`, (index, collection, ids, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mDelete(index, collection, ids, opts);
         });
         /**
@@ -472,6 +581,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mReplace`, (index, collection, documents, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mReplace(index, collection, documents, opts);
         });
         /**
@@ -485,6 +595,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mUpdate`, (index, collection, documents, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mUpdate(index, collection, documents, opts);
         });
         /**
@@ -499,6 +610,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:mUpsert`, (index, collection, documents, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.mUpsert(index, collection, documents, opts);
         });
         /**
@@ -539,6 +651,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:replace`, (index, collection, id, content, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.replace(index, collection, id, content, opts);
         });
         /**
@@ -590,6 +703,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:update`, (index, collection, id, content, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.update(index, collection, id, content, opts);
         });
         /**
@@ -605,6 +719,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:updateByQuery`, (index, collection, query, changes, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.updateByQuery(index, collection, query, changes, opts);
         });
         /**
@@ -620,6 +735,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:bulk:updateByQuery`, (index, collection, query, changes, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.bulkUpdateByQuery(index, collection, query, changes, opts);
         });
         /**
@@ -635,6 +751,7 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:document:upsert`, (index, collection, id, content, opts) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.upsert(index, collection, id, content, opts);
         });
     }
@@ -671,9 +788,37 @@ class ClientAdapter {
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:mappings:update`, (index, collection, mappings) => {
             this.cache.assertCollectionExists(index, collection);
+            this.cache.assertCollectionWritable(index, collection);
             return this.client.updateMapping(index, collection, mappings);
         });
     }
+    registerLockEvents() {
+        /**
+         * Write-lock a collection, cluster-wide
+         * @param {string} index
+         * @param {string} collection
+         * @param {Object} options -- { owner, reason }
+         * @returns {Promise.<{ owner, reason, lockedAt }>}
+         * @throws If the collection does not exist, or is locked by another owner
+         */
+        global.kuzzle.onAsk(`core:storage:${this.scope}:collection:lock`, (index, collection, options) => this.lockCollection(index, collection, options));
+        /**
+         * Release a collection write lock
+         * @param {string} index
+         * @param {string} collection
+         * @param {string} owner
+         * @returns {Promise.<boolean>} false if the collection was not locked
+         * @throws If the collection is locked by another owner
+         */
+        global.kuzzle.onAsk(`core:storage:${this.scope}:collection:unlock`, (index, collection, owner) => this.unlockCollection(index, collection, owner));
+        /**
+         * Return a collection write lock
+         * @param {string} index
+         * @param {string} collection
+         * @returns {{ owner, reason, lockedAt }|null}
+         */
+        global.kuzzle.onAsk(`core:storage:${this.scope}:collection:lock:get`, (index, collection) => this.cache.getLock(index, collection));
+    }
     /**
      * Cache update operations. These events trigger neither any actual change
      * in the storage layer, nor kuzzle events.
@@ -705,6 +850,19 @@ class ClientAdapter {
          * @param  {string} collection
          */
         global.kuzzle.onAsk(`core:storage:${this.scope}:cache:removeCollection`, (index, collection) => this.cache.removeCollection(index, collection));
+        /**
+         * Caches a collection write lock taken on another node
+         * @param  {string} index
+         * @param  {string} collection
+         * @param  {Object} lock -- { owner, reason, lockedAt }
+         */
+        global.kuzzle.onAsk(`core:storage:${this.scope}:cache:setLock`, (index, collection, lock) => this.cache.setLock(index, collection, lock));
+        /**
+         * Removes a collection write lock released on another node
+         * @param  {string} index
+         * @param  {string} collection
+         */
+        global.kuzzle.onAsk(`core:storage:${this.scope}:cache:removeLock`, (index, collection) => this.cache.removeLock(index, collection));
     }
     /**
      * Load database fixtures into Kuzzle
@@ -725,6 +883,7 @@ class ClientAdapter {
             }
             for (const [collection, payload] of Object.entries(collections)) {
                 this.cache.assertCollectionExists(index, collection);
+                this.cache.assertCollectionWritable(index, collection);
                 const { errors } = await this.client.import(index, collection, payload, { refresh });
                 if (errors.length > 0) {
                     throw servicesError.get("import_failed", errors);

package/dist/lib/core/storage/indexCache.d.ts

@@ -1,11 +1,30 @@
+/**
+ * A collection write lock: while it is held, the storage layer rejects every
+ * action writing to the collection, and serves reads as usual.
+ */
+export interface CollectionLock {
+    /** Who holds the lock (e.g. a plugin name), the only one who can release it */
+    owner: string;
+    /** Why the collection is locked, quoted in the error writers receive */
+    reason: string;
+    /** Lock timestamp (Epoch-millis) */
+    lockedAt: number;
+}
 export declare class IndexCache {
     /**
      * Index map: each entry holds a set of collection names
      *
      * Map<index, Set<collection>>
      */
-    private indexes;
-    constructor();
+    private readonly indexes;
+    /**
+     * Collection write locks, a local copy of the cluster-wide state (see
+     * `ClientAdapter`): checking a lock on every write must not cost a round
+     * trip to Redis.
+     *
+     * Map<index, Map<collection, CollectionLock>>
+     */
+    private readonly locks;
     /**
      * Cache a new index
      *
@@ -60,4 +79,32 @@ export declare class IndexCache {
      * Assert that the provided index and collection exist
      */
     assertCollectionExists(index: string, collection: string): void;
+    /**
+     * Cache a collection write lock, replacing the one it may already hold
+     */
+    setLock(index: string, collection: string, lock: CollectionLock): void;
+    /**
+     * Remove a collection write lock from the cache
+     */
+    removeLock(index: string, collection: string): void;
+    /**
+     * Remove every cached collection write lock
+     */
+    clearLocks(): void;
+    /**
+     * Return a collection write lock, or null if the collection is not locked
+     */
+    getLock(index: string, collection: string): CollectionLock | null;
+    /**
+     * Assert that the provided collection is not write-locked
+     *
+     * @throws If the collection is locked
+     */
+    assertCollectionWritable(index: string, collection: string): void;
+    /**
+     * Assert that none of the provided index collections is write-locked
+     *
+     * @throws If one of the index collections is locked
+     */
+    assertIndexWritable(index: string): void;
 }

package/dist/lib/core/storage/indexCache.js

@@ -54,7 +54,14 @@ class IndexCache {
          * Map<index, Set<collection>>
          */
         this.indexes = new Map();
-        this.indexes = new Map();
+        /**
+         * Collection write locks, a local copy of the cluster-wide state (see
+         * `ClientAdapter`): checking a lock on every write must not cost a round
+         * trip to Redis.
+         *
+         * Map<index, Map<collection, CollectionLock>>
+         */
+        this.locks = new Map();
     }
     /**
      * Cache a new index
@@ -150,6 +157,66 @@ class IndexCache {
             throw storageError.get("unknown_collection", index, collection);
         }
     }
+    /**
+     * Cache a collection write lock, replacing the one it may already hold
+     */
+    setLock(index, collection, lock) {
+        let collections = this.locks.get(index);
+        if (collections === undefined) {
+            collections = new Map();
+            this.locks.set(index, collections);
+        }
+        collections.set(collection, lock);
+    }
+    /**
+     * Remove a collection write lock from the cache
+     */
+    removeLock(index, collection) {
+        const collections = this.locks.get(index);
+        if (collections) {
+            collections.delete(collection);
+            if (collections.size === 0) {
+                this.locks.delete(index);
+            }
+        }
+    }
+    /**
+     * Remove every cached collection write lock
+     */
+    clearLocks() {
+        this.locks.clear();
+    }
+    /**
+     * Return a collection write lock, or null if the collection is not locked
+     */
+    getLock(index, collection) {
+        return this.locks.get(index)?.get(collection) ?? null;
+    }
+    /**
+     * Assert that the provided collection is not write-locked
+     *
+     * @throws If the collection is locked
+     */
+    assertCollectionWritable(index, collection) {
+        const lock = this.getLock(index, collection);
+        if (lock !== null) {
+            throw storageError.get("collection_locked", index, collection, lock.owner, lock.reason);
+        }
+    }
+    /**
+     * Assert that none of the provided index collections is write-locked
+     *
+     * @throws If one of the index collections is locked
+     */
+    assertIndexWritable(index) {
+        const collections = this.locks.get(index);
+        if (collections === undefined) {
+            return;
+        }
+        for (const collection of collections.keys()) {
+            this.assertCollectionWritable(index, collection);
+        }
+    }
 }
 exports.IndexCache = IndexCache;
 //# sourceMappingURL=indexCache.js.map

package/dist/lib/kerror/codes/1-services.json

@@ -293,6 +293,12 @@
                     "message": "Attempt to recreate an existing collection %s of index %s of scope %s with non matching static setting : %s at %s while existing one is at %s",
                     "code": 51,
                     "class": "BadRequestError"
+                },
+                "collection_locked": {
+                    "description": "The collection is locked against writes, typically during a maintenance operation such as a mapping migration. Reads are still served: retry the write once the lock is released",
+                    "message": "The collection \"%s\":\"%s\" is locked by \"%s\" (%s): write actions are rejected until it is unlocked.",
+                    "code": 52,
+                    "class": "ServiceUnavailableError"
                 }
             }
         },

package/dist/lib/service/storage/8/elasticsearch.d.ts

@@ -877,6 +877,10 @@ export declare class ES8 {
      * applies, which is what a row without one used to throw on.
      */
     _catAliases(name?: string): Promise<CatAliasRecord[]>;
+    /**
+     * Returns the indices marked with `UNMANAGED_INDICE_ALIAS`.
+     */
+    _listUnmanagedIndices(): Promise<Set<string>>;
     /**
      * Check for each indice whether it has an alias or not.
      * When the latter is missing, create one based on the indice name.

package/dist/lib/service/storage/8/elasticsearch.js

@@ -79,6 +79,14 @@ const PUBLIC_PREFIX = "&";
 const INDEX_PREFIX_POSITION_IN_INDICE = 0;
 const INDEX_PREFIX_POSITION_IN_ALIAS = 1;
 const NAME_SEPARATOR = ".";
+/**
+ * Marks an indice the core must leave alone: neither given a missing alias
+ * (`generateMissingAliases`) nor counted in the storage stats. Set by tools
+ * building a collection's next indice beside it (e.g. a mapping migration).
+ * It sits outside the `@&` / `@%` alias convention, so every alias reader
+ * already ignores it.
+ */
+const UNMANAGED_INDICE_ALIAS = "kuzzle-unmanaged";
 const FORBIDDEN_CHARS = `\\/*?"<>| \t\r\n,+#:${NAME_SEPARATOR}${PUBLIC_PREFIX}${PRIVATE_PREFIX}`;
 const DYNAMIC_PROPERTY_VALUES = ["true", "false", "strict"];
 // used to check whether we need to wait for ES to initialize or not
@@ -211,13 +219,15 @@ class ES8 {
             metric: ["docs", "store"],
         };
         const stats = await this._client.indices.stats(esRequest);
+        const unmanaged = await this._listUnmanagedIndices();
         const indexes = {};
         let size = 0;
         for (const [indice, indiceInfo] of Object.entries(stats.indices ?? {})) {
             const infos = indiceInfo;
-            // Ignore non-Kuzzle indices
-            if (!indice.startsWith(PRIVATE_PREFIX) &&
-                !indice.startsWith(PUBLIC_PREFIX)) {
+            // Ignore non-Kuzzle indices, and the ones Kuzzle must leave alone
+            if ((!indice.startsWith(PRIVATE_PREFIX) &&
+                !indice.startsWith(PUBLIC_PREFIX)) ||
+                unmanaged.has(indice)) {
                 continue;
             }
             const aliases = await this._getAliasFromIndice(indice);
@@ -2547,6 +2557,15 @@ class ES8 {
             index: index ?? "",
         }));
     }
+    /**
+     * Returns the indices marked with `UNMANAGED_INDICE_ALIAS`.
+     */
+    async _listUnmanagedIndices() {
+        const body = await this._catAliases();
+        return new Set(body
+            .filter(({ alias }) => alias === UNMANAGED_INDICE_ALIAS)
+            .map(({ index }) => index));
+    }
     /**
      * Check for each indice whether it has an alias or not.
      * When the latter is missing, create one based on the indice name.
@@ -2559,7 +2578,9 @@ class ES8 {
             const body = await this._client.cat.indices({ format: "json" });
             const indices = body.flatMap(({ index: indice }) => indice === undefined ? [] : [indice]);
             const aliases = await this.listAliases();
+            const unmanaged = await this._listUnmanagedIndices();
             const indicesWithoutAlias = indices.filter((indice) => indice[INDEX_PREFIX_POSITION_IN_INDICE] === this._indexPrefix &&
+                !unmanaged.has(indice) &&
                 !aliases.some((alias) => alias.indice === indice));
             const esRequest = {
                 body: { actions: [] },

package/dist/lib/types/Policy.d.ts

@@ -3,6 +3,12 @@ import type { PolicyRestrictions, OptimizedPolicyRestrictions } from "./PolicyRe
  * Policy definition for a role
  * and its restrictions
  *
+ * The same policy as the API contract's `ProfilePolicy`, typed differently on
+ * purpose: `ProfilePolicy.restrictedTo` is a one-element tuple and leaves
+ * `collections` optional; here it is a list of any length and
+ * `PolicyRestrictions.collections` is required. Kept apart, since aligning
+ * either one would stop code written against it from compiling.
+ *
  * @example
  * {
  *   "roleId": "admin",

package/dist/lib/types/RoleDefinition.d.ts

@@ -1,5 +1,7 @@
+import type { RoleRightsDefinition } from "kuzzle-types";
 /**
- * A role definition
+ * A role definition: its rights, under `controllers`, in the shape of the API
+ * contract's `RoleRightsDefinition`
  *
  * @see https://docs.kuzzle.io/core/2/guides/main-concepts/permissions/#roles
  *
@@ -17,11 +19,5 @@
  * }
  */
 export type RoleDefinition = {
-    controllers: {
-        [controllerName: string]: {
-            actions: {
-                [actionName: string]: boolean;
-            };
-        };
-    };
+    controllers: RoleRightsDefinition;
 };

package/dist/lib/types/storage/7/Elasticsearch.d.ts

@@ -1,5 +1,6 @@
 import type { ByteSize, ClusterNodesStats } from "sdk-es7/api/types";
 import type { JSONObject } from "../../JSONObject";
+export type { KRequestBody, KuzzleInfo } from "../KuzzleInfo";
 export type InfoResult = {
     type: string;
     version: string;
@@ -8,27 +9,6 @@ export type InfoResult = {
     spaceUsed?: ByteSize;
     nodes?: ClusterNodesStats;
 };
-/**
- * Kuzzle's own metadata, stored alongside every document it writes.
- *
- * `author` and `updater` are kuids, and `getKuid` answers `null` for an
- * anonymous write — so both are nullable, as is `updatedAt` on a document that
- * has only ever been created.
- */
-export type KuzzleInfo = {
-    author: string | null;
-    createdAt: number;
-    updatedAt: number | null;
-    updater: string | null;
-};
-/**
- * `_kuzzle_info` is `Partial` because a partial update writes only the two
- * fields it owns (`updatedAt`, `updater`) and leaves the creation pair to the
- * document already in the index.
- */
-export type KRequestBody<T> = T & {
-    _kuzzle_info?: Partial<KuzzleInfo>;
-};
 export type { JSONObject } from "../../JSONObject";
 export type KImportError = {
     _id?: string | null;

package/dist/lib/types/storage/8/Elasticsearch.d.ts

@@ -1,5 +1,6 @@
 import type { estypes } from "sdk-es8";
 import type { JSONObject } from "../../JSONObject";
+export type { KRequestBody, KuzzleInfo } from "../KuzzleInfo";
 export type InfoResult = {
     type: string;
     version: string;
@@ -30,27 +31,6 @@ export type KStats = {
     indexes: KStatsIndex[];
     size: estypes.ByteSize;
 };
-/**
- * Kuzzle's own metadata, stored alongside every document it writes.
- *
- * `author` and `updater` are kuids, and `getKuid` answers `null` for an
- * anonymous write — so both are nullable, as is `updatedAt` on a document that
- * has only ever been created.
- */
-export type KuzzleInfo = {
-    author: string | null;
-    createdAt: number;
-    updatedAt: number | null;
-    updater: string | null;
-};
-/**
- * `_kuzzle_info` is `Partial` because a partial update writes only the two
- * fields it owns (`updatedAt`, `updater`) and leaves the creation pair to the
- * document already in the index.
- */
-export type KRequestBody<T> = T & {
-    _kuzzle_info?: Partial<KuzzleInfo>;
-};
 export type { JSONObject } from "../../JSONObject";
 export type KImportError = {
     _id?: string | null;

package/dist/lib/types/storage/KuzzleInfo.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Kuzzle's own metadata, stored alongside every document it writes.
+ *
+ * `author` and `updater` are kuids, and `getKuid` answers `null` for an
+ * anonymous write — so both are nullable, as is `updatedAt` on a document that
+ * has only ever been created.
+ *
+ * Wider than the API contract's `KDocumentKuzzleInfo`, whose `author` is a
+ * `string`: that type describes what a client is handed, this one what the
+ * storage layer may write. Kept apart on purpose.
+ */
+export type KuzzleInfo = {
+    author: string | null;
+    createdAt: number;
+    updatedAt: number | null;
+    updater: string | null;
+};
+/**
+ * `_kuzzle_info` is `Partial` because a partial update writes only the two
+ * fields it owns (`updatedAt`, `updater`) and leaves the creation pair to the
+ * document already in the index.
+ */
+export type KRequestBody<T> = T & {
+    _kuzzle_info?: Partial<KuzzleInfo>;
+};

package/dist/lib/types/storage/KuzzleInfo.js

@@ -0,0 +1,5 @@
+"use strict";
+// Shared by the Elasticsearch 7 and 8 storage types, which re-export both
+// under the names they have always exported.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=KuzzleInfo.js.map

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "kuzzle",
     "author": "The Kuzzle Team <support@kuzzle.io>",
-    "version": "2.58.0",
+    "version": "2.59.0",
     "description": "Kuzzle is an open-source solution that handles all the data management through a secured API, with a large choice of protocols.",
     "scripts": {
         "build": "rm -Rf ./dist && tsc && node -r ts-node/register/transpile-only ./bin/copy-binaries.ts",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kuzzle",
   "author": "The Kuzzle Team <support@kuzzle.io>",
-  "version": "2.58.0",
+  "version": "2.59.0",
   "description": "Kuzzle is an open-source solution that handles all the data management through a secured API, with a large choice of protocols.",
   "scripts": {
     "build": "rm -Rf ./dist && tsc && node -r ts-node/register/transpile-only ./bin/copy-binaries.ts",