@eclipse-glsp/server 1.1.0-RC05

package/src/common/session/client-session-manager.ts

@@ -0,0 +1,182 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { InitializeClientSessionParameters, remove } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import { GLSPServer } from '../protocol/glsp-server';
+import { GLSPServerListener } from '../protocol/glsp-server-listener';
+import { GLSPServerError } from '../utils/glsp-server-error';
+import { ClientSession } from './client-session';
+import { ClientSessionFactory } from './client-session-factory';
+import { ClientSessionListener } from './client-session-listener';
+
+export const ClientSessionManager = Symbol('ClientSessionManager');
+
+/**
+ * The central component that manages the lifecycle of client sessions.
+ */
+export interface ClientSessionManager {
+    /**
+     * Retries an existing (or created a new) {@link ClientSession} for the given id and diagram type.
+     * If a new session has been created all {@link ClientSessionListener}s are notified via the
+     * {@link ClientSessionListener.sessionCreated} method.
+     *
+     * @param clientSessionId The client session id (i.e. clientId).
+     * @param diagramType     The diagram type.
+     * @returns The existing or newly constructed {@link ClientSession}.
+     *
+     * @throws {@link GLSPServerError} if another session with matching client id but different diagram type already exists.
+     */
+    getOrCreateClientSession(params: InitializeClientSessionParameters): ClientSession;
+
+    /**
+     * Retrieve an existing (i.e. currently active) {@link ClientSession} for the given client session id.
+     *
+     * @param clientSessionId The client session id.
+     * @returns The client session for the given id o `undefined` if no session is present with the given id.
+     */
+    getSession(clientSessionId: string): ClientSession | undefined;
+
+    /**
+     * Return all currently active {@link ClientSession}s for the given diagram type.
+     *
+     * @param diagramType The diagram type.
+     * @returns An array of all currently active {@link ClientSession}s.
+     */
+    getSessionsByType(diagramType: string): Array<ClientSession>;
+
+    /**
+     * Dispose the active client session with the given id. This marks the end of the lifecylce of a client session.
+     * After successfully disposal all {@link ClientSessionListener}s are notified via the
+     * {@link ClientSessionListener.sessionDisposed} method.
+     *
+     * @param clientSessionId The id of the client session which should be disposed.
+     * @returns `true` if a session with the given id was active and successfully disposed, `false` otherwise.
+     */
+    disposeClientSession(clientSessionId: string): boolean;
+
+    /**
+     * Register a new {@link ClientSessionListener}. Optionally the scope of the listener can be restricted to a set
+     * of client session ids. If no client session ids are passed, the listener will be registered globally and trigger
+     * for all client sessions.
+     *
+     * @param listener         The listener that should be registered.
+     * @param clientSessionIds Scope of client ids
+     * @returns `true` if the listener was registered successfully, `false` otherwise
+     */
+    addListener(listener: ClientSessionListener, ...clientSessionIds: string[]): boolean;
+
+    /**
+     * Unregister a given {@link ClientSessionListener} from this client session manager.
+     *
+     * @param listener The listener that should be removed.
+     * @returns `false` if the listener is not registered, `true` if it was successfully unregistered.
+     */
+    removeListener(listener: ClientSessionListener): boolean;
+
+    /**
+     * Unregister all {@link ClientSessionListener} that haven been registered for the given scope of client session ids.
+     * If not client session ids are passed all listeners will be removed.
+     *
+     * @param clientSessionIds Scope (i.e. set) of client session ids.
+     */
+    removeListeners(...clientSessionIds: string[]): void;
+}
+
+const ALL_CLIENT_IDS_KEY = '*';
+
+@injectable()
+export class DefaultClientSessionManager implements ClientSessionManager, GLSPServerListener {
+    @inject(ClientSessionFactory) sessionFactory: ClientSessionFactory;
+
+    protected clientSessions: Map<string, ClientSession> = new Map<string, ClientSession>();
+    protected listeners: Map<string, ClientSessionListener[]> = new Map<string, ClientSessionListener[]>();
+
+    protected getListenersToNotify(clientSession: ClientSession, method: keyof ClientSessionListener): ClientSessionListener[] {
+        const globalListeners = this.listeners.get(ALL_CLIENT_IDS_KEY)?.filter(listener => listener[method]) ?? [];
+        const sessionListeners = this.listeners.get(clientSession.id)?.filter(listener => listener[method]) ?? [];
+        return [...globalListeners, ...sessionListeners];
+    }
+
+    getOrCreateClientSession(params: InitializeClientSessionParameters): ClientSession {
+        const { clientSessionId, diagramType } = params;
+        const session = this.clientSessions.get(clientSessionId);
+        if (session) {
+            if (session.diagramType !== diagramType) {
+                throw new GLSPServerError(`Could not initialize new session for diagram type '${diagramType}'
+                Another session with the same id for the diagram type ${session.diagramType} already exists`);
+            }
+            return session;
+        }
+
+        const newSession = this.sessionFactory.create(params);
+        this.clientSessions.set(clientSessionId, newSession);
+        this.getListenersToNotify(newSession, 'sessionCreated').forEach(listener => listener.sessionCreated!(newSession));
+        return newSession;
+    }
+
+    getSession(clientSessionId: string): ClientSession | undefined {
+        return this.clientSessions.get(clientSessionId);
+    }
+
+    getSessionsByType(diagramType: string): ClientSession[] {
+        return Array.from(this.clientSessions.values()).filter(session => session.diagramType === diagramType);
+    }
+
+    disposeClientSession(clientSessionId: string): boolean {
+        const session = this.clientSessions.get(clientSessionId);
+        if (session) {
+            session.dispose();
+            this.getListenersToNotify(session, 'sessionDisposed').forEach(listener => listener.sessionDisposed!(session));
+            this.clientSessions.delete(clientSessionId);
+            this.listeners.delete(clientSessionId);
+            return true;
+        }
+        return false;
+    }
+
+    addListener(listener: ClientSessionListener, ...clientSessionIds: string[]): boolean {
+        if (clientSessionIds.length === 0) {
+            this.addSingleListener(ALL_CLIENT_IDS_KEY, listener);
+        }
+        return clientSessionIds.map(clientId => this.addSingleListener(clientId, listener)).every(added => added);
+    }
+
+    protected addSingleListener(clientSessionId: string, listener: ClientSessionListener): boolean {
+        const listeners = this.listeners.get(clientSessionId) ?? [];
+        listeners.push(listener);
+        this.listeners.set(clientSessionId, listeners);
+        return true;
+    }
+
+    removeListener(listener: ClientSessionListener): boolean {
+        return Array.from(this.listeners.values())
+            .map(listeners => remove(listeners, listener))
+            .every(removed => removed);
+    }
+
+    removeListeners(...clientSessionIds: string[]): void {
+        if (clientSessionIds.length === 0) {
+            this.listeners.clear();
+        } else {
+            clientSessionIds.forEach(id => this.listeners.delete(id));
+        }
+    }
+
+    serverShutDown(server: GLSPServer): void {
+        Array.from(this.clientSessions.keys()).forEach(id => this.disposeClientSession(id));
+        this.listeners.clear();
+    }
+}

