@directus/api 32.2.0 → 33.1.0

package/dist/websocket/collab/permissions-cache.js

@@ -0,0 +1,204 @@
+import { useEnv } from '@directus/env';
+import { LRUMapWithDelete } from 'mnemonist';
+import { useBus } from '../../bus/index.js';
+import { IRRELEVANT_COLLECTIONS } from './constants.js';
+const env = useEnv();
+/**
+ * Caches permission check results for collaborative editing clients.
+ * Supports granular invalidation based on collection, item, and relational dependencies.
+ */
+export class PermissionCache {
+    cache;
+    tags = new Map();
+    keyTags = new Map();
+    timers = new Map();
+    bus = useBus();
+    invalidationCount = 0;
+    constructor(maxSize) {
+        this.cache = new LRUMapWithDelete(maxSize);
+        this.bus.subscribe('websocket.event', (event) => {
+            this.handleInvalidation(event);
+        });
+    }
+    /**
+     * Used for race condition protection during async permission fetches.
+     */
+    getInvalidationCount() {
+        return this.invalidationCount;
+    }
+    /**
+     * Clears entire cache for system collections, or performs granular invalidation for user data.
+     */
+    handleInvalidation(event) {
+        const { collection, keys, key } = event;
+        const items = keys || (key ? [key] : []);
+        const affectedKeys = new Set();
+        // System Invalidation (Roles, Permissions, Policies, Schema)
+        if ([
+            'directus_roles',
+            'directus_permissions',
+            'directus_policies',
+            'directus_access',
+            'directus_fields',
+            'directus_relations',
+            'directus_collections',
+        ].includes(collection)) {
+            this.clear();
+            return;
+        }
+        // Skip known high-traffic collections
+        if (IRRELEVANT_COLLECTIONS.includes(collection)) {
+            return;
+        }
+        this.invalidationCount++;
+        // Prevent overflow issues in long-running processes
+        if (this.invalidationCount >= Number.MAX_SAFE_INTEGER) {
+            this.invalidationCount = 1;
+        }
+        // Skip if no keys are watching
+        if (!this.tags.has(`collection:${collection}`) &&
+            !this.tags.has(`dependency:${collection}`) &&
+            !this.tags.has(`collection-dependency:${collection}`)) {
+            return;
+        }
+        // Collection-level Invalidation
+        if (items.length === 0 && this.tags.has(`collection:${collection}`)) {
+            for (const k of this.tags.get(`collection:${collection}`))
+                affectedKeys.add(k);
+        }
+        // Item-level Invalidation
+        for (const id of items) {
+            const tag = `item:${collection}:${id}`;
+            if (this.tags.has(tag)) {
+                for (const k of this.tags.get(tag))
+                    affectedKeys.add(k);
+            }
+        }
+        // Dependency Invalidation (Items + Relational)
+        const depTags = [`dependency:${collection}`];
+        if (items.length > 0) {
+            for (const id of items) {
+                depTags.push(`dependency:${collection}:${id}`);
+            }
+        }
+        else {
+            depTags.push(`collection-dependency:${collection}`);
+        }
+        for (const tag of depTags) {
+            if (this.tags.has(tag)) {
+                for (const k of this.tags.get(tag))
+                    affectedKeys.add(k);
+            }
+        }
+        for (const k of affectedKeys) {
+            this.invalidateKey(k);
+        }
+    }
+    /**
+     * Get cached allowed fields for a given accountability and collection/item.
+     * LRUMap automatically updates access order on get().
+     */
+    get(accountability, collection, item, action) {
+        const key = this.getCacheKey(accountability, collection, item, action);
+        return this.cache.get(key);
+    }
+    /**
+     * Store allowed fields in the cache with optional TTL and dependencies.
+     */
+    set(accountability, collection, item, action, fields, dependencies = [], ttlMs) {
+        const key = this.getCacheKey(accountability, collection, item, action);
+        // Clear existing timer if any
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+            this.timers.delete(key);
+        }
+        // Clean up metadata for LRU eviction if at capacity
+        // LRUMapWithDelete auto-evicts, but we need to clean up our tag mappings
+        if (!this.cache.has(key) && this.cache.size >= this.cache.capacity) {
+            const lruKey = this.cache.keys().next().value;
+            if (lruKey) {
+                this.cleanupKeyMetadata(lruKey);
+            }
+        }
+        this.cache.set(key, fields);
+        if (ttlMs) {
+            const timer = setTimeout(() => {
+                this.invalidateKey(key);
+            }, ttlMs);
+            this.timers.set(key, timer);
+        }
+        // Always tag the specific item
+        this.addTag(key, `item:${collection}:${item}`);
+        // Always tag the collection to cover batch updates
+        this.addTag(key, `collection:${collection}`);
+        // Add custom dependencies such as relational collections
+        for (const dep of dependencies) {
+            this.addTag(key, `dependency:${dep}`);
+            if (dep.includes(':')) {
+                const [dependencyCollection] = dep.split(':');
+                this.addTag(key, `collection-dependency:${dependencyCollection}`);
+            }
+        }
+    }
+    /**
+     * Called before LRU eviction or explicit invalidation to prevent orphaned metadata.
+     */
+    cleanupKeyMetadata(key) {
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+            this.timers.delete(key);
+        }
+        const tags = this.keyTags.get(key);
+        if (tags) {
+            for (const tag of tags) {
+                const keys = this.tags.get(tag);
+                if (keys) {
+                    keys.delete(key);
+                    if (keys.size === 0)
+                        this.tags.delete(tag);
+                }
+            }
+            this.keyTags.delete(key);
+        }
+    }
+    /**
+     * Maintains bidirectional mappings: tag → keys and key → tags.
+     */
+    addTag(key, tag) {
+        if (!this.tags.has(tag)) {
+            this.tags.set(tag, new Set());
+        }
+        this.tags.get(tag).add(key);
+        if (!this.keyTags.has(key)) {
+            this.keyTags.set(key, new Set());
+        }
+        this.keyTags.get(key).add(tag);
+    }
+    /**
+     * Cleans up metadata first, then removes from cache.
+     */
+    invalidateKey(key) {
+        this.cleanupKeyMetadata(key);
+        this.cache.delete(key);
+    }
+    /**
+     * Cache key format: user:collection:item:action
+     */
+    getCacheKey(accountability, collection, item, action) {
+        return `${accountability.user || 'public'}:${collection}:${item || 'singleton'}:${action}`;
+    }
+    /**
+     * Clear the entire cache.
+     */
+    clear() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.cache.clear();
+        this.tags.clear();
+        this.keyTags.clear();
+        this.invalidationCount++;
+    }
+}
+export const permissionCache = new PermissionCache(Number(env['WEBSOCKETS_COLLAB_PERMISSIONS_CACHE_CAPACITY'] ?? 2000));

