@naeemo/capnp 0.7.0 → 0.8.0

package/dist/{rpc-connection-_eHtWsk2.js → rpc-connection-OuadMfAW.js}

@@ -1,4 +1,85 @@
 
+//#region src/debug/config.ts
+/**
+* Global debug state
+*/
+const debugState = {
+	enabled: false,
+	options: {
+		colors: true,
+		maxBytes: 256,
+		filter: ""
+	}
+};
+/**
+* Check if running in Node.js environment
+*/
+function isNode$1() {
+	return typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+}
+/**
+* Check CAPNP_DEBUG environment variable in Node.js
+*/
+function checkEnvVar() {
+	if (isNode$1()) try {
+		const envValue = process.env.CAPNP_DEBUG;
+		return envValue === "1" || envValue === "true";
+	} catch {
+		return false;
+	}
+	return false;
+}
+if (checkEnvVar()) debugState.enabled = true;
+/**
+* Enable debug mode with optional configuration
+*
+* @param options - Debug configuration options
+* @example
+* ```typescript
+* enableDebug({ colors: true, maxBytes: 512 });
+* ```
+*/
+function enableDebug(options) {
+	debugState.enabled = true;
+	if (options) debugState.options = {
+		...debugState.options,
+		...options
+	};
+}
+/**
+* Disable debug mode
+*
+* @example
+* ```typescript
+* disableDebug();
+* ```
+*/
+function disableDebug() {
+	debugState.enabled = false;
+}
+/**
+* Check if debug mode is currently enabled
+*
+* @returns True if debug mode is enabled
+* @example
+* ```typescript
+* if (isDebugEnabled()) {
+*   console.log('Debug is on');
+* }
+* ```
+*/
+function isDebugEnabled() {
+	return debugState.enabled;
+}
+/**
+* Get current debug options (internal use)
+* @internal
+*/
+function getDebugOptions() {
+	return Object.freeze({ ...debugState.options });
+}
+
+//#endregion
 //#region src/rpc/four-tables.ts
 /** Manages the question table for outbound calls */
 var QuestionTable = class {
@@ -197,6 +278,238 @@ var ExportTable = class {
 	}
 };
 
