@directus/api 11.0.1 → 11.1.0

package/dist/websocket/controllers/graphql.js

@@ -0,0 +1,102 @@
+import { CloseCode, MessageType, makeServer } from 'graphql-ws';
+import env from '../../env.js';
+import logger from '../../logger.js';
+import { bindPubSub } from '../../services/graphql/subscription.js';
+import { GraphQLService } from '../../services/index.js';
+import { getSchema } from '../../utils/get-schema.js';
+import { authenticateConnection, refreshAccountability } from '../authenticate.js';
+import { handleWebSocketException } from '../exceptions.js';
+import { ConnectionParams, WebSocketMessage } from '../messages.js';
+import { getMessageType } from '../utils/message.js';
+import SocketController from './base.js';
+export class GraphQLSubscriptionController extends SocketController {
+    gql;
+    constructor(httpServer) {
+        super(httpServer, 'WEBSOCKETS_GRAPHQL');
+        this.server.on('connection', (ws, auth) => {
+            this.bindEvents(this.createClient(ws, auth));
+        });
+        this.gql = makeServer({
+            schema: async (ctx) => {
+                const accountability = ctx.extra.client.accountability;
+                // for now only the items will be watched, system events tbd
+                const service = new GraphQLService({
+                    schema: await getSchema(),
+                    scope: 'items',
+                    accountability,
+                });
+                return service.getSchema();
+            },
+        });
+        bindPubSub();
+        logger.info(`GraphQL Subscriptions started at ws://${env['HOST']}:${env['PORT']}${this.endpoint}`);
+    }
+    bindEvents(client) {
+        const closedHandler = this.gql.opened({
+            protocol: client.protocol,
+            send: (data) => new Promise((resolve, reject) => {
+                client.send(data, (err) => (err ? reject(err) : resolve()));
+            }),
+            close: (code, reason) => client.close(code, reason),
+            onMessage: (cb) => {
+                client.on('parsed-message', async (message) => {
+                    try {
+                        if (getMessageType(message) === 'connection_init' && this.authentication.mode !== 'strict') {
+                            const params = ConnectionParams.parse(message['payload'] ?? {});
+                            if (this.authentication.mode === 'handshake') {
+                                if (typeof params.access_token === 'string') {
+                                    const { accountability, expires_at } = await authenticateConnection({
+                                        access_token: params.access_token,
+                                    });
+                                    client.accountability = accountability;
+                                    client.expires_at = expires_at;
+                                }
+                                else {
+                                    client.close(CloseCode.Forbidden, 'Forbidden');
+                                    return;
+                                }
+                            }
+                        }
+                        else if (this.authentication.mode === 'handshake' && !client.accountability?.user) {
+                            // the first message should authenticate successfully in this mode
+                            client.close(CloseCode.Forbidden, 'Forbidden');
+                            return;
+                        }
+                        else {
+                            client.accountability = await refreshAccountability(client.accountability);
+                        }
+                        await cb(JSON.stringify(message));
+                    }
+                    catch (error) {
+                        handleWebSocketException(client, error, MessageType.Error);
+                    }
+                });
+            },
+        }, { client });
+        // notify server that the socket closed
+        client.once('close', (code, reason) => closedHandler(code, reason.toString()));
+        // check strict authentication status
+        if (this.authentication.mode === 'strict' && !client.accountability?.user) {
+            client.close(CloseCode.Forbidden, 'Forbidden');
+        }
+    }
+    setTokenExpireTimer(client) {
+        if (client.auth_timer !== null) {
+            clearTimeout(client.auth_timer);
+            client.auth_timer = null;
+        }
+        if (this.authentication.mode !== 'handshake')
+            return;
+        client.auth_timer = setTimeout(() => {
+            if (!client.accountability?.user) {
+                client.close(CloseCode.Forbidden, 'Forbidden');
+            }
+        }, this.authentication.timeout);
+    }
+    async handleHandshakeUpgrade({ request, socket, head }) {
+        this.server.handleUpgrade(request, socket, head, async (ws) => {
+            this.server.emit('connection', ws, { accountability: null, expires_at: null });
+            // actual enforcement is handled by the setTokenExpireTimer function
+        });
+    }
+}

