@eclipse-glsp/server 1.1.0-RC05

package/src/common/operations/operation-handler-registry.spec.ts

@@ -0,0 +1,50 @@
+/********************************************************************************
+ * 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 { CompoundOperation, CreateEdgeOperation, CreateNodeOperation } from '@eclipse-glsp/protocol';
+import { expect } from 'chai';
+import * as mock from '../test/mock-util';
+import { CompoundOperationHandler } from './compound-operation-handler';
+import { OperationHandlerRegistry } from './operation-handler-registry';
+
+describe('Test OperationHandlerRegistry', () => {
+    const stubANode = new mock.StubCreateNodeOperationHandler('ANode');
+    const stubBNode = new mock.StubCreateNodeOperationHandler('BNode');
+    const stubAEdge = new mock.StubCreateEdgeOperationHandler('AEdge');
+    const stubBEdge = new mock.StubCreateEdgeOperationHandler('BEdge');
+    const operationHandlerRegistry = new OperationHandlerRegistry();
+
+    it('register OperationActionHandler', () => {
+        operationHandlerRegistry.registerHandler(new CompoundOperationHandler());
+        expect(operationHandlerRegistry.keys()).to.have.length(1);
+        expect(operationHandlerRegistry.keys()).to.contain(CompoundOperation.KIND);
+        expect(operationHandlerRegistry.get(CompoundOperation.KIND)).to.be.an.instanceOf(CompoundOperationHandler);
+    });
+
+    it('register CreateOperationActionHandlers', () => {
+        operationHandlerRegistry.registerHandler(stubANode);
+        operationHandlerRegistry.registerHandler(stubBNode);
+        operationHandlerRegistry.registerHandler(stubAEdge);
+        operationHandlerRegistry.registerHandler(stubBEdge);
+        expect(operationHandlerRegistry.keys()).to.contain(`${CreateNodeOperation.KIND}_ANode`);
+        expect(operationHandlerRegistry.get(`${CreateNodeOperation.KIND}_ANode`)).to.be.equal(stubANode);
+        expect(operationHandlerRegistry.keys()).to.contain(`${CreateNodeOperation.KIND}_BNode`);
+        expect(operationHandlerRegistry.get(`${CreateNodeOperation.KIND}_BNode`)).to.be.equal(stubBNode);
+        expect(operationHandlerRegistry.keys()).to.contain(`${CreateEdgeOperation.KIND}_AEdge`);
+        expect(operationHandlerRegistry.get(`${CreateEdgeOperation.KIND}_AEdge`)).to.be.equal(stubAEdge);
+        expect(operationHandlerRegistry.keys()).to.contain(`${CreateEdgeOperation.KIND}_BEdge`);
+        expect(operationHandlerRegistry.get(`${CreateEdgeOperation.KIND}_BEdge`)).to.be.equal(stubBEdge);
+    });
+});

package/src/common/operations/operation-handler-registry.ts

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * 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, CreateOperation, MaybePromise, Operation } from '@eclipse-glsp/protocol';
+import { inject, injectable, optional } from 'inversify';
+import { Command } from '../command/command';
+import { ClientSessionInitializer } from '../session/client-session-initializer';
+import { Registry } from '../utils/registry';
+import { CreateOperationHandler } from './create-operation-handler';
+import { OperationHandler, OperationHandlerConstructor, OperationHandlerFactory } from './operation-handler';
+
+@injectable()
+export class OperationHandlerRegistry extends Registry<string, OperationHandler> {
+    registerHandler(handler: OperationHandler): boolean {
+        if (CreateOperationHandler.is(handler)) {
+            handler.elementTypeIds.forEach(typeId => this.register(`${handler.operationType}_${typeId}`, handler));
+            return true;
+        } else {
+            return this.register(handler.operationType, handler);
+        }
+    }
+
+    getOperationHandler(operation: Operation): OperationHandler | undefined {
+        return CreateOperation.is(operation) ? this.get(`${operation.kind}_${operation.elementTypeId}`) : this.get(operation.kind);
+    }
+
+    /**
+     * Returns the matching command for the given operation.
+     *
+     * @param operation operation
+     * @return the matching command for the given operation
+     */
+    getExecutableCommand(operation: Operation): MaybePromise<Command | undefined> {
+        return this.getOperationHandler(operation)?.createCommand(operation);
+    }
+}
+
+@injectable()
+export class OperationHandlerRegistryInitializer implements ClientSessionInitializer {
+    @inject(OperationHandlerFactory)
+    protected factory: OperationHandlerFactory;
+
+    @inject(OperationHandlerConstructor)
+    @optional()
+    protected handlerConstructors: OperationHandlerConstructor[] = [];
+
+    @inject(OperationHandlerRegistry)
+    protected registry: OperationHandlerRegistry;
+
+    initialize(_args?: Args): void {
+        const handlers = this.handlerConstructors.map(constructor => this.factory(constructor));
+        handlers.forEach(handler => this.registry.registerHandler(handler));
+    }
+}