package/src/common/session/client-session.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { Disposable } from '@eclipse-glsp/protocol';
+import { Container } from 'inversify';
+import { ActionDispatcher } from '../actions/action-dispatcher';
+
+/**
+ * Stores the core information that the `GLSPServer` needs to know about a client session.
+ * When handling session specific requests (i.e. `ActionMessage`s the server retrieves the corresponding
+ * client session from the `ClientSessionManager` and delegates the action message to its
+ * {@link ActionDispatcher};
+ */
+export interface ClientSession extends Disposable {
+    /**
+     * The id of the client session.
+     */
+    readonly id: string;
+
+    /**
+     * The diagram type of the client session.
+     */
+    readonly diagramType: string;
+
+    /**
+     * The action dispatcher of this diagram type. The action dispatcher is typically created by the session
+     * specific injector and is basically the entrypoint to the session specific injection context.
+     */
+    readonly actionDispatcher: ActionDispatcher;
+
+    /**
+     * The session specific {@link Container}.
+     */
+    readonly container: Container;
+}
+
+export class DefaultClientSession implements ClientSession {
+    constructor(
+        readonly id: string,
+        readonly diagramType: string,
+        readonly actionDispatcher: ActionDispatcher,
+        readonly container: Container
+    ) {}
+
+    dispose(): void {
+        if (Disposable.is(this.actionDispatcher)) {
+            this.actionDispatcher.dispose();
+        }
+    }
+}

