Support attaching to remote DAP server using websockets

Author: parzivail

package.json

@@ -47,10 +47,14 @@
 		"vscode:prepublish": "rimraf dist && npm run -S esbuild-base -- --minify && npm run -S esbuild-web -- --minify",
 		"test": "npm run check && npm run typecheck"
 	},
+	"dependencies": {
+		"ws": "^8.18.2"
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",
 		"@types/node": "22.x",
 		"@types/vscode": "^1.99.0",
+		"@types/ws": "^8.18.1",
 		"@vscode/debugadapter": "^1.68.0",
 		"@vscode/vsce": "^3.3.2",
 		"esbuild": "^0.25.3",
@@ -178,22 +182,17 @@
 						}
 					},
 					"attach": {
-						"required": ["program", "port"],
+						"required": ["program", "address"],
 						"properties": {
 							"program": {
 								"type": "string",
 								"format": "uri-reference",
 								"description": "Path of program to be debugged (debugee)."
 							},
-							"port": {
-								"type": "number",
-								"description": "TCP port to attach to."
-							},
-							"host": {
+							"address": {
 								"type": "string",
-								"format": "uri-reference",
-								"description": "TCP host to attach to.",
-								"default": true
+								"format": "uri",
+								"description": "Remote address to attach to."
 							},
 							"trace": {
 								"type": "boolean",

sampleWorkspace/.vscode/launch.json

@@ -20,7 +20,7 @@
       "request": "attach",
       "name": "Attach running",
       "program": "hello_world.bin",
-      "port": 4567,
+      "address": "ws://localhost:4567/debug/",
       "trace": true
     }
   ]

src/cc65Debug.ts

@@ -16,6 +16,7 @@ import * as path from "node:path";
 import { Logger, LoggingDebugSession, TerminatedEvent, logger } from "@vscode/debugadapter";
 import type { DebugProtocol } from "@vscode/debugprotocol";
 import type { DebugSession } from "vscode";
+import { WebSocket } from "ws";
 import {
 	type DbgFile,
 	type DbgMap,
@@ -77,7 +78,7 @@ export class Cc65DebugSession extends LoggingDebugSession {
 
 	private _program: ChildProcessWithoutNullStreams | undefined;
 
-	/// connected over TCP port?
+	private _websocket: WebSocket | undefined;
 	private _connected = false;
 
 	private _debugData: DbgMap | undefined;
@@ -155,7 +156,8 @@ export class Cc65DebugSession extends LoggingDebugSession {
 
 		const header = `Content-Length: ${contentLength}\r\n\r\n`;
 
-		this._program?.stdin.write(header + json, "utf8");
+		if (this._program) this._program?.stdin.write(header + json, "utf8");
+		if (this._websocket) this._websocket?.send(header + json);
 	}
 
 	public sendResponse(response: DebugProtocol.Response): void {
@@ -514,8 +516,52 @@ export class Cc65DebugSession extends LoggingDebugSession {
 	/**
 	 * Attempts to connect to an existing debugger adapter.
 	 */
-	protected connectAdapter(port: number, host: string): Promise<void> {
-		throw new Error("Connecting to existing debugger not supported yet.");
+	protected connectAdapter(address: string | URL): Promise<void> {
+		console.debug("connectAdapter", address);
+
+		const addr = typeof address === "string" ? new URL(address) : address;
+
+		if (["ws:", "wss:"].includes(addr.protocol)) {
+			return new Promise((resolve, reject) => {
+				const ws = new WebSocket(addr);
+
+				ws.addEventListener("open", (event) => {
+					console.log(`WebSocket connection established to ${addr}`);
+					logger.log(`WebSocket connection established to ${addr}`);
+					this._websocket = ws;
+					this._connected = true;
+					resolve();
+				});
+
+				ws.addEventListener("message", (event) => {
+					if (typeof event.data === "string" || event.data instanceof String) {
+						this._processData(Buffer.from(String(event.data), "utf-8"));
+					} else {
+						console.warn("Received non-text websocket data, ignoring.");
+						logger.warn("Received non-text websocket data, ignoring.");
+					}
+				});
+
+				ws.addEventListener("error", (error) => {
+					console.error(`WebSocket error: ${error}`);
+					logger.error(`WebSocket error: ${error}`);
+					reject(error.message);
+				});
+
+				ws.addEventListener("close", (event) => {
+					console.log(
+						`WebSocket connection closed. Code: ${event.code}, Reason: ${event.reason}`,
+					);
+					logger.log(
+						`WebSocket connection closed. Code: ${event.code}, Reason: ${event.reason}`,
+					);
+				});
+			});
+		}
+
+		throw new Error(
+			`Unsupported connection protocol: ${addr.protocol}. Only 'ws:' and 'wss:' are supported`,
+		);
 	}
 
 	/**
@@ -553,9 +599,9 @@ export class Cc65DebugSession extends LoggingDebugSession {
 
 			case "attach":
 				{
-					const { port, host = "localhost" } = this._session.configuration;
+					const { address } = this._session.configuration;
 					try {
-						await this.connectAdapter(port, host);
+						await this.connectAdapter(address);
 					} catch (error) {
 						return this.sendErrorResponse(response, {
 							id: ErrorCodes.DAP_CONNECT_ERROR,
@@ -591,11 +637,13 @@ export class Cc65DebugSession extends LoggingDebugSession {
 		request?: DebugProtocol.Request,
 	) {
 		console.log("attachRequest", args);
-		return this.sendErrorResponse(response, {
-			id: ErrorCodes.DAP_NOT_SUPPORTED,
-			format: "Attaching to TCP port is not yet supported.",
-			showUser: true,
-		});
+
+		if (!this._connected)
+			return this.sendErrorResponse(response, {
+				id: ErrorCodes.DAP_CONNECT_ERROR,
+				format: "Connection to the debug server was not established",
+				showUser: true,
+			});
 	}
 
 	protected disconnectRequest(

yarn.lock

@@ -299,6 +299,13 @@
     wrap-ansi "^8.1.0"
     wrap-ansi-cjs "npm:wrap-ansi@^7.0.0"
 
+"@types/node@*":
+  version "22.15.18"
+  resolved "https://registry.yarnpkg.com/@types/node/-/node-22.15.18.tgz#2f8240f7e932f571c2d45f555ba0b6c3f7a75963"
+  integrity sha512-v1DKRfUdyW+jJhZNEI1PYy29S2YRxMV5AOO/x/SjKmW0acCIOqmbj6Haf9eHAhsPmrhlHSxEhv/1WszcLWV4cg==
+  dependencies:
+    undici-types "~6.21.0"
+
 "@types/node@22.x":
   version "22.15.3"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-22.15.3.tgz#b7fb9396a8ec5b5dfb1345d8ac2502060e9af68b"
@@ -311,6 +318,13 @@
   resolved "https://registry.yarnpkg.com/@types/vscode/-/vscode-1.99.1.tgz#bde6e2d9ccbe0493fded98ad639bf2671b8ec9ee"
   integrity sha512-cQlqxHZ040ta6ovZXnXRxs3fJiTmlurkIWOfZVcLSZPcm9J4ikFpXuB7gihofGn5ng+kDVma5EmJIclfk0trPQ==
 
+"@types/ws@^8.18.1":
+  version "8.18.1"
+  resolved "https://registry.yarnpkg.com/@types/ws/-/ws-8.18.1.tgz#48464e4bf2ddfd17db13d845467f6070ffea4aa9"
+  integrity sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==
+  dependencies:
+    "@types/node" "*"
+
 "@vscode/debugadapter@^1.68.0":
   version "1.68.0"
   resolved "https://registry.yarnpkg.com/@vscode/debugadapter/-/debugadapter-1.68.0.tgz#abb23463cb750ca4a6f0834c5d4db659258dc159"
@@ -1867,6 +1881,11 @@ wrappy@1:
   resolved "https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f"
   integrity sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=
 
+ws@^8.18.2:
+  version "8.18.2"
+  resolved "https://registry.yarnpkg.com/ws/-/ws-8.18.2.tgz#42738b2be57ced85f46154320aabb51ab003705a"
+  integrity sha512-DMricUmwGZUVr++AEAe2uiVM7UoO9MAVZMDu05UQOaUII0lp+zOzLLU4Xqh/JvTqklB1T4uELaaPBKyjE1r4fQ==
+
 xml2js@^0.5.0:
   version "0.5.0"
   resolved "https://registry.yarnpkg.com/xml2js/-/xml2js-0.5.0.tgz#d9440631fbb2ed800203fad106f2724f62c493b7"