package/src/common/operations/operation-handler.ts

@@ -0,0 +1,82 @@
+/********************************************************************************
+ * 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 { MaybePromise, Operation } from '@eclipse-glsp/protocol';
+import { inject, injectable, interfaces } from 'inversify';
+import { Command } from '../command/command';
+import { ModelState } from '../features/model/model-state';
+
+/**
+ * An operation handler can execute {@link Operation}s of a certain type (subclass).
+ * The operation handler processes the operation in the {@link OperationHandler.execute()} method. The result
+ * of the execution is a {@link Command} that captures the corresponding source model changes.
+ * This command can be applied on the `CommandStack` and is reversible (undo) and can be reapplied (redo).
+ *
+ * The `OperationActionHandler` is responsible for retrieving all available (valid) operation handlers for an
+ * operation that is dispatched via `ActionDispatcher`.
+ */
+@injectable()
+export abstract class OperationHandler {
+    @inject(ModelState)
+    protected modelState: ModelState;
+
+    /**
+     * Returns the operation type that can be handled by this operation handler.
+     *
+     * @returns the operation type that can be handled.
+     */
+    abstract operationType: string;
+
+    readonly label?: string;
+
+    /**
+     * Creates a command that performs the operation in the source model(s). If `undefined` is  returned, no update
+     * is performed on the model(s).
+     *
+     * @param operation The operation to process.
+     * @return The created command to be executed on the command stack or `undefined` nothing should be done.
+     */
+    abstract createCommand(operation: Operation): MaybePromise<Command | undefined>;
+
+    /**
+     * Executes the operation handler for the given {@link Operation} and returns the corresponding {@link Command}.
+     * If the given operation cannot be handled by this handler or the handler execution did not result in any changes
+     * `undefined` is returned.
+     *
+     * @param operation The operation that should be executed or empty if nothing should be done.
+     * @returns The command capturing the execution changes or `undefined`
+     */
+    execute(operation: Operation): MaybePromise<Command | undefined> {
+        return this.handles(operation) ? this.createCommand(operation) : undefined;
+    }
+
+    /**
+     * Validates whether the given {@link Operation} can be handled by this operation handler.
+     *
+     * @param operation The operation that should be validated.
+     * @returns `true` if the given operation can be handled, `false` otherwise.
+     */
+    handles(operation: Operation): boolean {
+        return this.modelState.root && operation.kind === this.operationType;
+    }
+}
+
+export const OperationHandlerConstructor = Symbol('OperationHandlerConstructor');
+
+export type OperationHandlerConstructor = interfaces.Newable<OperationHandler>;
+
+export const OperationHandlerFactory = Symbol('OperationHandlerFactory');
+
+export type OperationHandlerFactory = (constructor: OperationHandlerConstructor) => OperationHandler;