package/src/common/test/mock-util.ts

@@ -0,0 +1,241 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+/* eslint-disable @typescript-eslint/no-empty-function */
+// Stub-implementation classes used for unit testing
+
+import { GEdge, GModelElement, GModelElementConstructor, GNode } from '@eclipse-glsp/graph';
+import {
+    Action,
+    ActionMessage,
+    Args,
+    CreateNodeOperation,
+    EdgeTypeHint,
+    InitializeClientSessionParameters,
+    MaybeArray,
+    Point,
+    RequestEditValidationAction,
+    ShapeTypeHint,
+    ValidationStatus
+} from '@eclipse-glsp/protocol';
+import { Container } from 'inversify';
+import { MessageConnection } from 'vscode-jsonrpc';
+import { ActionDispatcher } from '../actions/action-dispatcher';
+import { ActionHandler, ActionHandlerFactory } from '../actions/action-handler';
+import { Command } from '../command/command';
+import { DiagramConfiguration, ServerLayoutKind } from '../diagram/diagram-configuration';
+import { ContextEditValidator } from '../features/directediting/context-edit-validator';
+import { LabelEditValidator } from '../features/directediting/label-edit-validator';
+import { GModelCreateEdgeOperationHandler, GModelCreateNodeOperationHandler } from '../gmodel/index';
+import { JsonRpcGLSPClientProxy } from '../protocol/glsp-client-proxy';
+import { GLSPServer } from '../protocol/glsp-server';
+import { GLSPServerListener } from '../protocol/glsp-server-listener';
+import { ClientSession } from '../session/client-session';
+import { ClientSessionFactory } from '../session/client-session-factory';
+import { ClientSessionInitializer } from '../session/client-session-initializer';
+import { ClientSessionListener } from '../session/client-session-listener';
+import { ClientSessionManager } from '../session/client-session-manager';
+import { Logger, LogLevel } from '../utils/logger';
+
+export async function delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function createClientSession(
+    id: string,
+    diagramType: string,
+    container = new Container(),
+    actionDispatcher = new StubActionDispatcher()
+): ClientSession {
+    return {
+        id,
+        diagramType,
+        container,
+        actionDispatcher,
+        dispose: () => {
+            //
+        }
+    };
+}
+
+export class StubActionHandler implements ActionHandler {
+    constructor(public actionKinds: string[]) {}
+
+    execute(action: Action): Action[] {
+        return [];
+    }
+}
+
+export class StubCreateNodeOperationHandler extends GModelCreateNodeOperationHandler {
+    elementTypeIds: string[];
+
+    constructor(readonly label: string) {
+        super();
+        this.elementTypeIds = [label];
+    }
+
+    createNode(operation: CreateNodeOperation, relativeLocation?: Point): GNode | undefined {
+        return new GNode();
+    }
+}
+
+export class StubCreateEdgeOperationHandler extends GModelCreateEdgeOperationHandler {
+    elementTypeIds: string[];
+
+    constructor(readonly label: string) {
+        super();
+        this.elementTypeIds = [label];
+    }
+
+    createEdge(source: GModelElement, target: GModelElement): GEdge | undefined {
+        return undefined;
+    }
+}
+
+export class StubActionDispatcher implements ActionDispatcher {
+    dispatchAfterNextUpdate(...actions: MaybeArray<Action[]>): void {}
+
+    dispatch(action: Action): Promise<void> {
+        return Promise.resolve();
+    }
+
+    dispatchAll(...actions: MaybeArray<Action>[]): Promise<void> {
+        return Promise.resolve();
+    }
+}
+
+export class StubClientSessionFactory implements ClientSessionFactory {
+    create(params: InitializeClientSessionParameters): ClientSession {
+        const { clientSessionId, diagramType } = params;
+        return createClientSession(clientSessionId, diagramType);
+    }
+}
+
+export class StubClientSessionManager implements ClientSessionManager {
+    getOrCreateClientSession(params: InitializeClientSessionParameters): ClientSession {
+        const { clientSessionId, diagramType } = params;
+        return createClientSession(clientSessionId, diagramType);
+    }
+
+    getSession(clientSessionId: string): ClientSession | undefined {
+        return undefined;
+    }
+
+    getSessionsByType(diagramType: string): ClientSession[] {
+        return [];
+    }
+
+    disposeClientSession(clientSessionId: string): boolean {
+        return true;
+    }
+
+    addListener(listener: ClientSessionListener, ...clientSessionIds: string[]): boolean {
+        return true;
+    }
+
+    removeListener(listener: ClientSessionListener): boolean {
+        return true;
+    }
+
+    removeListeners(...clientSessionIds: string[]): void {
+        return undefined;
+    }
+}
+
+export class StubLogger extends Logger {
+    logLevel = LogLevel.none;
+    caller = undefined;
+
+    info(message: string, ...params: any[]): void {}
+
+    warn(message: string, ...params: any[]): void {}
+
+    error(message: string, ...params: any[]): void {}
+
+    debug(message: string, ...params: any[]): void {}
+}
+
+export class StubClientSessionListener implements ClientSessionListener {
+    sessionCreated(clientSession: ClientSession): void {}
+
+    sessionDisposed(clientSession: ClientSession): void {}
+}
+
+export class StubGLSPClientProxy implements JsonRpcGLSPClientProxy {
+    connect(connection: MessageConnection): void {}
+
+    process(message: ActionMessage<Action>): void {}
+}
+
+export class StubGLSPServerListener implements GLSPServerListener {
+    serverInitialized(server: GLSPServer): void {}
+
+    serverShutDown(server: GLSPServer): void {}
+}
+
+export class StubDiagramConfiguration implements DiagramConfiguration {
+    typeMapping = new Map<string, GModelElementConstructor>();
+
+    shapeTypeHints: ShapeTypeHint[] = [];
+
+    edgeTypeHints: EdgeTypeHint[] = [];
+
+    layoutKind = ServerLayoutKind.NONE;
+
+    needsClientLayout = true;
+
+    animatedUpdate = true;
+}
+
+export class TestLabelEditValidator extends LabelEditValidator {
+    validate(label: string, element: GModelElement): ValidationStatus {
+        if (label === 'error') {
+            return { severity: ValidationStatus.Severity.ERROR, message: 'error' };
+        }
+        if (label === 'warning') {
+            return { severity: ValidationStatus.Severity.WARNING, message: 'warning' };
+        }
+        return { severity: ValidationStatus.Severity.OK, message: 'ok' };
+    }
+}
+
+export class TestContextEditValidator implements ContextEditValidator {
+    get contextId(): string {
+        return 'test';
+    }
+
+    validate(action: RequestEditValidationAction): ValidationStatus {
+        if (action.text === 'error') {
+            return { severity: ValidationStatus.Severity.ERROR, message: 'error' };
+        }
+        if (action.text === 'warning') {
+            return { severity: ValidationStatus.Severity.WARNING, message: 'warning' };
+        }
+        return { severity: ValidationStatus.Severity.OK, message: 'ok' };
+    }
+}
+
+export const stubActionHandlerFactory: ActionHandlerFactory = constructor => new constructor();
+
+export class StubClientSessionInitializer implements ClientSessionInitializer {
+    initialize(args?: Args): void {}
+}
+
+export class StubCommand implements Command {
+    execute(): void {}
+    undo(): void {}
+    redo(): void {}
+    canUndo?(): boolean;
+}