package/dist/websocket/controllers/hooks.d.ts

@@ -0,0 +1 @@
+export declare function registerWebSocketEvents(): void;

package/dist/websocket/controllers/hooks.js

@@ -0,0 +1,122 @@
+import emitter from '../../emitter.js';
+import { getMessenger } from '../../messenger.js';
+let actionsRegistered = false;
+export function registerWebSocketEvents() {
+    if (actionsRegistered)
+        return;
+    actionsRegistered = true;
+    registerActionHooks([
+        'items',
+        'activity',
+        'collections',
+        'folders',
+        'permissions',
+        'presets',
+        'revisions',
+        'roles',
+        'settings',
+        'users',
+        'webhooks',
+    ]);
+    registerFieldsHooks();
+    registerFilesHooks();
+    registerRelationsHooks();
+}
+function registerActionHooks(modules) {
+    // register event hooks that can be handled in an uniform manner
+    for (const module of modules) {
+        registerAction(module + '.create', ({ key, collection, payload = {} }) => ({
+            collection,
+            action: 'create',
+            key,
+            payload,
+        }));
+        registerAction(module + '.update', ({ keys, collection, payload = {} }) => ({
+            collection,
+            action: 'update',
+            keys,
+            payload,
+        }));
+        registerAction(module + '.delete', ({ keys, collection, payload = [] }) => ({
+            collection,
+            action: 'delete',
+            keys,
+            payload,
+        }));
+    }
+}
+function registerFieldsHooks() {
+    // exception for field hooks that don't report `directus_fields` as being the collection
+    registerAction('fields.create', ({ key, payload = {} }) => ({
+        collection: 'directus_fields',
+        action: 'create',
+        key,
+        payload,
+    }));
+    registerAction('fields.update', ({ keys, payload = {} }) => ({
+        collection: 'directus_fields',
+        action: 'update',
+        keys,
+        payload,
+    }));
+    registerAction('fields.delete', ({ keys, payload = [] }) => ({
+        collection: 'directus_fields',
+        action: 'delete',
+        keys,
+        payload,
+    }));
+}
+function registerFilesHooks() {
+    // extra event for file uploads that doubles as create event
+    registerAction('files.upload', ({ key, collection, payload = {} }) => ({
+        collection,
+        action: 'create',
+        key,
+        payload,
+    }));
+    registerAction('files.update', ({ keys, collection, payload = {} }) => ({
+        collection,
+        action: 'update',
+        keys,
+        payload,
+    }));
+    registerAction('files.delete', ({ keys, collection, payload = [] }) => ({
+        collection,
+        action: 'delete',
+        keys,
+        payload,
+    }));
+}
+function registerRelationsHooks() {
+    // exception for relation hooks that don't report `directus_relations` as being the collection
+    registerAction('relations.create', ({ key, payload = {} }) => ({
+        collection: 'directus_relations',
+        action: 'create',
+        key,
+        payload: { ...payload, key },
+    }));
+    registerAction('relations.update', ({ keys, payload = {} }) => ({
+        collection: 'directus_relations',
+        action: 'update',
+        keys,
+        payload,
+    }));
+    registerAction('relations.delete', ({ collection, payload = [] }) => ({
+        collection: 'directus_relations',
+        action: 'delete',
+        keys: payload,
+        payload: { collection, fields: payload },
+    }));
+}
+/**
+ * Wrapper for emitter.onAction to hook into system events
+ * @param event The action event to watch
+ * @param transform Transformer function
+ */
+function registerAction(event, transform) {
+    const messenger = getMessenger();
+    emitter.onAction(event, async (data) => {
+        // push the event through the Redis pub/sub
+        messenger.publish('websocket.event', transform(data));
+    });
+}