package/dist/websocket/collab/room.d.ts

@@ -0,0 +1,125 @@
+import { type Accountability, type Item, type PrimaryKey, type WebSocketClient } from '@directus/types';
+import { type BaseServerMessage, type ClientID, type Color, type ServerError } from '@directus/types/collab';
+import { Messenger } from './messenger.js';
+import type { JoinMessage, PermissionClient } from './types.js';
+/**
+ * Store and manage all active collaborative editing rooms
+ */
+export declare class RoomManager {
+    rooms: Record<string, Room>;
+    messenger: Messenger;
+    constructor(messenger?: Messenger);
+    /**
+     * Create a new collaborative editing room or return an existing one matching collection, item and version.
+     */
+    createRoom(collection: string, item: PrimaryKey | null, version: string | null, initialChanges?: Item): Promise<Room>;
+    /**
+     * Remove a room from local memory
+     */
+    removeRoom(uid: string): void;
+    /**
+     * Get an existing room by UID.
+     * If the room is not part of the local rooms, it will be loaded from shared memory.
+     * The room will not be persisted in local memory.
+     */
+    getRoom(uid: string): Promise<Room | undefined>;
+    /**
+     * Get all rooms a client is currently in from local memory
+     */
+    getClientRooms(uid: ClientID): Promise<Room[]>;
+    /**
+     * Returns all clients that are part of a room in the local memory
+     */
+    getLocalRoomClients(): Promise<RoomClient[]>;
+    /**
+     * Remove empty rooms from local memory
+     */
+    cleanupRooms(uids?: string[]): Promise<void>;
+    /**
+     * Forcefully close all local rooms and notify clients.
+     */
+    terminateAll(): Promise<void>;
+}
+type RoomClient = {
+    uid: ClientID;
+    accountability: Accountability;
+    color: Color;
+};
+type RoomData = {
+    uid: string;
+    collection: string;
+    item: PrimaryKey | null;
+    version: string | null;
+    changes: Item;
+    clients: RoomClient[];
+    focuses: Record<ClientID, string>;
+};
+/**
+ * Represents a single collaborative editing room for a specific item
+ */
+export declare class Room {
+    uid: string;
+    collection: string;
+    item: PrimaryKey | null;
+    version: string | null;
+    initialChanges: Item | undefined;
+    messenger: Messenger;
+    store: <T>(callback: (store: import("./store.js").RedisStore<RoomData>) => Promise<T>) => Promise<T>;
+    onUpdateHandler: (meta: Record<string, any>, context?: any) => Promise<void>;
+    onDeleteHandler: (meta: Record<string, any>, context?: any) => Promise<void>;
+    constructor(uid: string, collection: string, item: PrimaryKey | null, version: string | null, initialChanges?: Item, messenger?: Messenger);
+    /**
+     * Ensures that foundational room state (metadata) exists in shared memory even after restarts
+     */
+    ensureInitialized(): Promise<void>;
+    getDisplayName(): string;
+    getClients(): Promise<RoomClient[]>;
+    getFocuses(): Promise<Record<ClientID, string>>;
+    getChanges(): Promise<Item>;
+    hasClient(id: ClientID): Promise<boolean>;
+    getFocusByUser(id: ClientID): Promise<string | undefined>;
+    getFocusByField(field: string): Promise<string | undefined>;
+    /**
+     * Client requesting to join a room. If the client hasn't entered the room already, add a new client.
+     * Otherwise all users just will be informed again that the user has joined.
+     */
+    join(client: WebSocketClient, color?: JoinMessage['color']): Promise<void>;
+    /**
+     * Leave the room
+     */
+    leave(uid: ClientID): Promise<void>;
+    /**
+     * Propagate an update to other clients
+     */
+    update(sender: WebSocketClient, changes: Record<string, unknown>): Promise<void>;
+    /**
+     * Propagate an unset to other clients
+     */
+    unset(sender: PermissionClient, field: string): Promise<void>;
+    /**
+     * Discard specified changes in the room and propagate to other clients
+     */
+    discard(fields: string[]): Promise<void>;
+    /**
+     * Atomically acquire or release focus and propagate focus state to other clients
+     */
+    focus(sender: PermissionClient, field: string | null): Promise<boolean>;
+    sendAll(message: BaseServerMessage): Promise<void>;
+    sendExcluding(message: BaseServerMessage, exclude: ClientID): Promise<void>;
+    send(client: ClientID, message: BaseServerMessage): void;
+    /**
+     * Close the room and clean up shared state
+     *
+     * @param options.force If true, close the room even if active clients are present
+     * @param options.reason Optional reason to be sent to clients
+     * @param options.terminate If true, forcefully terminate the client connection after closing
+     */
+    close(options?: {
+        force?: boolean;
+        reason?: ServerError;
+        terminate?: boolean;
+    }): Promise<boolean>;
+    dispose(): void;
+}
+export declare function getRoomHash(collection: string, item: PrimaryKey | null, version: string | null): string;
+export {};