@theia/core 1.26.0 → 1.27.0-next.10

package/src/common/cancellation.ts

@@ -49,6 +49,14 @@ export namespace CancellationToken {
         isCancellationRequested: true,
         onCancellationRequested: shortcutEvent
     });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    export function is(value: any): value is CancellationToken {
+        const candidate = value as CancellationToken;
+        return candidate && (candidate === CancellationToken.None
+            || candidate === CancellationToken.Cancelled
+            || (typeof candidate.isCancellationRequested === 'boolean' && !!candidate.onCancellationRequested));
+    }
 }
 
 export class CancellationError extends Error {

package/src/common/index.ts

@@ -29,10 +29,12 @@ export * from './contribution-provider';
 export * from './path';
 export * from './logger';
 export * from './messaging';
+export * from './message-rpc';
 export * from './message-service';
 export * from './message-service-protocol';
 export * from './progress-service';
 export * from './progress-service-protocol';
+export * from './quick-pick-service';
 export * from './selection';
 export * from './strings';
 export * from './application-error';

package/src/common/message-rpc/channel.spec.ts

@@ -0,0 +1,88 @@
+// *****************************************************************************
+// Copyright (C) 2021 Red Hat, Inc. 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 { assert, expect, spy, use } from 'chai';
+import * as spies from 'chai-spies';
+import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from './uint8-array-message-buffer';
+import { ChannelMultiplexer, ForwardingChannel, MessageProvider } from './channel';
+
+use(spies);
+
+/**
+ * A pipe with two channels at each end for testing.
+ */
+export class ChannelPipe {
+    readonly left: ForwardingChannel = new ForwardingChannel('left', () => this.right.onCloseEmitter.fire({ reason: 'Left channel has been closed' }), () => {
+        const leftWrite = new Uint8ArrayWriteBuffer();
+        leftWrite.onCommit(buffer => {
+            this.right.onMessageEmitter.fire(() => new Uint8ArrayReadBuffer(buffer));
+        });
+        return leftWrite;
+    });
+    readonly right: ForwardingChannel = new ForwardingChannel('right', () => this.left.onCloseEmitter.fire({ reason: 'Right channel has been closed' }), () => {
+        const rightWrite = new Uint8ArrayWriteBuffer();
+        rightWrite.onCommit(buffer => {
+            this.left.onMessageEmitter.fire(() => new Uint8ArrayReadBuffer(buffer));
+        });
+        return rightWrite;
+    });
+}
+describe('Message Channel', () => {
+    describe('Channel multiplexer', () => {
+        it('should forward messages to intended target channel', async () => {
+            const pipe = new ChannelPipe();
+
+            const leftMultiplexer = new ChannelMultiplexer(pipe.left);
+            const rightMultiplexer = new ChannelMultiplexer(pipe.right);
+            const openChannelSpy = spy(() => {
+            });
+
+            rightMultiplexer.onDidOpenChannel(openChannelSpy);
+            leftMultiplexer.onDidOpenChannel(openChannelSpy);
+
+            const leftFirst = await leftMultiplexer.open('first');
+            const leftSecond = await leftMultiplexer.open('second');
+
+            const rightFirst = rightMultiplexer.getOpenChannel('first');
+            const rightSecond = rightMultiplexer.getOpenChannel('second');
+
+            assert.isNotNull(rightFirst);
+            assert.isNotNull(rightSecond);
+
+            const leftSecondSpy = spy((buf: MessageProvider) => {
+                const message = buf().readString();
+                expect(message).equal('message for second');
+            });
+
+            leftSecond.onMessage(leftSecondSpy);
+
+            const rightFirstSpy = spy((buf: MessageProvider) => {
+                const message = buf().readString();
+                expect(message).equal('message for first');
+            });
+
+            rightFirst!.onMessage(rightFirstSpy);
+
+            leftFirst.getWriteBuffer().writeString('message for first').commit();
+            rightSecond!.getWriteBuffer().writeString('message for second').commit();
+
+            expect(leftSecondSpy).to.be.called();
+            expect(rightFirstSpy).to.be.called();
+
+            expect(openChannelSpy).to.be.called.exactly(4);
+        });
+    });
+});

package/src/common/message-rpc/channel.ts

@@ -0,0 +1,260 @@
+// *****************************************************************************
+// Copyright (C) 2021 Red Hat, Inc. 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, DisposableCollection } from '../disposable';
+import { Emitter, Event } from '../event';
+import { ReadBuffer, WriteBuffer } from './message-buffer';
+
+/**
+ * A channel is a bidirectional communications channel with lifecycle and
+ * error signalling. Note that creation of channels is specific to particular
+ * implementations and thus not part of the protocol.
+ */
+export interface Channel {
+
+    /**
+     * The remote side has closed the channel
+     */
+    onClose: Event<ChannelCloseEvent>;
+
+    /**
+     * An error has occurred while writing to or reading from the channel
+     */
+    onError: Event<unknown>;
+
+    /**
+     * A message has arrived and can be read  by listeners using a {@link MessageProvider}.
+     */
+    onMessage: Event<MessageProvider>;
+
+    /**
+     * Obtain a {@link WriteBuffer} to write a message to the channel.
+     */
+    getWriteBuffer(): WriteBuffer;
+
+    /**
+     * Close this channel. No {@link onClose} event should be sent
+     */
+    close(): void;
+}
+
+/**
+ * The event that is emitted when a channel is closed from the remote side.
+ */
+export interface ChannelCloseEvent {
+    reason: string,
+    code?: number
+};
+
+/**
+ * The `MessageProvider` is emitted when a channel receives a new message.
+ * Listeners can invoke the provider to obtain a new {@link ReadBuffer} for the received message.
+ * This ensures that each listener has its own isolated {@link ReadBuffer} instance.
+ *
+ */
+export type MessageProvider = () => ReadBuffer;
+
+/**
+ * Helper class to implement the single channels on a {@link ChannelMultiplexer}. Simply forwards write requests to
+ * the given write buffer source i.e. the main channel of the {@link ChannelMultiplexer}.
+ */
+export class ForwardingChannel implements Channel {
+
+    protected toDispose = new DisposableCollection();
+    constructor(readonly id: string, protected readonly closeHandler: () => void, protected readonly writeBufferSource: () => WriteBuffer) {
+        this.toDispose.pushAll([this.onCloseEmitter, this.onErrorEmitter, this.onMessageEmitter]);
+    }
+
+    onCloseEmitter: Emitter<ChannelCloseEvent> = new Emitter();
+    get onClose(): Event<ChannelCloseEvent> {
+        return this.onCloseEmitter.event;
+    };
+
+    onErrorEmitter: Emitter<unknown> = new Emitter();
+    get onError(): Event<unknown> {
+        return this.onErrorEmitter.event;
+    };
+
+    onMessageEmitter: Emitter<MessageProvider> = new Emitter();
+    get onMessage(): Event<MessageProvider> {
+        return this.onMessageEmitter.event;
+    };
+
+    getWriteBuffer(): WriteBuffer {
+        return this.writeBufferSource();
+    }
+
+    close(): void {
+        this.closeHandler();
+        this.toDispose.dispose();
+    }
+}
+
+/**
+ * The different message types used in the messaging protocol of the {@link ChannelMultiplexer}
+ */
+export enum MessageTypes {
+    Open = 1,
+    Close = 2,
+    AckOpen = 3,
+    Data = 4
+}
+
+/**
+ * The write buffers in this implementation immediately write to the underlying
+ * channel, so we rely on writers to the multiplexed channels to always commit their
+ * messages and always in one go.
+ */
+export class ChannelMultiplexer implements Disposable {
+    protected pendingOpen: Map<string, (channel: ForwardingChannel) => void> = new Map();
+    protected openChannels: Map<string, ForwardingChannel> = new Map();
+
+    protected readonly onOpenChannelEmitter = new Emitter<{ id: string, channel: Channel }>();
+    get onDidOpenChannel(): Event<{ id: string, channel: Channel }> {
+        return this.onOpenChannelEmitter.event;
+    }
+
+    protected toDispose = new DisposableCollection();
+
+    constructor(protected readonly underlyingChannel: Channel) {
+        this.toDispose.pushAll([
+            this.underlyingChannel.onMessage(buffer => this.handleMessage(buffer())),
+            this.underlyingChannel.onClose(event => this.onUnderlyingChannelClose(event)),
+            this.underlyingChannel.onError(error => this.handleError(error)),
+            this.onOpenChannelEmitter
+        ]);
+    }
+
+    protected handleError(error: unknown): void {
+        this.openChannels.forEach(channel => {
+            channel.onErrorEmitter.fire(error);
+        });
+    }
+
+    onUnderlyingChannelClose(event?: ChannelCloseEvent): void {
+        if (!this.toDispose.disposed) {
+            this.toDispose.push(Disposable.create(() => {
+                this.pendingOpen.clear();
+                this.openChannels.forEach(channel => {
+                    channel.onCloseEmitter.fire(event ?? { reason: 'Multiplexer main channel has been closed from the remote side!' });
+                });
+
+                this.openChannels.clear();
+            }));
+            this.dispose();
+        }
+
+    }
+
+    protected handleMessage(buffer: ReadBuffer): void {
+        const type = buffer.readUint8();
+        const id = buffer.readString();
+        switch (type) {
+            case MessageTypes.AckOpen: {
+                return this.handleAckOpen(id);
+            }
+            case MessageTypes.Open: {
+                return this.handleOpen(id);
+            }
+            case MessageTypes.Close: {
+                return this.handleClose(id);
+            }
+            case MessageTypes.Data: {
+                return this.handleData(id, buffer.sliceAtReadPosition());
+            }
+        }
+    }
+
+    protected handleAckOpen(id: string): void {
+        // edge case: both side try to open a channel at the same time.
+        const resolve = this.pendingOpen.get(id);
+        if (resolve) {
+            const channel = this.createChannel(id);
+            this.pendingOpen.delete(id);
+            this.openChannels.set(id, channel);
+            resolve!(channel);
+            this.onOpenChannelEmitter.fire({ id, channel });
+        }
+    }
+
+    protected handleOpen(id: string): void {
+        if (!this.openChannels.has(id)) {
+            const channel = this.createChannel(id);
+            this.openChannels.set(id, channel);
+            const resolve = this.pendingOpen.get(id);
+            if (resolve) {
+                // edge case: both side try to open a channel at the same time.
+                resolve(channel);
+            }
+            this.underlyingChannel.getWriteBuffer().writeUint8(MessageTypes.AckOpen).writeString(id).commit();
+            this.onOpenChannelEmitter.fire({ id, channel });
+        }
+    }
+
+    protected handleClose(id: string): void {
+        const channel = this.openChannels.get(id);
+        if (channel) {
+            channel.onCloseEmitter.fire({ reason: 'Channel has been closed from the remote side' });
+            this.openChannels.delete(id);
+        }
+    }
+
+    protected handleData(id: string, data: ReadBuffer): void {
+        const channel = this.openChannels.get(id);
+        if (channel) {
+            channel.onMessageEmitter.fire(() => data);
+        }
+    }
+
+    protected createChannel(id: string): ForwardingChannel {
+        return new ForwardingChannel(id, () => this.closeChannel(id), () => this.prepareWriteBuffer(id));
+    }
+
+    // Prepare the write buffer for the channel with the give, id. The channel id has to be encoded
+    // and written to the buffer before the actual message.
+    protected prepareWriteBuffer(id: string): WriteBuffer {
+        const underlying = this.underlyingChannel.getWriteBuffer();
+        underlying.writeUint8(MessageTypes.Data);
+        underlying.writeString(id);
+        return underlying;
+    }
+
+    protected closeChannel(id: string): void {
+        this.underlyingChannel.getWriteBuffer()
+            .writeUint8(MessageTypes.Close)
+            .writeString(id)
+            .commit();
+
+        this.openChannels.delete(id);
+    }
+
+    open(id: string): Promise<Channel> {
+        const result = new Promise<Channel>((resolve, reject) => {
+            this.pendingOpen.set(id, resolve);
+        });
+        this.underlyingChannel.getWriteBuffer().writeUint8(MessageTypes.Open).writeString(id).commit();
+        return result;
+    }
+
+    getOpenChannel(id: string): Channel | undefined {
+        return this.openChannels.get(id);
+    }
+
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+}
+

package/src/{node/messaging/logger.ts → common/message-rpc/index.ts}

@@ -1,5 +1,5 @@
 // *****************************************************************************
-// Copyright (C) 2017 TypeFox and others.
+// Copyright (C) 2022 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
@@ -13,25 +13,6 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 // *****************************************************************************
-
-import { Logger } from 'vscode-ws-jsonrpc';
-
-export class ConsoleLogger implements Logger {
-
-    error(message: string): void {
-        console.log(message);
-    }
-
-    warn(message: string): void {
-        console.log(message);
-    }
-
-    info(message: string): void {
-        console.log(message);
-    }
-
-    log(message: string): void {
-        console.log(message);
-    }
-
-}
+export { RequestHandler, RpcProtocol, RpcProtocolOptions } from './rpc-protocol';
+export { Channel, ChannelCloseEvent, MessageProvider } from './channel';
+export { ReadBuffer, WriteBuffer } from './message-buffer';

package/src/common/message-rpc/message-buffer.ts

@@ -0,0 +1,99 @@
+// *****************************************************************************
+// Copyright (C) 2021 Red Hat, Inc. 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
+// *****************************************************************************
+
+/**
+ * A buffer maintaining a write position capable of writing primitive values
+ */
+export interface WriteBuffer {
+    writeUint8(byte: number): this
+    writeUint16(value: number): this
+    writeUint32(value: number): this
+    writeString(value: string): this
+    writeBytes(value: Uint8Array): this
+    writeNumber(value: number): this
+    writeLength(value: number): this
+    /**
+     * Makes any writes to the buffer permanent, for example by sending the writes over a channel.
+     * You must obtain a new write buffer after committing
+     */
+    commit(): void;
+}
+
+export class ForwardingWriteBuffer implements WriteBuffer {
+    constructor(protected readonly underlying: WriteBuffer) {
+    }
+
+    writeUint8(byte: number): this {
+        this.underlying.writeUint8(byte);
+        return this;
+    }
+
+    writeUint16(value: number): this {
+        this.underlying.writeUint16(value);
+        return this;
+    }
+
+    writeUint32(value: number): this {
+        this.underlying.writeUint32(value);
+        return this;
+    }
+
+    writeLength(value: number): this {
+        this.underlying.writeLength(value);
+        return this;
+    }
+
+    writeString(value: string): this {
+        this.underlying.writeString(value);
+        return this;
+    }
+
+    writeBytes(value: Uint8Array): this {
+        this.underlying.writeBytes(value);
+        return this;
+    }
+
+    writeNumber(value: number): this {
+        this.underlying.writeNumber(value);
+        return this;
+    }
+
+    commit(): void {
+        this.underlying.commit();
+    }
+}
+
+/**
+ * A buffer maintaining a read position in a buffer containing a received message capable of
+ * reading primitive values.
+ */
+export interface ReadBuffer {
+    readUint8(): number;
+    readUint16(): number;
+    readUint32(): number;
+    readString(): string;
+    readNumber(): number,
+    readLength(): number,
+    readBytes(): Uint8Array;
+
+    /**
+     * Returns a new read buffer  whose starting read position is the current read position of this buffer.
+     * This is useful to create read buffers sub messages.
+     * (e.g. when using a multiplexer the beginning of the message might contain some protocol overhead which should not be part
+     * of the message reader that is sent to the target channel)
+     */
+    sliceAtReadPosition(): ReadBuffer
+}

package/src/common/message-rpc/rpc-message-encoder.spec.ts

@@ -0,0 +1,42 @@
+// *****************************************************************************
+// Copyright (C) 2021 Red Hat, Inc. 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 { expect } from 'chai';
+import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from './uint8-array-message-buffer';
+import { RpcMessageDecoder, RpcMessageEncoder } from './rpc-message-encoder';
+
+describe('PPC Message Codex', () => {
+    describe('RPC Message Encoder & Decoder', () => {
+        it('should encode object into binary message and decode the message back into the original object', () => {
+            const buffer = new Uint8Array(1024);
+            const writer = new Uint8ArrayWriteBuffer(buffer);
+
+            const encoder = new RpcMessageEncoder();
+            const jsonMangled = JSON.parse(JSON.stringify(encoder));
+
+            encoder.writeTypedValue(writer, encoder);
+
+            const written = writer.getCurrentContents();
+
+            const reader = new Uint8ArrayReadBuffer(written);
+
+            const decoder = new RpcMessageDecoder();
+            const decoded = decoder.readTypedValue(reader);
+
+            expect(decoded).deep.equal(jsonMangled);
+        });
+    });
+});