package/dist/websocket/controllers/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" resolution-mode="require"/>
+import type { Server as httpServer } from 'http';
+import { GraphQLSubscriptionController } from './graphql.js';
+import { WebSocketController } from './rest.js';
+export declare function createWebSocketController(server: httpServer): void;
+export declare function getWebSocketController(): WebSocketController;
+export declare function createSubscriptionController(server: httpServer): void;
+export declare function getSubscriptionController(): GraphQLSubscriptionController | undefined;
+export * from './graphql.js';
+export * from './rest.js';

package/dist/websocket/controllers/index.js

@@ -0,0 +1,35 @@
+import env from '../../env.js';
+import { ServiceUnavailableException } from '../../index.js';
+import { toBoolean } from '../../utils/to-boolean.js';
+import { GraphQLSubscriptionController } from './graphql.js';
+import { WebSocketController } from './rest.js';
+let websocketController;
+let subscriptionController;
+export function createWebSocketController(server) {
+    if (toBoolean(env['WEBSOCKETS_REST_ENABLED'])) {
+        websocketController = new WebSocketController(server);
+    }
+}
+export function getWebSocketController() {
+    if (!toBoolean(env['WEBSOCKETS_ENABLED']) || !toBoolean(env['WEBSOCKETS_REST_ENABLED'])) {
+        throw new ServiceUnavailableException('WebSocket server is disabled', {
+            service: 'get-websocket-controller',
+        });
+    }
+    if (!websocketController) {
+        throw new ServiceUnavailableException('WebSocket server is not initialized', {
+            service: 'get-websocket-controller',
+        });
+    }
+    return websocketController;
+}
+export function createSubscriptionController(server) {
+    if (toBoolean(env['WEBSOCKETS_GRAPHQL_ENABLED'])) {
+        subscriptionController = new GraphQLSubscriptionController(server);
+    }
+}
+export function getSubscriptionController() {
+    return subscriptionController;
+}
+export * from './graphql.js';
+export * from './rest.js';

package/dist/websocket/controllers/rest.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="node" resolution-mode="require"/>
+import type { Server as httpServer } from 'http';
+import { WebSocketMessage } from '../messages.js';
+import SocketController from './base.js';
+export declare class WebSocketController extends SocketController {
+    constructor(httpServer: httpServer);
+    private bindEvents;
+    protected parseMessage(data: string): WebSocketMessage;
+}

package/dist/websocket/controllers/rest.js

@@ -0,0 +1,47 @@
+import { parseJSON } from '@directus/utils';
+import emitter from '../../emitter.js';
+import env from '../../env.js';
+import logger from '../../logger.js';
+import { refreshAccountability } from '../authenticate.js';
+import { WebSocketException, handleWebSocketException } from '../exceptions.js';
+import { WebSocketMessage } from '../messages.js';
+import SocketController from './base.js';
+export class WebSocketController extends SocketController {
+    constructor(httpServer) {
+        super(httpServer, 'WEBSOCKETS_REST');
+        this.server.on('connection', (ws, auth) => {
+            this.bindEvents(this.createClient(ws, auth));
+        });
+        logger.info(`WebSocket Server started at ws://${env['HOST']}:${env['PORT']}${this.endpoint}`);
+    }
+    bindEvents(client) {
+        client.on('parsed-message', async (message) => {
+            try {
+                message = WebSocketMessage.parse(await emitter.emitFilter('websocket.message', message, { client }));
+                client.accountability = await refreshAccountability(client.accountability);
+                emitter.emitAction('websocket.message', { message, client });
+            }
+            catch (error) {
+                handleWebSocketException(client, error, 'server');
+                return;
+            }
+        });
+        client.on('error', (event) => {
+            emitter.emitAction('websocket.error', { client, event });
+        });
+        client.on('close', (event) => {
+            emitter.emitAction('websocket.close', { client, event });
+        });
+        emitter.emitAction('websocket.connect', { client });
+    }
+    parseMessage(data) {
+        let message;
+        try {
+            message = parseJSON(data);
+        }
+        catch (err) {
+            throw new WebSocketException('server', 'INVALID_PAYLOAD', 'Unable to parse the incoming message.');
+        }
+        return message;
+    }
+}

package/dist/websocket/exceptions.d.ts