package/src/common/protocol/glsp-client-proxy.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 { ActionMessage, JsonrpcGLSPClient } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import * as jsonrpc from 'vscode-jsonrpc';
+import { Logger } from '../utils/logger';
+
+export const GLSPClientProxyFactory = Symbol('GLSPClientProxyFactory');
+
+export type GLSPClientProxyFactory = (connection: jsonrpc.MessageConnection) => GLSPClientProxy;
+
+export const GLSPClientProxy = Symbol('GLSPClientProxy');
+
+/**
+ * Json-rpc client proxy interface to hide the underlying json-rpc logic.
+ */
+export interface GLSPClientProxy {
+    /**
+     * A `process` notification is sent from the server to server to the client when the client should handle i.e.
+     * process a specific {@link ActionMessage}. Any communication that is performed between initialization and shutdown
+     * is handled by sending action messages, either from the client to the server or from the server to the client. This
+     * is the core part of the Graphical Language Server Protocol.
+     *
+     * @param message The {@link ActionMessage} that should be processed.
+     */
+    process(message: ActionMessage): void;
+}
+
+export const JsonRpcGLSPClientProxy = Symbol('JsonRpcGLSPClientProxy');
+
+export interface JsonRpcGLSPClientProxy extends GLSPClientProxy {
+    connect(connection: jsonrpc.MessageConnection): void;
+}
+
+@injectable()
+export class DefaultGLSPClientProxy implements JsonRpcGLSPClientProxy {
+    @inject(Logger)
+    private logger: Logger;
+
+    protected connection: jsonrpc.MessageConnection;
+
+    connect(connection: jsonrpc.MessageConnection): void {
+        if (!this.connection) {
+            this.connection = connection;
+        }
+    }
+
+    process(message: ActionMessage): void {
+        this.logger.debug(`Send action '${message.action.kind}' to client '${message.clientId}'`);
+        this.connection.sendNotification(JsonrpcGLSPClient.ActionMessageNotification, message);
+    }
+}

package/src/common/protocol/glsp-server-listener.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { GLSPServer } from './glsp-server';
+
+export const GLSPServerListener = Symbol('GLSPServerListener');
+
+/**
+ * A listener to track the connection status of {@link GLSPClient}s (i.e. client applications).
+ * Gets notified when a new GLSP client connects or disconnects.
+ */
+export interface GLSPServerListener {
+    /**
+     * Triggered after a GLSPServer has been initialized via the {@link GLSPServer.initialize()}
+     * method.
+     *
+     * @param server The GLSPServer which has been initialized.
+     */
+    serverInitialized?(server: GLSPServer): void;
+
+    /**
+     * Triggered after the {@link GLSPServer.shutdown()} method has been invoked.
+     *
+     * @param glspServer The glspServer which has been shut down.
+     */
+    serverShutDown?(server: GLSPServer): void;
+}

package/src/common/protocol/glsp-server.spec.ts