+//#endregion
+//#region src/debug/index.ts
+/**
+* Default configuration for debug logging
+*/
+const DEFAULT_CONFIG = {
+	enabled: false,
+	colors: true,
+	maxBytesToLog: 1024
+};
+/**
+* ANSI color codes for Node.js output
+*/
+const ANSI_COLORS = {
+	reset: "\x1B[0m",
+	bright: "\x1B[1m",
+	dim: "\x1B[2m",
+	red: "\x1B[31m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	blue: "\x1B[34m",
+	magenta: "\x1B[35m",
+	cyan: "\x1B[36m",
+	white: "\x1B[37m",
+	gray: "\x1B[90m"
+};
+/**
+* CSS styles for browser console output
+*/
+const BROWSER_STYLES = {
+	header: "color: #6c757d; font-weight: bold;",
+	send: "color: #28a745; font-weight: bold;",
+	recv: "color: #007bff; font-weight: bold;",
+	hex: "color: #6c757d;",
+	ascii: "color: #495057;",
+	arrow: "color: #6c757d;",
+	parsed: "color: #17a2b8;"
+};
+/**
+* Check if running in Node.js environment
+*/
+function isNode() {
+	return typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+}
+/**
+* Format a byte as two-digit hex string
+*/
+function byteToHex(byte) {
+	return byte.toString(16).padStart(2, "0");
+}
+/**
+* Check if a byte is printable ASCII
+*/
+function isPrintable(byte) {
+	return byte >= 32 && byte < 127;
+}
+/**
+* Format binary data as hex + ASCII (like hexdump -C)
+*
+* Output format:
+* 00000000: 00 00 00 00 02 00 00 00  │........│
+*
+* @param data - The binary data to format
+* @param maxBytes - Maximum number of bytes to format
+* @param useColors - Whether to include ANSI colors
+* @returns Array of formatted lines
+*/
+function formatHexDump(data, maxBytes = 1024, useColors = false) {
+	const lines = [];
+	const bytesToFormat = Math.min(data.length, maxBytes);
+	const bytesPerLine = 16;
+	for (let offset = 0; offset < bytesToFormat; offset += bytesPerLine) {
+		const chunk = data.slice(offset, Math.min(offset + bytesPerLine, bytesToFormat));
+		let line = `${byteToHex(offset >> 24 & 255)}${byteToHex(offset >> 16 & 255)}${byteToHex(offset >> 8 & 255)}${byteToHex(offset & 255)}: `;
+		const hexParts = [];
+		for (let i = 0; i < bytesPerLine; i++) {
+			if (i < chunk.length) hexParts.push(byteToHex(chunk[i]));
+			else hexParts.push("  ");
+			if (i === 7) hexParts.push("");
+		}
+		line += hexParts.join(" ");
+		let ascii = " │";
+		for (let i = 0; i < chunk.length; i++) ascii += isPrintable(chunk[i]) ? String.fromCharCode(chunk[i]) : ".";
+		ascii += "│";
+		line += ascii;
+		if (useColors && isNode()) {
+			const hexStart = line.indexOf(":") + 2;
+			const delimiterIndex = line.indexOf("│");
+			const hexPart = line.slice(hexStart, delimiterIndex);
+			const asciiPart = line.slice(delimiterIndex);
+			line = line.slice(0, hexStart) + ANSI_COLORS.gray + hexPart + ANSI_COLORS.reset + ANSI_COLORS.dim + asciiPart + ANSI_COLORS.reset;
+		}
+		lines.push(line);
+	}
+	if (data.length > maxBytes) {
+		const remaining = data.length - maxBytes;
+		lines.push(`... (${remaining} more bytes)`);
+	}
+	return lines;
+}
+/**
+* Debug logger for Cap'n Proto RPC messages
+*/
+var DebugLogger = class {
+	config;
+	/**
+	* Create a new DebugLogger instance
+	* @param config - Partial configuration to override defaults
+	*/
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Update the logger configuration
+	* @param config - Partial configuration to merge
+	*/
+	setConfig(config) {
+		this.config = {
+			...this.config,
+			...config
+		};
+	}
+	/**
+	* Get current configuration
+	*/
+	getConfig() {
+		return { ...this.config };
+	}
+	/**
+	* Check if debugging is enabled
+	*/
+	isEnabled() {
+		return this.config.enabled;
+	}
+	/**
+	* Enable debug logging
+	*/
+	enable() {
+		this.config.enabled = true;
+	}
+	/**
+	* Disable debug logging
+	*/
+	disable() {
+		this.config.enabled = false;
+	}
+	/**
+	* Format the header for a log message
+	* @param direction - 'send' or 'recv'
+	* @param byteLength - Number of bytes
+	* @returns Formatted header string
+	*/
+	formatHeader(direction, byteLength) {
+		const prefix = direction === "send" ? "CAPNP:SEND" : "CAPNP:RECV";
+		if (isNode() && this.config.colors) return `${direction === "send" ? ANSI_COLORS.green : ANSI_COLORS.blue}[${prefix}]${ANSI_COLORS.reset} ${byteLength} bytes`;
+		return `[${prefix}] ${byteLength} bytes`;
+	}
+	/**
+	* Log a Cap'n Proto message
+	*
+	* Output format:
+	* [CAPNP:SEND] 64 bytes
+	* 00000000: 00 00 00 00 02 00 00 00  │........│
+	* → { messageType: 'Bootstrap', ... }
+	*
+	* @param direction - 'send' for outgoing, 'recv' for incoming
+	* @param data - The raw binary message data
+	* @param parsed - Optional parsed message object to display
+	*/
+	logMessage(direction, data, parsed) {
+		if (!this.config.enabled) return;
+		const isNodeEnv = isNode();
+		const useColors = this.config.colors;
+		const header = this.formatHeader(direction, data.length);
+		const hexLines = formatHexDump(data, this.config.maxBytesToLog, useColors);
+		if (isNodeEnv) {
+			console.log(header);
+			for (const line of hexLines) console.log(line);
+			if (parsed !== void 0) {
+				const arrow = useColors ? `${ANSI_COLORS.gray}→${ANSI_COLORS.reset}` : "→";
+				const parsedStr = JSON.stringify(parsed, null, 2);
+				const coloredParsed = useColors ? `${ANSI_COLORS.cyan}${parsedStr}${ANSI_COLORS.reset}` : parsedStr;
+				console.log(`${arrow} ${coloredParsed}`);
+			}
+		} else if (useColors) {
+			const style = direction === "send" ? BROWSER_STYLES.send : BROWSER_STYLES.recv;
+			console.log(`%c[CAPNP:${direction.toUpperCase()}]%c ${data.length} bytes`, style, "color: inherit;");
+			for (const line of hexLines) console.log(`%c${line}`, BROWSER_STYLES.hex);
+			if (parsed !== void 0) console.log("%c→%c %o", BROWSER_STYLES.arrow, BROWSER_STYLES.parsed, parsed);
+		} else {
+			console.log(header);
+			for (const line of hexLines) console.log(line);
+			if (parsed !== void 0) console.log("→", parsed);
+		}
+	}
+	/**
+	* Log a generic debug message (only if enabled)
+	* @param message - Message to log
+	* @param args - Additional arguments
+	*/
+	log(message, ...args) {
+		if (!this.config.enabled) return;
+		if (isNode() && this.config.colors) console.log(`${ANSI_COLORS.gray}[CAPNP:DEBUG]${ANSI_COLORS.reset} ${message}`, ...args);
+		else console.log(`[CAPNP:DEBUG] ${message}`, ...args);
+	}
+	/**
+	* Log an error message (always shown if debug is enabled)
+	* @param message - Error message
+	* @param error - Optional error object
+	*/
+	error(message, error) {
+		if (!this.config.enabled) return;
+		if (isNode() && this.config.colors) console.error(`${ANSI_COLORS.red}[CAPNP:ERROR]${ANSI_COLORS.reset} ${message}`, error ?? "");
+		else console.error(`[CAPNP:ERROR] ${message}`, error ?? "");
+	}
+};
+/**
+* Create a default debug logger instance
+* @param config - Optional configuration
+* @returns DebugLogger instance
+*/
+function createDebugLogger(config) {
+	return new DebugLogger(config);
+}
+/**
+* Global debug logger instance for convenience
+*/
+const debug = new DebugLogger();
+
 //#endregion
 //#region src/rpc/pipeline.ts
 /**
@@ -1458,9 +1771,26 @@ function serializeListSchemasResults(results) {
 
 //#endregion
 //#region src/rpc/rpc-connection.ts
+/**
+* RpcConnection
+*
+* Manages a single RPC connection, handling message routing and the Four Tables.
+* This is the core of the RPC implementation.
+*
+* Phase 2 Updates:
+* - Added Promise Pipelining support
+* - Added capability passing
+* - Added Resolve/Release/Disembargo message handling
+*
+* Phase 4 Updates:
+* - Added Level 3 RPC support (Provide/Accept)
+* - Added third-party capability handling
+* - Integrated with ConnectionManager for multi-vat scenarios
+*/
 var RpcConnection = class {
 	transport;
 	options;
+	debugLogger = createDebugLogger();
 	questions = new QuestionTable();
 	answers = new AnswerTable();
 	imports = new ImportTable();
@@ -1479,6 +1809,11 @@ var RpcConnection = class {
 		this.transport = transport;
 		this.options = options;
 		this.level3Handlers = options.level3Handlers;
+		if (options.debug ?? isDebugEnabled()) {
+			this.debugLogger.enable();
+			this.debugLogger.setConfig(getDebugOptions());
+			this.debugLogger.log("RPC connection created");
+		}
 		this.transport.onClose = (reason) => {
 			this.handleDisconnect(reason);
 		};
@@ -1509,7 +1844,7 @@ var RpcConnection = class {
 			type: "bootstrap",
 			bootstrap: { questionId: question.id }
 		};
-		await this.transport.send(bootstrapMsg);
+		await this.sendWithLogging(bootstrapMsg);
 		await question.completionPromise;
 		return {};
 	}
@@ -1534,7 +1869,7 @@ var RpcConnection = class {
 				sendResultsTo: { type: "caller" }
 			}
 		};
-		await this.transport.send(callMsg);
+		await this.sendWithLogging(callMsg);
 		return question.completionPromise;
 	}
 	/**
@@ -1560,7 +1895,7 @@ var RpcConnection = class {
 				sendResultsTo: { type: "caller" }
 			}
 		};
-		await this.transport.send(callMsg);
+		await this.sendWithLogging(callMsg);
 		return createPipelineClient({
 			connection: this,
 			questionId: question.id
@@ -1577,7 +1912,7 @@ var RpcConnection = class {
 				requireEarlyCancellationWorkaround: false
 			}
 		};
-		await this.transport.send(finishMsg);
+		await this.sendWithLogging(finishMsg);
 		this.questions.markFinishSent(questionId);
 		this.questions.remove(questionId);
 	}
@@ -1590,7 +1925,7 @@ var RpcConnection = class {
 				referenceCount
 			}
 		};
-		await this.transport.send(releaseMsg);
+		await this.sendWithLogging(releaseMsg);
 	}
 	/** Send a resolve message to indicate a promise has resolved */
 	async resolve(promiseId, cap) {
@@ -1604,7 +1939,7 @@ var RpcConnection = class {
 				}
 			}
 		};