@@ -0,0 +1,16 @@
+import { BaseException } from '@directus/exceptions';
+import type { WebSocket } from 'ws';
+import { ZodError } from 'zod';
+import type { WebSocketResponse } from './messages.js';
+import type { WebSocketClient } from './types.js';
+export declare class WebSocketException extends Error {
+    type: string;
+    code: string;
+    uid: string | number | undefined;
+    constructor(type: string, code: string, message: string, uid?: string | number);
+    toJSON(): WebSocketResponse;
+    toMessage(): string;
+    static fromException(error: BaseException, type?: string): WebSocketException;
+    static fromZodError(error: ZodError, type?: string): WebSocketException;
+}
+export declare function handleWebSocketException(client: WebSocketClient | WebSocket, error: unknown, type?: string): void;

package/dist/websocket/exceptions.js

@@ -0,0 +1,55 @@
+import { BaseException } from '@directus/exceptions';
+import { ZodError } from 'zod';
+import { fromZodError } from 'zod-validation-error';
+import logger from '../logger.js';
+export class WebSocketException extends Error {
+    type;
+    code;
+    uid;
+    constructor(type, code, message, uid) {
+        super(message);
+        this.type = type;
+        this.code = code;
+        this.uid = uid;
+    }
+    toJSON() {
+        const message = {
+            type: this.type,
+            status: 'error',
+            error: {
+                code: this.code,
+                message: this.message,
+            },
+        };
+        if (this.uid !== undefined) {
+            message.uid = this.uid;
+        }
+        return message;
+    }
+    toMessage() {
+        return JSON.stringify(this.toJSON());
+    }
+    static fromException(error, type = 'unknown') {
+        return new WebSocketException(type, error.code, error.message);
+    }
+    static fromZodError(error, type = 'unknown') {
+        const zError = fromZodError(error);
+        return new WebSocketException(type, 'INVALID_PAYLOAD', zError.message);
+    }
+}
+export function handleWebSocketException(client, error, type) {
+    if (error instanceof BaseException) {
+        client.send(WebSocketException.fromException(error, type).toMessage());
+        return;
+    }
+    if (error instanceof WebSocketException) {
+        client.send(error.toMessage());
+        return;
+    }
+    if (error instanceof ZodError) {
+        client.send(WebSocketException.fromZodError(error, type).toMessage());
+        return;
+    }
+    // unhandled exceptions
+    logger.error(`WebSocket unhandled exception ${JSON.stringify({ type, error })}`);
+}

package/dist/websocket/handlers/heartbeat.d.ts

@@ -0,0 +1,11 @@
+import { WebSocketController } from '../controllers/index.js';
+import { WebSocketMessage } from '../messages.js';
+import type { WebSocketClient } from '../types.js';
+export declare class HeartbeatHandler {
+    private pulse;
+    private controller;
+    constructor(controller?: WebSocketController);
+    private checkClients;
+    onMessage(client: WebSocketClient, message: WebSocketMessage): void;
+    pingClients(): void;
+}

package/dist/websocket/handlers/heartbeat.js