@@ -0,0 +1,150 @@
+/********************************************************************************
+ * 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 { DisposeClientSessionParameters, InitializeClientSessionParameters, InitializeParameters } from '@eclipse-glsp/protocol';
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import * as sinon from 'sinon';
+import { GlobalActionProvider } from '../actions/global-action-provider';
+import { ClientSessionManager } from '../session/client-session-manager';
+import * as mock from '../test/mock-util';
+import { Logger } from '../utils/logger';
+import { GLSPClientProxy, JsonRpcGLSPClientProxy } from './glsp-client-proxy';
+import { DefaultGLSPServer } from './glsp-server';
+import { GLSPServerListener } from './glsp-server-listener';
+import assert = require('assert');
+
+describe('test DefaultGLSPServer', () => {
+    const container = new Container();
+    const clientSessionId = 'myClientSession';
+    const diagramType = 'myDiagram';
+    const applicationId = 'Test';
+    const protocolVersion = '1.0.0';
+    const serverActionKinds = new Map<string, string[]>();
+    serverActionKinds.set(diagramType, ['A1', 'A2']);
+    const sessionManager = new mock.StubClientSessionManager();
+    const spy_sessionManager_getOrCreate = sinon.spy(sessionManager, 'getOrCreateClientSession');
+    const spy_sessionManager_dispose = sinon.spy(sessionManager, 'disposeClientSession');
+    const listener1 = new mock.StubGLSPServerListener();
+    const spy_listener1_initialize = sinon.spy(listener1, 'serverInitialized');
+    const spy_listener1_shutdown = sinon.spy(listener1, 'serverShutDown');
+    const listener2 = new mock.StubGLSPServerListener();
+    const spy_listener2_initialize = sinon.spy(listener2, 'serverInitialized');
+    const spy_listener2_shutdown = sinon.spy(listener2, 'serverShutDown');
+
+    container.load(
+        new ContainerModule(bind => {
+            bind(Logger).toConstantValue(new mock.StubLogger());
+            bind(GLSPClientProxy).toConstantValue(new mock.StubGLSPClientProxy());
+            bind(JsonRpcGLSPClientProxy).toConstantValue(new mock.StubGLSPClientProxy());
+            bind(ClientSessionManager).toConstantValue(sessionManager);
+            bind(GlobalActionProvider).toConstantValue({ clientActionKinds: new Map<string, string[]>(), serverActionKinds });
+            bind(GLSPServerListener).toConstantValue(listener1);
+        })
+    );
+
+    const glspServer = container.resolve(DefaultGLSPServer);
+
+    beforeEach(() => {
+        spy_sessionManager_getOrCreate.restore();
+        spy_sessionManager_dispose.restore();
+        spy_listener1_initialize.restore();
+        spy_listener1_shutdown.restore();
+        spy_listener2_initialize.restore();
+        spy_listener2_shutdown.restore();
+    });
+
+    it('Test calls before server initialization (should throw errors)', async () => {
+        assert.rejects(() => glspServer.initializeClientSession({ clientSessionId: 'id', diagramType: 'type' }));
+        assert.rejects(() => glspServer.disposeClientSession({ clientSessionId: 'id' }));
+        assert.throws(() => glspServer.process({ clientId: 'id', action: { kind: 'action' } }));
+    });
+
+    it('addListener - add existing listener', () => {
+        const originalSize = glspServer['serverListeners'].length;
+        glspServer.addListener(listener1);
+        expect(glspServer['serverListeners'].length).to.be.equal(originalSize);
+    });
+
+    it('addListener - add new listener', () => {
+        const originalSize = glspServer['serverListeners'].length;
+        glspServer.addListener(listener2);
+        expect(glspServer['serverListeners']).to.include(listener2);
+        expect(glspServer['serverListeners'].length).to.be.equal(originalSize + 1);
+    });
+
+    it('removeListener - remove non-existing listener', () => {
+        const originalSize = glspServer['serverListeners'].length;
+        glspServer.removeListener({});
+        expect(glspServer['serverListeners'].length).to.be.equal(originalSize);
+    });
+
+    it('removeListener - remove existing listener', () => {
+        const originalSize = glspServer['serverListeners'].length;
+        glspServer.removeListener(listener2);
+        expect(glspServer['serverListeners'].length).to.be.equal(originalSize - 1);
+    });
+
+    it('initialize - with wrong protocol version', async () => {
+        const initializeParameters: InitializeParameters = { applicationId, protocolVersion: 'abc' };
+        assert.rejects(glspServer.initialize(initializeParameters));
+    });
+
+    it('initialize - with correct parameters', async () => {
+        const initializeParameters: InitializeParameters = { applicationId, protocolVersion };
+        const result = await glspServer.initialize(initializeParameters);
+        expect(result.protocolVersion).to.be.equal(protocolVersion);
+        expect(result.serverActions[diagramType]).to.be.equal(serverActionKinds.get(diagramType));
+        expect(result.serverActions[diagramType]).to.be.equal(serverActionKinds.get(diagramType));
+        expect(spy_listener1_initialize.calledWith(glspServer));
+        expect(spy_listener2_initialize.notCalled);
+    });
+
+    it('initialize - subsequent call with same parameters', async () => {
+        const initializeParameters: InitializeParameters = { applicationId, protocolVersion };
+        const result = await glspServer.initialize(initializeParameters);
+        expect(result.protocolVersion).to.be.equal(protocolVersion);
+        expect(result.serverActions[diagramType]).to.be.equal(serverActionKinds.get(diagramType));
+        expect(result.serverActions[diagramType]).to.be.equal(serverActionKinds.get(diagramType));
+    });
+
+    it('initialize -  subsequent call with other parameters', async () => {
+        const initializeParameters = { applicationId: 'someOtherApp', protocolVersion: 'AnotherProtocolVersion' };
+        await assert.rejects(() => glspServer.initialize(initializeParameters));
+    });
+
+    it('initialize client session', async () => {
+        const initializeClientSessionParameters: InitializeClientSessionParameters = {
+            clientSessionId,
+            diagramType
+        };
+        await glspServer.initializeClientSession(initializeClientSessionParameters);
+        expect(spy_sessionManager_getOrCreate.calledWith(initializeClientSessionParameters));
+    });
+
+    it('dispose client session', async () => {
+        const disposeClientSessionParameters: DisposeClientSessionParameters = {
+            clientSessionId
+        };
+        await glspServer.disposeClientSession(disposeClientSessionParameters);
+        expect(spy_sessionManager_dispose.calledWith(clientSessionId));
+    });
+
+    it('shutdown server', async () => {
+        glspServer.shutdown();
+        expect(spy_listener1_shutdown.calledWith(glspServer));
+        expect(spy_listener2_shutdown.notCalled);
+    });
+});