-		await this.transport.send(resolveMsg);
+		await this.sendWithLogging(resolveMsg);
 	}
 	/** Send a resolve message indicating a promise was broken */
 	async resolveException(promiseId, reason) {
@@ -1621,7 +1956,7 @@ var RpcConnection = class {
 				}
 			}
 		};
-		await this.transport.send(resolveMsg);
+		await this.sendWithLogging(resolveMsg);
 	}
 	/** Send a return message (internal use) */
 	async sendReturn(ret) {
@@ -1629,7 +1964,7 @@ var RpcConnection = class {
 			type: "return",
 			return: ret
 		};
-		await this.transport.send(returnMsg);
+		await this.sendWithLogging(returnMsg);
 	}
 	/** Send a disembargo message (internal use) */
 	async sendDisembargo(disembargo) {
@@ -1637,7 +1972,7 @@ var RpcConnection = class {
 			type: "disembargo",
 			disembargo
 		};
-		await this.transport.send(disembargoMsg);
+		await this.sendWithLogging(disembargoMsg);
 	}
 	/** Internal method: Create a new question (used by pipeline) */
 	createQuestion() {
@@ -1649,7 +1984,7 @@ var RpcConnection = class {
 			type: "call",
 			call
 		};
-		await this.transport.send(callMsg);
+		await this.sendWithLogging(callMsg);
 	}
 	/** Internal method: Wait for an answer (used by pipeline) */
 	async waitForAnswer(questionId) {
@@ -1660,7 +1995,7 @@ var RpcConnection = class {
 	/** Main message processing loop */
 	async messageLoop() {
 		while (this.running) try {
-			const message = await this.transport.receive();
+			const message = await this.receiveWithLogging();
 			if (message === null) break;
 			await this.handleMessage(message);
 		} catch (error) {
@@ -1725,7 +2060,7 @@ var RpcConnection = class {
 				}
 			}
 		};
-		await this.transport.send(returnMsg);
+		await this.sendWithLogging(returnMsg);
 		this.answers.markReturnSent(bootstrap.questionId);
 	}
 	/** Handle incoming call */
@@ -1746,7 +2081,7 @@ var RpcConnection = class {
 				}
 			}
 		};
