@theia/debug 1.18.0 → 1.21.0-next.12

package/src/node/debug-adapter-session.ts

@@ -22,40 +22,33 @@
 // Some entities copied and modified from https://github.com/Microsoft/vscode-debugadapter-node/blob/master/adapter/src/protocol.ts
 
 import {
-    CommunicationProvider,
-    DebugAdapterSession,
-} from '../common/debug-model';
+    DebugAdapter,
+    DebugAdapterSession
+} from './debug-model';
 import { DebugProtocol } from 'vscode-debugprotocol';
-import { IWebSocket } from '@theia/core/shared/vscode-ws-jsonrpc';
-import { DisposableCollection, Disposable } from '@theia/core/lib/common/disposable';
+import { Channel } from '../common/debug-service';
 
 /**
  * [DebugAdapterSession](#DebugAdapterSession) implementation.
  */
 export class DebugAdapterSessionImpl implements DebugAdapterSession {
 
-    private static TWO_CRLF = '\r\n\r\n';
-    private static CONTENT_LENGTH = 'Content-Length';
-
-    private readonly toDispose = new DisposableCollection();
-    private channel: IWebSocket | undefined;
-    private contentLength: number;
-    private buffer: Buffer;
+    private channel: Channel | undefined;
+    private isClosed: boolean = false;
 
     constructor(
         readonly id: string,
-        protected readonly communicationProvider: CommunicationProvider
+        protected readonly debugAdapter: DebugAdapter
     ) {
-        this.contentLength = -1;
-        this.buffer = Buffer.alloc(0);
-        this.toDispose.pushAll([
-            this.communicationProvider,
-            Disposable.create(() => this.write(JSON.stringify({ seq: -1, type: 'request', command: 'disconnect' }))),
-            Disposable.create(() => this.write(JSON.stringify({ seq: -1, type: 'request', command: 'terminate' })))
-        ]);
+        this.debugAdapter.onMessageReceived((message: string) => this.send(message));
+        this.debugAdapter.onClose(() => this.onDebugAdapterExit());
+        this.debugAdapter.onError(error => this.onDebugAdapterError(error));
+
     }
 
-    async start(channel: IWebSocket): Promise<void> {
+    async start(channel: Channel): Promise<void> {
+
+        console.debug(`starting debug adapter session '${this.id}'`);
         if (this.channel) {
             throw new Error('The session has already been started, id: ' + this.id);
         }
@@ -63,25 +56,19 @@ export class DebugAdapterSessionImpl implements DebugAdapterSession {
         this.channel.onMessage((message: string) => this.write(message));
         this.channel.onClose(() => this.channel = undefined);
 
-        this.communicationProvider.output.on('data', (data: Buffer) => this.handleData(data));
-        this.communicationProvider.output.on('close', () => this.onDebugAdapterExit(1, undefined)); // FIXME pass a proper exit code
-        this.communicationProvider.output.on('error', error => this.onDebugAdapterError(error));
-        this.communicationProvider.input.on('error', error => this.onDebugAdapterError(error));
     }
 
-    protected onDebugAdapterExit(exitCode: number, signal: string | undefined): void {
-        const event: DebugProtocol.ExitedEvent = {
-            type: 'event',
-            event: 'exited',
-            seq: -1,
-            body: {
-                exitCode
-            }
-        };
-        this.send(JSON.stringify(event));
+    protected onDebugAdapterExit(): void {
+        this.isClosed = true;
+        console.debug(`onDebugAdapterExit session: '${this.id}'`);
+        if (this.channel) {
+            this.channel.close();
+            this.channel = undefined;
+        }
     }
 
     protected onDebugAdapterError(error: Error): void {
+        console.debug(`error in debug adapter session: '${this.id}': ${JSON.stringify(error)}`);
         const event: DebugProtocol.Event = {
             type: 'event',
             event: 'error',
@@ -91,49 +78,6 @@ export class DebugAdapterSessionImpl implements DebugAdapterSession {
         this.send(JSON.stringify(event));
     }
 
-    protected handleData(data: Buffer): void {
-        this.buffer = Buffer.concat([this.buffer, data]);
-
-        while (true) {
-            if (this.contentLength >= 0) {
-                if (this.buffer.length >= this.contentLength) {
-                    const message = this.buffer.toString('utf8', 0, this.contentLength);
-                    this.buffer = this.buffer.slice(this.contentLength);
-                    this.contentLength = -1;
-
-                    if (message.length > 0) {
-                        this.send(message);
-                    }
-                    continue; // there may be more complete messages to process
-                }
-            } else {
-                let idx = this.buffer.indexOf(DebugAdapterSessionImpl.CONTENT_LENGTH);
-                if (idx > 0) {
-                    // log unrecognized output
-                    const output = this.buffer.slice(0, idx);
-                    console.log(output.toString('utf-8'));
-
-                    this.buffer = this.buffer.slice(idx);
-                }
-
-                idx = this.buffer.indexOf(DebugAdapterSessionImpl.TWO_CRLF);
-                if (idx !== -1) {
-                    const header = this.buffer.toString('utf8', 0, idx);
-                    const lines = header.split('\r\n');
-                    for (let i = 0; i < lines.length; i++) {
-                        const pair = lines[i].split(/: +/);
-                        if (pair[0] === DebugAdapterSessionImpl.CONTENT_LENGTH) {
-                            this.contentLength = +pair[1];
-                        }
-                    }
-                    this.buffer = this.buffer.slice(idx + DebugAdapterSessionImpl.TWO_CRLF.length);
-                    continue;
-                }
-            }
-            break;
-        }
-    }
-
     protected send(message: string): void {
         if (this.channel) {
             this.channel.send(message);
@@ -141,10 +85,18 @@ export class DebugAdapterSessionImpl implements DebugAdapterSession {
     }
 
     protected write(message: string): void {
-        this.communicationProvider.input.write(`Content-Length: ${Buffer.byteLength(message, 'utf8')}\r\n\r\n${message}`, 'utf8');
+        if (!this.isClosed) {
+            this.debugAdapter.send(message);
+        }
     }
 
     async stop(): Promise<void> {
-        this.toDispose.dispose();
+        console.debug(`stopping debug adapter session: '${this.id}'`);
+
+        if (!this.isClosed) {
+            await this.debugAdapter.stop();
+        }
+        this.channel?.close();
+        this.channel = undefined;
     }
 }

package/src/node/debug-backend-module.ts

@@ -30,7 +30,7 @@ import {
     DebugAdapterContribution,
     DebugAdapterSessionFactory,
     DebugAdapterFactory
-} from '../common/debug-model';
+} from './debug-model';
 import { DebugServiceImpl } from './debug-service-impl';
 import { DebugAdapterContributionRegistry } from './debug-adapter-contribution-registry';
 import { DebugAdapterSessionManager } from './debug-adapter-session-manager';

package/src/{common → node}/debug-model.ts

@@ -22,12 +22,11 @@
 // Some entities copied and modified from https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts
 // Some entities copied and modified from https://github.com/Microsoft/vscode/blob/master/src/vs/workbench/parts/debug/common/debug.ts
 
-import * as stream from 'stream';
-import { WebSocketChannel } from '@theia/core/lib/common/messaging/web-socket-channel';
-import { DebugConfiguration } from './debug-configuration';
+import { DebugConfiguration } from '../common/debug-configuration';
 import { IJSONSchema, IJSONSchemaSnippet } from '@theia/core/lib/common/json-schema';
-import { Disposable } from '@theia/core/lib/common/disposable';
 import { MaybePromise } from '@theia/core/lib/common/types';
+import { Event } from '@theia/core/lib/common/event';
+import { Channel } from '../common/debug-service';
 
 // FIXME: break down this file to debug adapter and debug adapter contribution (see Theia file naming conventions)
 
@@ -37,12 +36,14 @@ import { MaybePromise } from '@theia/core/lib/common/types';
 export const DebugAdapterSession = Symbol('DebugAdapterSession');
 
 /**
- * The debug adapter session.
+ * The debug adapter session. The debug adapter session manages the lifecycle of a
+ * debug session: the debug session should be discarded if and only if the debug adapter
+ * session is stopped.
  */
 export interface DebugAdapterSession {
     id: string;
     parentSession?: DebugAdapterSession;
-    start(channel: WebSocketChannel): Promise<void>
+    start(channel: Channel): Promise<void>
     stop(): Promise<void>
 }
 
@@ -55,7 +56,7 @@ export const DebugAdapterSessionFactory = Symbol('DebugAdapterSessionFactory');
  * The [debug session](#DebugSession) factory.
  */
 export interface DebugAdapterSessionFactory {
-    get(sessionId: string, communicationProvider: CommunicationProvider): DebugAdapterSession;
+    get(sessionId: string, debugAdapter: DebugAdapter): DebugAdapterSession;
 }
 
 /**
@@ -88,16 +89,35 @@ export interface DebugAdapterForkExecutable {
 export type DebugAdapterExecutable = DebugAdapterSpawnExecutable | DebugAdapterForkExecutable;
 
 /**
- * Provides some way we can communicate with the running debug adapter. In general there is
- * no obligation as of how to launch/initialize local or remote debug adapter
- * process/server, it can be done separately and it is not required that this interface covers the
- * procedure, however it is also not disallowed.
- *
- * TODO: the better name is DebugStreamConnection + handling on error and close
+ * Implementers stand for the various types of debug adapters the system can talk to.
+ * Creation of debug adapters is not covered in this interface, but handling communication
+ * and the end of life is.
  */
-export interface CommunicationProvider extends Disposable {
-    output: stream.Readable;
-    input: stream.Writable;
+
+export interface DebugAdapter {
+    /**
+     * A DAP protocol message has been received from the debug adapter
+     */
+    onMessageReceived: Event<string>;
+    /**
+     * Send a DAP message to the debug adapter
+     * @param message the JSON-encoded DAP message
+     */
+    send(message: string): void;
+    /**
+     * An error has occured communicating with the debug adapter. This does not meant the debug adapter
+     * has terminated.
+     */
+    onError: Event<Error>;
+    /**
+     * The connection to the debug adapter has been lost. This signals the end of life for this
+     * debug adapter instance.
+     */
+    onClose: Event<void>;
+    /**
+     * Terminate the connection to the debug adapter.
+     */
+    stop(): Promise<void>;
 }
 
 /**
@@ -109,8 +129,8 @@ export const DebugAdapterFactory = Symbol('DebugAdapterFactory');
  * Factory to start debug adapter.
  */
 export interface DebugAdapterFactory {
-    start(executable: DebugAdapterExecutable): CommunicationProvider;
-    connect(debugServerPort: number): CommunicationProvider;
+    start(executable: DebugAdapterExecutable): DebugAdapter;
+    connect(debugServerPort: number): DebugAdapter;
 }
 
 /**

package/src/node/inline-debug-adapter.ts

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * 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 { Emitter, Event } from '@theia/core/lib/common/event';
+import { DebugAdapter } from './debug-model';
+import * as theia from '@theia/plugin';
+
+/**
+ * A debug adapter for using the inline implementation from a plugin.
+ */
+export class InlineDebugAdapter implements DebugAdapter {
+    private messageReceivedEmitter = new Emitter<string>();
+    onMessageReceived: Event<string> = this.messageReceivedEmitter.event;
+    onError: Event<Error> = Event.None;
+    private closeEmitter = new Emitter<void>();
+    onClose: Event<void> = this.closeEmitter.event;
+
+    constructor(private debugAdapter: theia.DebugAdapter) {
+        this.debugAdapter.onDidSendMessage(msg => {
+            this.messageReceivedEmitter.fire(JSON.stringify(msg));
+        });
+    }
+
+    async start(): Promise<void> {
+    }
+
+    send(message: string): void {
+        this.debugAdapter.handleMessage(JSON.parse(message));
+    }
+
+    async stop(): Promise<void> {
+        this.debugAdapter.dispose();
+    }
+}

package/src/node/stream-debug-adapter.ts

@@ -0,0 +1,126 @@
+/********************************************************************************
+ * 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 { DisposableCollection } from '@theia/core/lib/common/disposable';
+import { Emitter, Event } from '@theia/core/lib/common/event';
+import { ChildProcess } from 'child_process';
+import * as stream from 'stream';
+import * as net from 'net';
+import { DebugAdapter } from './debug-model';
+
+abstract class StreamDebugAdapter extends DisposableCollection {
+    private messageReceivedEmitter = new Emitter<string>();
+    onMessageReceived: Event<string> = this.messageReceivedEmitter.event;
+    private errorEmitter = new Emitter<Error>();
+    onError: Event<Error> = this.errorEmitter.event;
+    private closeEmitter = new Emitter<void>();
+    onClose: Event<void> = this.closeEmitter.event;
+
+    // these constants are for the message header, see: https://microsoft.github.io/debug-adapter-protocol/overview#header-part
+    private static TWO_CRLF = '\r\n\r\n';
+    private static CONTENT_LENGTH = 'Content-Length';
+    private contentLength: number = -1;
+    private buffer: Buffer = Buffer.alloc(0);
+
+    constructor(private fromAdapter: stream.Readable, private toAdapter: stream.Writable) {
+        super();
+
+        this.fromAdapter.on('data', (data: Buffer) => this.handleData(data));
+        this.fromAdapter.on('close', () => this.handleClosed()); // FIXME pass a proper exit code
+        this.fromAdapter.on('error', error => this.errorEmitter.fire(error));
+        this.toAdapter.on('error', error => this.errorEmitter.fire(error));
+    }
+
+    handleClosed(): void {
+        this.closeEmitter.fire();
+    }
+
+    send(message: string): void {
+        const msg = `${StreamDebugAdapter.CONTENT_LENGTH}: ${Buffer.byteLength(message, 'utf8')}${StreamDebugAdapter.TWO_CRLF}${message}`;
+
+        this.toAdapter.write(msg, 'utf8');
+    }
+
+    protected handleData(data: Buffer): void {
+        this.buffer = Buffer.concat([this.buffer, data]);
+
+        while (true) {
+            if (this.contentLength >= 0) {
+                if (this.buffer.length >= this.contentLength) {
+                    const message = this.buffer.toString('utf8', 0, this.contentLength);
+                    this.buffer = this.buffer.slice(this.contentLength);
+                    this.contentLength = -1;
+
+                    if (message.length > 0) {
+                        this.messageReceivedEmitter.fire(message);
+                    }
+                    continue; // there may be more complete messages to process
+                }
+            } else {
+                let idx = this.buffer.indexOf(StreamDebugAdapter.CONTENT_LENGTH);
+                if (idx > 0) {
+                    // log unrecognized output
+                    const output = this.buffer.slice(0, idx);
+                    console.log(output.toString('utf-8'));
+
+                    this.buffer = this.buffer.slice(idx);
+                }
+
+                idx = this.buffer.indexOf(StreamDebugAdapter.TWO_CRLF);
+                if (idx !== -1) {
+                    const header = this.buffer.toString('utf8', 0, idx);
+                    const lines = header.split('\r\n');
+                    for (let i = 0; i < lines.length; i++) {
+                        const pair = lines[i].split(/: +/);
+                        if (pair[0] === StreamDebugAdapter.CONTENT_LENGTH) {
+                            this.contentLength = +pair[1];
+                        }
+                    }
+                    this.buffer = this.buffer.slice(idx + StreamDebugAdapter.TWO_CRLF.length);
+                    continue;
+                }
+            }
+            break;
+        }
+    }
+}
+
+export class ProcessDebugAdapter extends StreamDebugAdapter implements DebugAdapter {
+    protected readonly process: ChildProcess;
+    constructor(process: ChildProcess) {
+        super(process.stdout!, process.stdin!);
+        this.process = process;
+    }
+
+    async stop(): Promise<void> {
+        this.process.kill();
+        this.process.stdin?.end();
+    }
+}
+
+export class SocketDebugAdapter extends StreamDebugAdapter implements DebugAdapter {
+    private readonly socket: net.Socket;
+    constructor(socket: net.Socket) {
+        super(socket, socket);
+        this.socket = socket;
+    }
+
+    stop(): Promise<void> {
+        return new Promise<void>(resolve => {
+            this.socket.end(() => resolve());
+        });
+    }
+}

package/src/node/vscode/vscode-debug-adapter-contribution.ts

@@ -16,7 +16,7 @@
 
 import * as fs from '@theia/core/shared/fs-extra';
 import * as path from 'path';
-import { DebugAdapterExecutable, DebugAdapterContribution } from '../../common/debug-model';
+import { DebugAdapterExecutable, DebugAdapterContribution } from '../debug-model';
 import { isWindows, isOSX } from '@theia/core/lib/common/os';
 import { IJSONSchema, IJSONSchemaSnippet } from '@theia/core/lib/common/json-schema';
 import { deepClone } from '@theia/core/lib/common/objects';

package/lib/common/debug-model.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"debug-model.d.ts","sourceRoot":"","sources":["../../src/common/debug-model.ts"],"names":[],"mappings":"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"}

package/lib/common/debug-model.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"debug-model.js","sourceRoot":"","sources":["../../src/common/debug-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;kFAckF;;;AAiBlF,kHAAkH;AAElH;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAYjE;;GAEG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAmD/E;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAUjE;;GAEG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC"}