@@ -0,0 +1,72 @@
+import emitter from '../../emitter.js';
+import env from '../../env.js';
+import { toBoolean } from '../../utils/to-boolean.js';
+import { WebSocketController, getWebSocketController } from '../controllers/index.js';
+import { WebSocketMessage } from '../messages.js';
+import { fmtMessage, getMessageType } from '../utils/message.js';
+const HEARTBEAT_FREQUENCY = Number(env['WEBSOCKETS_HEARTBEAT_PERIOD']) * 1000;
+export class HeartbeatHandler {
+    pulse;
+    controller;
+    constructor(controller) {
+        this.controller = controller ?? getWebSocketController();
+        emitter.onAction('websocket.message', ({ client, message }) => {
+            try {
+                this.onMessage(client, WebSocketMessage.parse(message));
+            }
+            catch {
+                /* ignore errors */
+            }
+        });
+        if (toBoolean(env['WEBSOCKETS_HEARTBEAT_ENABLED']) === true) {
+            emitter.onAction('websocket.connect', () => this.checkClients());
+            emitter.onAction('websocket.error', () => this.checkClients());
+            emitter.onAction('websocket.close', () => this.checkClients());
+        }
+    }
+    checkClients() {
+        const hasClients = this.controller.clients.size > 0;
+        if (hasClients && !this.pulse) {
+            this.pulse = setInterval(() => {
+                this.pingClients();
+            }, HEARTBEAT_FREQUENCY);
+        }
+        if (!hasClients && this.pulse) {
+            clearInterval(this.pulse);
+            this.pulse = undefined;
+        }
+    }
+    onMessage(client, message) {
+        if (getMessageType(message) !== 'ping')
+            return;
+        // send pong message back as acknowledgement
+        const data = 'uid' in message ? { uid: message.uid } : {};
+        client.send(fmtMessage('pong', data));
+    }
+    pingClients() {
+        const pendingClients = new Set(this.controller.clients);
+        const activeClients = new Set();
+        const timeout = setTimeout(() => {
+            // close connections that haven't responded
+            for (const client of pendingClients) {
+                client.close();
+            }
+        }, HEARTBEAT_FREQUENCY);
+        const messageWatcher = ({ client }) => {
+            // any message means this connection is still open
+            if (!activeClients.has(client)) {
+                pendingClients.delete(client);
+                activeClients.add(client);
+            }
+            if (pendingClients.size === 0) {
+                clearTimeout(timeout);
+                emitter.offAction('websocket.message', messageWatcher);
+            }
+        };
+        emitter.onAction('websocket.message', messageWatcher);
+        // ping all the clients
+        for (const client of pendingClients) {
+            client.send(fmtMessage('ping'));
+        }
+    }
+}

package/dist/websocket/handlers/index.d.ts

@@ -0,0 +1,4 @@
+export declare function startWebSocketHandlers(): void;
+export * from './heartbeat.js';
+export * from './items.js';
+export * from './subscribe.js';

package/dist/websocket/handlers/index.js

@@ -0,0 +1,11 @@
+import { HeartbeatHandler } from './heartbeat.js';
+import { ItemsHandler } from './items.js';
+import { SubscribeHandler } from './subscribe.js';
+export function startWebSocketHandlers() {
+    new HeartbeatHandler();
+    new ItemsHandler();
+    new SubscribeHandler();
+}
+export * from './heartbeat.js';
+export * from './items.js';
+export * from './subscribe.js';

package/dist/websocket/handlers/items.d.ts

@@ -0,0 +1,6 @@
+import { WebSocketItemsMessage } from '../messages.js';
+import type { WebSocketClient } from '../types.js';
+export declare class ItemsHandler {
+    constructor();
+    onMessage(client: WebSocketClient, message: WebSocketItemsMessage): Promise<void>;
+}

package/dist/websocket/handlers/items.js