package/src/common/utils/args-util.ts

@@ -0,0 +1,98 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { Args, Point } from '@eclipse-glsp/protocol';
+
+export namespace ArgsUtil {
+    export const KEY_EDGE_PADDING = 'edgePadding';
+    export const KEY_EDGE_SOURCE_POINT_X = 'edgeSourcePointX';
+    export const KEY_EDGE_SOURCE_POINT_Y = 'edgeSourcePointY';
+    export const KEY_EDGE_TARGET_POINT_X = 'edgeTargetPointX';
+    export const KEY_EDGE_TARGET_POINT_Y = 'edgeTargetPointY';
+
+    export const KEY_RADIUS_TOP_LEFT = 'radiusTopLeft';
+    export const KEY_RADIUS_TOP_RIGHT = 'radiusTopRight';
+    export const KEY_RADIUS_BOTTOM_RIGHT = 'radiusBottomRight';
+    export const KEY_RADIUS_BOTTOM_LEFT = 'radiusBottomLeft';
+
+    export function cornerRadius(radius: number): Args;
+    export function cornerRadius(topLeftBottomRight: number, topRightBottomLeft: number): Args;
+    export function cornerRadius(topLeft: number, topRight: number, bottomRight: number, bottomLeft: number): Args;
+    export function cornerRadius(radiusOrTopLeft: number, topRightOpt?: number, bottomRightOpt?: number, bottomLeftOpt?: number): Args {
+        const topLeft = radiusOrTopLeft;
+        let topRight = radiusOrTopLeft;
+        let bottomLeft = radiusOrTopLeft;
+        let bottomRight = radiusOrTopLeft;
+
+        if (topRightOpt) {
+            topRight = topRightOpt;
+            if (bottomRightOpt && bottomLeftOpt) {
+                bottomLeft = bottomLeftOpt;
+                bottomRight = bottomRightOpt;
+            } else {
+                bottomRight = radiusOrTopLeft;
+                bottomLeft = topRight;
+            }
+        }
+
+        return {
+            [KEY_RADIUS_TOP_RIGHT]: topLeft,
+            [KEY_RADIUS_BOTTOM_LEFT]: bottomLeft,
+            [KEY_RADIUS_BOTTOM_RIGHT]: bottomRight,
+            [KEY_RADIUS_TOP_RIGHT]: topRight
+        };
+    }
+
+    export function edgePadding(edgePadding: number): Args {
+        return { [KEY_EDGE_PADDING]: edgePadding };
+    }
+
+    export function getEdgePadding(args: Args): number | undefined {
+        return getNumber(args, KEY_EDGE_PADDING);
+    }
+
+    export function getEdgeSourcePoint(args: Args = {}): Point | undefined {
+        const x = getNumber(args, KEY_EDGE_SOURCE_POINT_X);
+        const y = getNumber(args, KEY_EDGE_SOURCE_POINT_Y);
+        if (x && y) {
+            return { x, y };
+        }
+        return undefined;
+    }
+
+    export function getEdgeTargetPoint(args: Args = {}): Point | undefined {
+        const x = getNumber(args, KEY_EDGE_TARGET_POINT_X);
+        const y = getNumber(args, KEY_EDGE_TARGET_POINT_Y);
+        if (x && y) {
+            return { x, y };
+        }
+        return undefined;
+    }
+
+    export function get(args: Args = {}, key: string): string | undefined {
+        const value = args[key];
+        return value && typeof value === 'string' ? value : undefined;
+    }
+
+    export function getNumber(args: Args = {}, key: string): number | undefined {
+        const value = args[key];
+        return value && typeof value === 'number' ? value : undefined;
+    }
+
+    export function getBoolean(args: Args = {}, key: string): boolean {
+        const value = args[key];
+        return value && typeof value === 'boolean' ? value : false;
+    }
+}

package/src/common/utils/client-options-util.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+export class ClientOptionsUtil {
+    private static FILE_PREFIX = 'file://';
+
+    public static adaptUri(uri: string): string {
+        return uri.replace(this.FILE_PREFIX, '');
+    }
+}

package/src/common/utils/glsp-server-error.ts

@@ -0,0 +1,27 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+export class GLSPServerError extends Error {
+    constructor(message: string, readonly cause?: unknown) {
+        super(message);
+    }
+}
+
+export function getOrThrow<T>(optional: undefined | T, errorMsg: string): T {
+    if (optional !== undefined) {
+        return optional;
+    }
+    throw new GLSPServerError(errorMsg);
+}