-		await this.transport.send(returnMsg);
+		await this.sendWithLogging(returnMsg);
 		this.answers.markReturnSent(call.questionId);
 	}
 	/** Handle return message */
@@ -1816,7 +2151,7 @@ var RpcConnection = class {
 					}
 				}
 			};
-			await this.transport.send(echoMsg);
+			await this.sendWithLogging(echoMsg);
 		}
 	}
 	/** Handle provide message (Level 3) */
@@ -1873,7 +2208,7 @@ var RpcConnection = class {
 			type: "unimplemented",
 			message: originalMessage
 		};
-		await this.transport.send(msg);
+		await this.sendWithLogging(msg);
 	}
 	/** Send return exception (helper) */
 	async sendReturnException(questionId, reason) {
@@ -1892,7 +2227,7 @@ var RpcConnection = class {
 				}
 			}
 		};
-		await this.transport.send(returnMsg);
+		await this.sendWithLogging(returnMsg);
 	}
 	/**
 	* Set the Level 4 handlers for this connection.
@@ -2039,7 +2374,7 @@ var RpcConnection = class {
 				sendResultsTo: { type: "caller" }
 			}
 		};
-		await this.transport.send(schemaRequestMsg);
+		await this.sendWithLogging(schemaRequestMsg);
 		const question = this.questions.create();
 		question.id = questionId;
 		try {
@@ -2133,7 +2468,7 @@ var RpcConnection = class {
 				sendResultsTo: { type: "caller" }
 			}
 		};
-		await this.transport.send(listRequestMsg);
+		await this.sendWithLogging(listRequestMsg);
 		const question = this.questions.create();
 		question.id = questionId;
 		try {
@@ -2152,6 +2487,17 @@ var RpcConnection = class {
 			throw error;
 		}
 	}
+	/** Send a message with debug logging */
+	async sendWithLogging(message) {
+		if (this.debugLogger.isEnabled()) this.debugLogger.log(`[RPC:SEND] ${message.type}`);
+		await this.transport.send(message);
+	}
+	/** Receive a message with debug logging */
+	async receiveWithLogging() {
+		const message = await this.transport.receive();
+		if (message !== null && this.debugLogger.isEnabled()) this.debugLogger.log(`[RPC:RECV] ${message.type}`);
+		return message;
+	}
 };
 
 //#endregion
@@ -2251,6 +2597,24 @@ Object.defineProperty(exports, 'deserializeSchemaResponse', {
     return deserializeSchemaResponse;
   }
 });
+Object.defineProperty(exports, 'disableDebug', {
+  enumerable: true,
+  get: function () {
+    return disableDebug;
+  }
+});
+Object.defineProperty(exports, 'enableDebug', {
+  enumerable: true,
+  get: function () {
+    return enableDebug;
+  }
+});
+Object.defineProperty(exports, 'isDebugEnabled', {
+  enumerable: true,
+  get: function () {
+    return isDebugEnabled;
+  }
+});
 Object.defineProperty(exports, 'isPipelineClient', {
   enumerable: true,
   get: function () {
@@ -2293,4 +2657,4 @@ Object.defineProperty(exports, 'serializeSchemaResponse', {
     return serializeSchemaResponse;
   }
 });
-//# sourceMappingURL=rpc-connection-_eHtWsk2.js.map
+//# sourceMappingURL=rpc-connection-OuadMfAW.js.map