@@ -0,0 +1,103 @@
+import emitter from '../../emitter.js';
+import { ItemsService, MetaService } from '../../services/index.js';
+import { getSchema } from '../../utils/get-schema.js';
+import { sanitizeQuery } from '../../utils/sanitize-query.js';
+import { WebSocketException, handleWebSocketException } from '../exceptions.js';
+import { WebSocketItemsMessage } from '../messages.js';
+import { fmtMessage, getMessageType } from '../utils/message.js';
+export class ItemsHandler {
+    constructor() {
+        emitter.onAction('websocket.message', ({ client, message }) => {
+            if (getMessageType(message) !== 'items')
+                return;
+            try {
+                const parsedMessage = WebSocketItemsMessage.parse(message);
+                this.onMessage(client, parsedMessage).catch((err) => {
+                    // this catch is required because the async onMessage function is not awaited
+                    handleWebSocketException(client, err, 'items');
+                });
+            }
+            catch (err) {
+                handleWebSocketException(client, err, 'items');
+            }
+        });
+    }
+    async onMessage(client, message) {
+        const uid = message.uid;
+        const accountability = client.accountability;
+        const schema = await getSchema();
+        if (!schema.collections[message.collection] || message.collection.startsWith('directus_')) {
+            throw new WebSocketException('items', 'INVALID_COLLECTION', 'The provided collection does not exists or is not accessible.', uid);
+        }
+        const isSingleton = !!schema.collections[message.collection]?.singleton;
+        const service = new ItemsService(message.collection, { schema, accountability });
+        const metaService = new MetaService({ schema, accountability });
+        let result, meta;
+        if (message.action === 'create') {
+            const query = sanitizeQuery(message?.query ?? {}, accountability);
+            if (Array.isArray(message.data)) {
+                const keys = await service.createMany(message.data);
+                result = await service.readMany(keys, query);
+            }
+            else {
+                const key = await service.createOne(message.data);
+                result = await service.readOne(key, query);
+            }
+        }
+        if (message.action === 'read') {
+            const query = sanitizeQuery(message.query ?? {}, accountability);
+            if (message.id) {
+                result = await service.readOne(message.id, query);
+            }
+            else if (message.ids) {
+                result = await service.readMany(message.ids, query);
+            }
+            else if (isSingleton) {
+                result = await service.readSingleton(query);
+            }
+            else {
+                result = await service.readByQuery(query);
+            }
+            meta = await metaService.getMetaForQuery(message.collection, query);
+        }
+        if (message.action === 'update') {
+            const query = sanitizeQuery(message.query ?? {}, accountability);
+            if (message.id) {
+                const key = await service.updateOne(message.id, message.data);
+                result = await service.readOne(key);
+            }
+            else if (message.ids) {
+                const keys = await service.updateMany(message.ids, message.data);
+                meta = await metaService.getMetaForQuery(message.collection, query);
+                result = await service.readMany(keys, query);
+            }
+            else if (isSingleton) {
+                await service.upsertSingleton(message.data);
+                result = await service.readSingleton(query);
+            }
+            else {
+                const keys = await service.updateByQuery(query, message.data);
+                meta = await metaService.getMetaForQuery(message.collection, query);
+                result = await service.readMany(keys, query);
+            }
+        }
+        if (message.action === 'delete') {
+            if (message.id) {
+                await service.deleteOne(message.id);
+                result = message.id;
+            }
+            else if (message.ids) {
+                await service.deleteMany(message.ids);
+                result = message.ids;
+            }
+            else if (message.query) {
+                const query = sanitizeQuery(message.query, accountability);
+                result = await service.deleteByQuery(query);
+            }
+            else {
+                throw new WebSocketException('items', 'INVALID_PAYLOAD', "Either 'ids', 'id' or 'query' is required for a DELETE request.", uid);
+            }
+        }
+        client.send(fmtMessage('items', { data: result, ...(meta ? { meta } : {}) }, uid));
+    }
+}

package/dist/websocket/handlers/subscribe.d.ts

@@ -0,0 +1,43 @@
+import type { Messenger } from '../../messenger.js';
+import type { WebSocketEvent } from '../messages.js';
+import { WebSocketSubscribeMessage } from '../messages.js';
+import type { Subscription, WebSocketClient } from '../types.js';
+/**
+ * Handler responsible for subscriptions
+ */
+export declare class SubscribeHandler {
+    subscriptions: Record<string, Set<Subscription>>;
+    protected messenger: Messenger;
+    /**
+     * Initialize the handler
+     */
+    constructor();
+    /**
+     * Hook into websocket client lifecycle events
+     */
+    bindWebSocket(): void;
+    /**
+     * Register a subscription
+     * @param subscription
+     */
+    subscribe(subscription: Subscription): void;
+    /**
+     * Remove a subscription
+     * @param subscription
+     */
+    unsubscribe(client: WebSocketClient, uid?: string | number): void;
+    /**
+     * Dispatch event to subscriptions
+     */
+    dispatch(event: WebSocketEvent): Promise<void>;
+    /**
+     * Handle incoming (un)subscribe requests
+     */
+    onMessage(client: WebSocketClient, message: WebSocketSubscribeMessage): Promise<void>;
+    private getSinglePayload;
+    private getMultiPayload;
+    private getCollectionPayload;
+    private getFieldsPayload;
+    private getItemsPayload;
+    private getSubscription;
+}