28254649616

Committed 26 Jun 2026 05:33PM UTC coverage: 72.796% (+0.1%) from 72.684%

Build # 28254649616

Build Type

Pull #323

github

Committed by

web-flow

Commit Message

Merge 0e2d1d7e2 into 025a474d2

Pull Request Pull Request #323: apply postfix for Library statement

Coverage Stats

3754 of 5392 branches covered (69.62%)

Branch coverage included in aggregate %.

116 of 121 new or added lines in 5 files covered. (95.87%)

591 existing lines in 3 files now uncovered.

5941 of 7926 relevant lines covered (74.96%)

47.23 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

59.85

/src/adapters/DebugProtocolAdapter.ts

import * as EventEmitter from 'events';
import { Socket } from 'net';
import { DiagnosticSeverity, util as bscUtil } from 'brighterscript';
import type { BSDebugDiagnostic } from '../CompileErrorProcessor';
import { CompileErrorProcessor } from '../CompileErrorProcessor';
import type { RendezvousHistory, RendezvousTracker } from '../RendezvousTracker';
import type { ChanperfData } from '../ChanperfTracker';
import { ChanperfTracker } from '../ChanperfTracker';
import { ErrorCode, PROTOCOL_ERROR_CODES, UpdateType } from '../debugProtocol/Constants';
import { defer, util } from '../util';
import { logger } from '../logging';
import type { AdapterOptions, HighLevelType, RokuAdapterEvaluateResponse } from '../interfaces';
import type { BreakpointManager } from '../managers/BreakpointManager';
import type { ProjectManager } from '../managers/ProjectManager';
import type { BreakpointsVerifiedEvent, ConstructorOptions, ProtocolVersionDetails } from '../debugProtocol/client/DebugProtocolClient';
import { DebugProtocolClient } from '../debugProtocol/client/DebugProtocolClient';
import { ProtocolCapabilities } from '../debugProtocol/client/ProtocolCapabilities';
import type { Variable } from '../debugProtocol/events/responses/VariablesResponse';
import { VariableType } from '../debugProtocol/events/responses/VariablesResponse';
import type { TelnetAdapter } from './TelnetAdapter';
import type { DeviceInfo } from 'roku-deploy';
import type { ThreadsResponse } from '../debugProtocol/events/responses/ThreadsResponse';
import type { ExceptionBreakpoint } from '../debugProtocol/events/requests/SetExceptionBreakpointsRequest';
import { insertCustomVariables, overrideKeyTypesForCustomVariables } from './customVariableUtils';
import type { DebugProtocol } from '@vscode/debugprotocol';
import { SocketConnectionInUseError } from '../Exceptions';

/**
 * A class that connects to a Roku device over telnet debugger port and provides a standardized way of interacting with it.
 */
export class DebugProtocolAdapter {
    constructor(
        private options: AdapterOptions & ConstructorOptions,
        private projectManager: ProjectManager,
        private breakpointManager: BreakpointManager,
        private rendezvousTracker: RendezvousTracker,
        private deviceInfo: DeviceInfo
    ) {
        util.normalizeAdapterOptions(this.options);
        this.emitter = new EventEmitter();
        this.chanperfTracker = new ChanperfTracker();
        this.compileErrorProcessor = new CompileErrorProcessor();
        this.connected = false;
        //capabilities derived from device-info; used to answer questions before the debug
        //protocol client has connected and completed its handshake
        this.fallbackCapabilities = new ProtocolCapabilities(this.deviceInfo?.brightscriptDebuggerVersion, this.deviceInfo?.softwareVersion);

        // watch for chanperf events
        this.chanperfTracker.on('chanperf', (output) => {
            this.emit('chanperf', output);
        });
    }

    private logger = logger.createLogger(`[padapter]`);

    /**
     * Capabilities seeded from the device-info `brightscript-debugger-version`. Used as the
     * source of truth for protocol capability questions before the debug protocol client has
     * connected and completed its handshake.
     */
    private fallbackCapabilities: ProtocolCapabilities;

    /**
     * The current authoritative capabilities for protocol-version-driven questions: the live
     * client's capabilities once it exists, otherwise the device-info-seeded fallback.
     */
    private get capabilities(): ProtocolCapabilities {
        return this.client?.capabilities ?? this.fallbackCapabilities;
    }

    /**
     * Indicates whether the adapter has successfully established a connection with the device
     */
    public connected: boolean;

    private compileClient: Socket;
    private compileErrorProcessor: CompileErrorProcessor;
    private emitter: EventEmitter;
    private chanperfTracker: ChanperfTracker;
    private client: DebugProtocolClient;
    private nextFrameId = 1;

    private stackFramesCache: Record<number, StackFrame> = {};
    private cache = {};

    /**
     * Get the version of the protocol for the Roku device we're currently connected to.
     */
    public get activeProtocolVersion() {
        return this.client?.protocolVersion;
    }

    /**
     * Subscribe to an event exactly once
     * @param eventName
     */
    public once(eventName: 'cannot-continue'): Promise<void>;
    public once(eventname: 'chanperf'): Promise<ChanperfData>;
    public once(eventName: 'close'): Promise<void>;
    public once(eventName: 'app-exit'): Promise<void>;
    public once(eventName: 'app-ready'): Promise<void>;
    public once(eventName: 'diagnostics'): Promise<BSDebugDiagnostic>;
    public once(eventName: 'connected'): Promise<boolean>;
    public once(eventname: 'console-output'): Promise<string>; // TODO: might be able to remove this at some point
    public once(eventname: 'protocol-version'): Promise<ProtocolVersionDetails>;
    public once(eventname: 'rendezvous'): Promise<RendezvousHistory>;
    public once(eventName: 'runtime-error'): Promise<BrightScriptRuntimeError>;
    public once(eventName: 'suspend'): Promise<void>;
    public once(eventName: 'start'): Promise<void>;
    public once(eventname: 'device-unresponsive'): Promise<void>;
    public once(eventname: 'unhandled-console-output'): Promise<string>;
    public once(eventName: string) {
        return new Promise((resolve) => {
            const disconnect = this.on(eventName as Parameters<DebugProtocolAdapter['on']>[0], (...args) => {
                disconnect();
                resolve(...args);
            });
        });
    }

    /**
     * Subscribe to various events
     * @param eventName
     * @param handler
     */
    public on(eventName: 'breakpoints-verified', handler: (event: BreakpointsVerifiedEvent) => any);
    public on(eventName: 'cannot-continue', handler: () => any);
    public on(eventname: 'chanperf', handler: (output: ChanperfData) => any);
    public on(eventName: 'close', handler: () => any);
    public on(eventName: 'app-exit', handler: () => any);
    public on(eventName: 'diagnostics', handler: (params: BSDebugDiagnostic[]) => any);
    public on(eventName: 'launch-status', handler: (message: string) => any);
    public on(eventName: 'connected', handler: (params: boolean) => any);
    public on(eventname: 'console-output', handler: (output: string) => any); // TODO: might be able to remove this at some point.
    public on(eventname: 'protocol-version', handler: (output: ProtocolVersionDetails) => any);
    public on(eventName: 'runtime-error', handler: (error: BrightScriptRuntimeError) => any);
    public on(eventName: 'suspend', handler: () => any);
    public on(eventName: 'start', handler: () => any);
    public on(eventName: 'waiting-for-debugger', handler: () => any);
    public on(eventName: 'device-unresponsive', handler: (data: { lastCommand: string }) => any);
    public on(eventname: 'unhandled-console-output', handler: (output: string) => any);
    public on(eventName: string, handler: (payload: any) => any) {
        this.emitter?.on(eventName, handler);
        return () => {
            this.emitter?.removeListener(eventName, handler);
        };
    }

    private emit(eventName: 'suspend');
    private emit(eventName: 'breakpoints-verified', event: BreakpointsVerifiedEvent);
    private emit(eventName: 'diagnostics', data: BSDebugDiagnostic[]);
    private emit(eventName: 'launch-status', message: string);
    private emit(eventName: 'app-exit' | 'app-ready' | 'cannot-continue' | 'chanperf' | 'close' | 'connected' | 'console-output' | 'protocol-version' | 'rendezvous' | 'runtime-error' | 'start' | 'unhandled-console-output' | 'waiting-for-debugger' | 'device-unresponsive', data?);
    private emit(eventName: string, data?) {
        //emit these events on next tick, otherwise they will be processed immediately which could cause issues
        setTimeout(() => {
            //in rare cases, this event is fired after the debugger has closed, so make sure the event emitter still exists
            if (!this.emitter) {
                return;
            }
            //drop stale 'suspend'/'runtime-error' events when the debugger has already resumed.
            //emit() defers via setTimeout, so isStopped can flip false between queue and fire (e.g. auto-continue on entry breakpoint),
            //causing downstream handlers to call getThreads() against a running debugger.
            //See https://github.com/rokucommunity/vscode-brightscript-language/issues/798
            if ((eventName === 'suspend' || eventName === 'runtime-error') && !this.isAtDebuggerPrompt) {
                this.logger.warn(`Dropping stale "${eventName}" event because debugger is no longer paused`);
                return;
            }
            this.emitter.emit(eventName, data);
        }, 0);
    }

    /**
     * Does the current client support exception breakpoints? Resolved via the live client's
     * capabilities when connected, otherwise the device-info-seeded fallback.
     */
    public get supportsExceptionBreakpoints(): boolean {
        return this.capabilities.supportsExceptionBreakpoints;
    }

    /**
     * Does the current client support conditional breakpoints? Same fallback semantics as
     * `supportsExceptionBreakpoints`.
     */
    public get supportsConditionalBreakpoints(): boolean {
        return this.capabilities.supportsConditionalBreakpoints;
    }

    /**
     * Does the current client support hit-count breakpoints?
     */
    public get supportsHitConditionalBreakpoints(): boolean {
        return this.capabilities.supportsHitConditionalBreakpoints;
    }

    /**
     * The debugger needs to tell us when to be active (i.e. when the package was deployed)
     */
    public isActivated = false;

    /**
     * This will be set to true When the roku emits the [scrpt.ctx.run.enter] text,
     * which indicates that the app is running on the Roku
     */
    public isAppRunning = false;

    public activate() {
        this.isActivated = true;
        this.handleStartupIfReady();
    }

    public async sendErrors() {
        await this.compileErrorProcessor.sendErrors();
    }

    private handleStartupIfReady() {
        if (this.isActivated && this.isAppRunning) {
            this.emit('start');

            //if we are already sitting at a debugger prompt, we need to emit the first suspend event.
            //If not, then there are probably still messages being received, so let the normal handler
            //emit the suspend event when it's ready
            if (this.isAtDebuggerPrompt === true) {
                this.emit('suspend');
            }
        }
    }

    /**
     * Wait until the client has stopped sending messages. This is used mainly during .connect so we can ignore all old messages from the server
     * @param client
     * @param maxWaitMilliseconds
     */
    private settleCompileClient(client: Socket, maxWaitMilliseconds = 400) {
        return new Promise<string>((resolve) => {
            let timeoutStarted = false;
            let callCount = -1;
            let logs = '';

            function handler(buffer) {
                callCount++;
                logs += buffer.toString();
                let myCallCount = callCount;
                timeoutStarted = true;
                setTimeout(() => {
                    if (myCallCount === callCount) {
                        // stop listening for data events
                        client.removeListener('data', handler);
                        resolve(logs);
                    }
                }, maxWaitMilliseconds);
            }

            const startTimeout = () => {
                if (timeoutStarted === false) {
                    handler(Buffer.from(''));
                }
            };

            // watch for data events
            client.on('data', handler);

            // watch for different connection related events to start the timeout logic
            client.on('ready', startTimeout);
            client.on('end', startTimeout);
            client.on('closed', startTimeout);
        });
    }

    public get isAtDebuggerPrompt() {
        return this.client?.isStopped ?? false;
    }

    private firstConnectDeferred = defer<void>();

    /**
     * Resolves when the first connection to the client is established
     */
    public onReady() {
        return this.firstConnectDeferred.promise;
    }

    /**
     * Connect to the telnet session. This should be called before the channel is launched.
     */
    public async connect(): Promise<void> {
        //Start processing telnet output to look for compile errors or the debugger prompt
        await this.processTelnetOutput();

        this.on('waiting-for-debugger', async () => { // eslint-disable-line @typescript-eslint/no-misused-promises
            await this.createDebugProtocolClient();

            //if this is the first time we are connecting, resolve the promise.
            //(future events fire for "reconnect" situations, we don't need to resolve again for those)
            if (!this.firstConnectDeferred.isCompleted) {
                this.firstConnectDeferred.resolve();
            }
        });
    }

    public async createDebugProtocolClient() {
        let deferred = defer();
        if (this.client) {
            await Promise.race([
                util.sleep(2000),
                await this.client.destroy()
            ]);
            this.client = undefined;
            //keep `connected` in sync with `client` so the _syncBreakpoints entry guard
            //(and similar checks elsewhere) reflects the actual state. Restored to true below
            //once the new client finishes connecting.
            this.connected = false;
        }
        this.client = new DebugProtocolClient(this.options);
        try {
            // Emit IO from the debugger.
            // eslint-disable-next-line @typescript-eslint/no-misused-promises
            this.client.on('io-output', async (responseText) => {
                if (typeof responseText === 'string') {
                    responseText = this.chanperfTracker.processLog(responseText);
                    responseText = await this.rendezvousTracker.processLog(responseText);
                    this.emit('unhandled-console-output', responseText);
                    this.emit('console-output', responseText);
                }
            });

            // Emit IO from the debugger.
            this.client.on('protocol-version', (data: ProtocolVersionDetails) => {
                if (data.errorCode === PROTOCOL_ERROR_CODES.SUPPORTED) {
                    this.emit('console-output', data.message);
                } else if (data.errorCode === PROTOCOL_ERROR_CODES.NOT_TESTED) {
                    this.emit('unhandled-console-output', data.message);
                    this.emit('console-output', data.message);
                } else if (data.errorCode === PROTOCOL_ERROR_CODES.NOT_SUPPORTED) {
                    this.emit('unhandled-console-output', data.message);
                    this.emit('console-output', data.message);
                }

            });

            // Listen for the close event
            this.client.on('close', () => {
                this.emit('close');
                this.beginAppExit();
                void this.client?.destroy();
                this.client = undefined;
                //the protocol client is gone — keep `connected` in sync so any subsequent
                //syncBreakpoints / setExceptionBreakpoints calls during the close→app-exit
                //window early-return instead of dereferencing the undefined client.
                //See https://github.com/rokucommunity/vscode-brightscript-language/issues/811
                this.connected = false;
            });

            // Listen for the app exit event
            this.client.on('app-exit', () => {
                this.emit('app-exit');
                void this.client?.destroy();
                this.client = undefined;
            });

            this.client.on('suspend', (data) => {
                this.clearCache();
                this.emit('suspend');
            });

            this.client.on('runtime-error', (data) => {
                console.debug('hasRuntimeError!!', data);
                this.emit('runtime-error', <BrightScriptRuntimeError>{
                    message: data.data.stopReasonDetail,
                    errorCode: data.data.stopReason
                });
            });

            this.client.on('cannot-continue', () => {
                this.emit('cannot-continue');
            });

            //handle when the device verifies breakpoints
            this.client.on('breakpoints-verified', (event) => {
                let unverifiableDeviceIds = [] as number[];

                //mark the breakpoints as verified
                for (let breakpoint of event?.breakpoints ?? []) {
                    const success = this.breakpointManager.verifyBreakpoint(breakpoint.id, true);
                    if (!success) {
                        unverifiableDeviceIds.push(breakpoint.id);
                    }
                }
                //if there were any unsuccessful breakpoint verifications, we need to ask the device to delete those breakpoints as they've gone missing on our side
                if (unverifiableDeviceIds.length > 0) {
                    this.logger.warn('Could not find breakpoints to verify. Removing from device:', { deviceBreakpointIds: unverifiableDeviceIds });
                    void this.client.removeBreakpoints(unverifiableDeviceIds);
                }
                this.emit('breakpoints-verified', event);
            });

            this.client.on('compile-error', (update) => {
                let diagnostics: BSDebugDiagnostic[] = [];
                diagnostics.push({
                    path: update.data.filePath,
                    range: bscUtil.createRange(update.data.lineNumber - 1, 0, update.data.lineNumber - 1, 999),
                    message: update.data.errorMessage,
                    severity: DiagnosticSeverity.Error,
                    code: undefined
                });
                this.emit('diagnostics', diagnostics);
            });

            await this.client.connect();

            this.logger.log(`Connected to device`, { host: this.options.host, connected: this.connected });
            this.connected = true;
            this.isAppRunning = true;
            this.handleStartupIfReady();
            this.emit('connected', this.connected);
            this.emit('app-ready');
            //flush any breakpoints that were queued while we were waiting for the client to connect.
            //setBreakpointsRequest is called by VS Code before the channel is uploaded, so the initial
            //sync bails out (no client yet); this re-sync pushes those queued breakpoints to the device.
            void this.syncBreakpoints();
            //also replay any queued exception breakpoint filters
            if (this.pendingExceptionBreakpointFilters) {
                const queuedFilters = this.pendingExceptionBreakpointFilters;
                this.pendingExceptionBreakpointFilters = undefined;
                void this.client.setExceptionBreakpoints(queuedFilters);
            }

            //the adapter is connected and running smoothly. resolve the promise
            deferred.resolve();
        } catch (e) {
            deferred.reject(e);
        }
        return deferred.promise;
    }

    private beginAppExit() {
        this.compileErrorProcessor.compileErrorTimer = setTimeout(() => {
            this.isAppRunning = false;
            this.emit('app-exit');
        }, 200);
    }

    /**
     * Determines if the current version of the debug protocol supports emitting compile error updates.
     */
    public get supportsCompileErrorReporting() {
        return this.capabilities.supportsCompileErrorReporting;
    }

    /**
     * Indicate if virtual variables should be auto resolved when they are encountered.
     */
    public get autoResolveVirtualVariables() {
        return this.options.autoResolveVirtualVariables;
    }

    private processingTelnetOutput = false;
    public async processTelnetOutput() {
        if (this.processingTelnetOutput) {
            return;
        }
        this.processingTelnetOutput = true;

        let deferred = defer();
        try {
            this.compileClient = new Socket({ allowHalfOpen: false });
            util.registerSocketLogging(this.compileClient, this.logger, 'CompileClient');

            this.compileErrorProcessor.on('diagnostics', (errors) => {
                this.compileClient.end();
                this.emit('diagnostics', errors);
            });

            this.compileErrorProcessor.on('launch-status', (message) => {
                this.emit('launch-status', message);
            });

            //if the connection fails, reject the connect promise.
            //Use tryReject (not reject) because this handler persists for the socket's lifetime.
            //After a successful connection the deferred is already resolved, so a post-connection
            //socket error (e.g. ECONNRESET on device disconnect) must not crash the process.
            this.compileClient.on('error', (err) => {
                deferred.tryReject(new Error(`Error with connection to: ${this.options.host}:${this.options.brightScriptConsolePort} \n\n ${err.message} `));
            });
            this.logger.info('Connecting via telnet to gather compile info', { host: this.options.host, port: this.options.brightScriptConsolePort });
            this.compileClient.connect(this.options.brightScriptConsolePort, this.options.host, () => {
                this.logger.log(`CONNECTED via telnet to gather compile info`, { host: this.options.host, port: this.options.brightScriptConsolePort });
            });

            this.logger.debug('Waiting for the compile client to settle');
            const settledLogs = await this.settleCompileClient(this.compileClient);
            this.logger.debug('Compile client has settled');
            this.logger.trace('Settled logs:', settledLogs);

            if (settledLogs.trim().startsWith('Console connection is already in use.')) {
                throw new SocketConnectionInUseError(`Telnet connection ${this.options.host}:${this.options.brightScriptConsolePort} already is use`, {
                    port: this.options.brightScriptConsolePort,
                    host: this.options.host
                });
            }

            let lastPartialLine = '';
            this.compileClient.on('data', (buffer) => {
                let responseText = buffer.toString();
                this.logger.info('CompileClient received data', { responseText });

                let logResult = util.handleLogFragments(lastPartialLine, buffer.toString());

                // Save any remaining partial line for the next event
                lastPartialLine = logResult.remaining;
                if (logResult.completed) {
                    // Emit the completed io string.
                    this.findWaitForDebuggerPrompt(logResult.completed);
                    this.compileErrorProcessor.processUnhandledLines(logResult.completed);
                    this.logger.debug('CompileClient data:', logResult.completed);
                    this.emit('unhandled-console-output', logResult.completed);
                } else {
                    this.logger.debug('CompileClient buffer was split:', lastPartialLine);
                }
            });

            this.compileClient.on('close', () => {
                this.logger.log('compileClient socket closed');
                this.compileClientClosed.tryResolve();
            });

            // connected to telnet. resolve the promise
            deferred.resolve();
        } catch (e) {
            deferred.reject(e);
        }
        return deferred.promise;
    }

    private findWaitForDebuggerPrompt(responseText: string) {
        let lines = responseText.split(/\r?\n/g);
        for (const line of lines) {
            if (/Waiting for debugger on \d+\.\d+\.\d+\.\d+:8081/g.exec(line)) {
                this.emit('waiting-for-debugger');
            }
        }
    }

    /**
     * Send command to step over
     */
    public async stepOver(threadId: number) {
        this.clearCache();
        return this.client.stepOver(threadId);
    }

    public async stepInto(threadId: number) {
        this.clearCache();
        return this.client.stepIn(threadId);
    }

    public async stepOut(threadId: number) {
        this.clearCache();
        return this.client.stepOut(threadId);
    }

    /**
     * Tell the brightscript program to continue (i.e. resume program)
     */
    public async continue() {
        this.clearCache();
        return this.client.continue();
    }

    /**
     * Tell the brightscript program to pause (fall into debug mode)
     */
    public async pause() {
        this.clearCache();
        //send the kill signal, which breaks into debugger mode
        return this.client.pause();
    }

    /**
     * Clears the state, which means that everything will be retrieved fresh next time it is requested
     */
    public clearCache() {
        this.cache = {};
        this.stackFramesCache = {};
    }

    /**
     * Execute a command directly on the roku. Returns the output of the command
     * @param command
     * @returns the output of the command (if possible)
     */
    public async evaluate(command: string, frameId: number = this.client.primaryThread): Promise<RokuAdapterEvaluateResponse> {
        if (this.capabilities.supportsExecuteCommand) {
            if (!this.isAtDebuggerPrompt) {
                throw new Error('Cannot run evaluate: debugger is not paused');
            }

            let stackFrame = this.getStackFrameById(frameId);
            if (!stackFrame) {
                throw new Error('Cannot execute command without a corresponding frame');
            }
            this.logger.log('evaluate ', { command, frameId });

            const response = await this.client.executeCommand(command, stackFrame.frameIndex, stackFrame.threadIndex);
            this.logger.info('evaluate response', { command, response });
            if (response.data.executeSuccess) {
                return {
                    message: undefined,
                    type: 'message'
                };
            } else {
                const messages = [
                    ...response?.data?.compileErrors ?? [],
                    ...response?.data?.runtimeErrors ?? [],
                    ...response?.data?.otherErrors ?? []
                ];
                return {
                    message: messages[0] ?? 'Unknown error executing command',
                    type: 'error'
                };
            }
        } else {
            return {
                message: `Execute commands are not supported on debug protocol: ${this.activeProtocolVersion}, v3.0.0 or greater is required.`,
                type: 'error'
            };
        }
    }

    public async getStackTrace(threadIndex: number = this.client.primaryThread) {
        if (!this.isAtDebuggerPrompt) {
            throw new Error('Cannot get stack trace: debugger is not paused');
        }
        return this.resolve(`stack trace for thread ${threadIndex}`, async () => {
            let thread = await this.getThreadByThreadId(threadIndex);
            let frames: StackFrame[] = [];
            let stackTraceData = await this.client.getStackTrace(threadIndex);

            // Non-OK error code (e.g. THREAD_DETACHED) means we can not provide the stack trace
            if (stackTraceData?.data?.errorCode !== undefined && stackTraceData.data.errorCode !== ErrorCode.OK) {
                this.logger.warn(`getStackTrace for thread ${threadIndex} failed with errorCode ${stackTraceData.data.errorCode}`);
                return frames;
            }
            for (let i = 0; i < (stackTraceData?.data?.entries?.length ?? 0); i++) {
                let frameData = stackTraceData.data.entries[i];
                let stackFrame: StackFrame = {
                    frameId: this.nextFrameId++,
                    // frame index is the reverse of the returned order.
                    frameIndex: stackTraceData.data.entries.length - i - 1,
                    threadIndex: threadIndex,
                    filePath: frameData.filePath,
                    lineNumber: frameData.lineNumber,
                    // eslint-disable-next-line no-nested-ternary
                    functionIdentifier: this.cleanUpFunctionName(i === 0 ? (frameData.functionName) ? frameData.functionName : thread.functionName : frameData.functionName)
                };
                this.stackFramesCache[stackFrame.frameId] = stackFrame;
                frames.push(stackFrame);
            }
            //if the first frame is missing any data, supplement with thread information
            if (frames[0]) {
                frames[0].filePath ??= thread.filePath;
                frames[0].lineNumber ??= thread.lineNumber;
            }

            return frames;
        });
    }

    public getStackFrameById(frameId: number): StackFrame {
        return this.stackFramesCache[frameId];
    }

    private cleanUpFunctionName(functionName): string {
        return functionName.substring(functionName.lastIndexOf('@') + 1);
    }

    /**
     * Get info about the specified variable.
     * @param expression the expression for the specified variable (i.e. `m`, `someVar.value`, `arr[1][2].three`). If empty string/undefined is specified, all local variables are retrieved instead
     */
    private async getVariablesResponse(expression: string, frameId: number) {
        const logger = this.logger.createLogger('[getVariable]');
        logger.info('begin', { expression });
        if (!this.isAtDebuggerPrompt) {
            throw new Error('Cannot resolve variable: debugger is not paused');
        }

        let frame = this.getStackFrameById(frameId);
        if (!frame) {
            throw new Error('Cannot request variable without a corresponding frame');
        }

        logger.info(`Expression:`, JSON.stringify(expression));
        let variablePath = expression === '' ? [] : util.getVariablePath(expression);

        // Temporary workaround related to casing issues over the protocol
        if (this.capabilities.enableVariablesLowerCaseRetry && variablePath?.length > 0) {
            variablePath[0] = variablePath[0].toLowerCase();
        }

        let response = await this.client.getVariables(variablePath, frame.frameIndex, frame.threadIndex);

        if (this.capabilities.enableVariablesLowerCaseRetry && response.data.errorCode !== ErrorCode.OK) {
            // Temporary workaround related to casing issues over the protocol
            logger.log(`Retrying expression as lower case:`, expression);
            variablePath = expression === '' ? [] : util.getVariablePath(expression?.toLowerCase());
            response = await this.client.getVariables(variablePath, frame.frameIndex, frame.threadIndex);
        }
        return response;
    }

    /**
     * Get the variable for the specified expression.
     */
    public async getVariable(expression: string, frameId: number): Promise<EvaluateContainer> {
        const response = await this.getVariablesResponse(expression, frameId);

        if (Array.isArray(response?.data?.variables)) {
            const container = this.createEvaluateContainer(
                response.data.variables[0],
                //the name of the top container is the expression itself
                expression,
                //this is the top-level container, so there are no parent keys to this entry
                undefined
            );
            await insertCustomVariables(this, expression, container);
            container.namedVariables = container.children.length - container.indexedVariables;
            return container;
        }
    }

    /**
     * Get the list of local variables
     */
    public async getLocalVariables(frameId: number) {
        const response = await this.getVariablesResponse('', frameId);

        if (response?.data?.errorCode === ErrorCode.OK && Array.isArray(response?.data?.variables)) {
            //create a top-level container to hold all the local vars
            const container = this.createEvaluateContainer(
                //dummy data
                {
                    isConst: false,
                    isContainer: true,
                    keyType: VariableType.String,
                    refCount: undefined,
                    type: VariableType.AssociativeArray,
                    value: undefined,
                    children: response.data.variables
                },
                //no name, this is a dummy container
                undefined,
                //there's no parent path
                undefined
            );
            container.indexedVariables = 0;
            container.namedVariables = container.children.length;
            return container;
        }
    }

    /**
     * Create an EvaluateContainer for the given variable. If the variable has children, those are created and attached as well
     * @param variable a Variable object from the debug protocol debugger
     * @param name the name of this variable. For example, `alpha.beta.charlie`, this value would be `charlie`. For local vars, this is the root variable name (i.e. `alpha`)
     * @param parentEvaluateName the string used to derive the parent, _excluding_ this variable's name (i.e. `alpha.beta` or `alpha[0]`)
     */
    private createEvaluateContainer(variable: Variable, name: string | number, parentEvaluateName: string): EvaluateContainer {
        let value;
        let variableType = variable.type;
        if (variable.value === null) {
            value = 'roInvalid';
        } else if (variableType === VariableType.String) {
            value = `\"${variable.value}\"`;
        } else {
            value = variable.value;
        }

        if (variableType === VariableType.SubtypedObject) {
            //subtyped objects can only have string values
            let parts = (variable.value as string).split('; ');
            // Pull the primary type from the value.
            (variableType as string) = parts[0];

            // Format the value to be more readable in the UI.
            // Example: `roSGNode; Group` = `roSGNode (Group)`
            (value as string) = `${parts[0]}(${parts[1]})`;
        } else if (variableType === VariableType.Object || variableType === VariableType.Interface) {
            // We want the type to reflect `roAppInfo` or `roDeviceInfo` for example in the UI
            // so set the type to be the value from the device
            variableType = value;
        } else if (variableType === VariableType.AssociativeArray) {
            // We want the type to reflect `function` in the UI
            value = VariableType.AssociativeArray;
        }

        //build full evaluate name for this var. (i.e. `alpha["beta"]` + ["charlie"]` === `alpha["beta"]["charlie"]`)
        let evaluateName: string;
        if (!parentEvaluateName?.trim()) {
            evaluateName = name?.toString();
        } else if (variable.isVirtual) {
            evaluateName = `${parentEvaluateName}.${name}`;
        } else if (typeof name === 'string') {
            evaluateName = `${parentEvaluateName}["${name}"]`;
        } else if (typeof name === 'number') {
            evaluateName = `${parentEvaluateName}[${name}]`;
        }

        let container: EvaluateContainer = {
            name: name?.toString() ?? '',
            evaluateName: evaluateName ?? '',
            type: variableType ?? '',
            value: value ?? null,
            highLevelType: undefined,
            //non object/array variables don't have a key type
            keyType: variable.keyType as unknown as KeyType,
            namedVariables: 0,
            indexedVariables: 0,
            //non object/array variables still need to have an empty `children` array to help upstream logic. The `keyType` being null is how we know it doesn't actually have children
            children: []
        };

        // In preparation for adding custom variables some variables need to be marked
        // as keyable/container like even thought they are not on device.
        overrideKeyTypesForCustomVariables(this, container);

        if (container.keyType === KeyType.integer) {
            container.indexedVariables = variable.childCount ?? variable.children?.length ?? undefined;
            // We do not know how many named variables there are, if any, so we will always tell the DAP client to ask for them
            container.namedVariables = 1;
        } else if (container.keyType === KeyType.string) {
            // container.namedVariables = variable.childCount ?? variable.children?.length ?? undefined;
            // Force one so DAP client always asks for all named vars
            container.namedVariables = 1;
        }

        //recursively generate children containers
        if ([KeyType.integer, KeyType.string].includes(container.keyType) && Array.isArray(variable.children)) {
            container.children = [];

            container.namedVariables = 0;
            container.indexedVariables = 0;

            for (let i = 0; i < variable.children.length; i++) {
                const childVariable = variable.children[i];
                if (childVariable.name === undefined) {
                    container.indexedVariables++;
                }
                const childContainer = this.createEvaluateContainer(
                    childVariable,
                    container.keyType === KeyType.integer && !childVariable.isVirtual ? i : childVariable.name,
                    container.evaluateName
                );
                container.children.push(childContainer);
            }
        }

        //show virtual variables in the UI
        if (variable.isVirtual) {
            if (!container.presentationHint) {
                container.presentationHint = {};
            }
            container.presentationHint.kind = 'virtual';
        }

        return container;
    }

    /**
     * Cache items by a unique key
     * @param expression
     * @param factory
     */
    private resolve<T>(key: string, factory: () => T | Thenable<T>): Promise<T> {
        if (this.cache[key]) {
            this.logger.log('return cashed response', key, this.cache[key]);
            return this.cache[key];
        }
        this.cache[key] = Promise.resolve<T>(factory());
        return this.cache[key];
    }

    /**
     * Get a list of threads. The active thread will always be first in the list.
     */
    public async getThreads() {
        if (!this.isAtDebuggerPrompt) {
            throw new Error('Cannot get threads: debugger is not paused');
        }
        return this.resolve('threads', async () => {
            let threads: Thread[] = [];
            let threadsResponse: ThreadsResponse;
            // sometimes roku threads are stubborn and haven't stopped yet, causing our ThreadsRequest to fail with "not stopped".
            // A nice simple fix for this is to just send a "pause" request again, which seems to fix the issue.
            // we'll do this a few times just to make sure we've tried our best to get the list of threads.
            for (let i = 0; i < 3; i++) {
                threadsResponse = await this.client.threads();
                if (threadsResponse.data.errorCode === ErrorCode.NOT_STOPPED) {
                    this.logger.log(`Threads request retrying... ${i}:\n`, threadsResponse);
                    threadsResponse = undefined;
                    const pauseResponse = await this.client.pause(true);
                    await util.sleep(100);
                } else {
                    break;
                }
            }
            if (!threadsResponse) {
                return [];
            }

            for (let i = 0; i < (threadsResponse.data?.threads?.length ?? 0); i++) {
                let threadInfo = threadsResponse.data.threads[i];
                let thread = <Thread>{
                    // NOTE: On THREAD_ATTACHED events the threads request is marking the wrong thread as primary.
                    // NOTE: Rely on the thead index from the threads update event.
                    isSelected: this.client.primaryThread === i,
                    // isSelected: threadInfo.isPrimary,
                    isDetached: threadInfo.isDetached,
                    filePath: threadInfo.filePath,
                    functionName: threadInfo.functionName,
                    lineNumber: threadInfo.lineNumber, //threadInfo.lineNumber is 1-based. Thread requires 1-based line numbers
                    lineContents: threadInfo.codeSnippet,
                    threadId: i,
                    osThreadId: threadInfo.osThreadId,
                    name: threadInfo.name,
                    type: threadInfo.type
                };
                threads.push(thread);
            }
            //make sure the selected thread is at the top
            threads.sort((a, b) => {
                return a.isSelected ? -1 : 1;
            });

            return threads;
        });
    }

    private async getThreadByThreadId(threadId: number) {
        let threads = await this.getThreads();
        for (let thread of threads) {
            if (thread.threadId === threadId) {
                return thread;
            }
        }
    }

    public removeAllListeners() {
        if (this.emitter) {
            this.emitter.removeAllListeners();
        }
    }

    /**
     * Indicates whether this class had `.destroy()` called at least once. Mostly used for checking externally to see if
     * the whole debug session has been terminated or is in a bad state.
     */
    public isDestroyed = false;
    /**
     * Disconnect from the telnet session and unset all objects
     */
    public async destroy() {
        this.isDestroyed = true;

        // destroy the debug client if it's defined
        if (this.client) {
            try {
                await this.client.destroy();
            } catch (e) {
                this.logger.error(e);
            }
        }

        try {
            let shutdownTimeMax = this.options?.shutdownTimeout ?? 10_000;
            await this.destroyCompileClient(shutdownTimeMax);
        } catch (e) {
            this.logger.error(e);
        }

        this.cache = undefined;
        this.removeAllListeners();
        this.emitter = undefined;
    }

    /**
     * Promise that is resolved when the compile client socket is closed
     */
    private compileClientClosed = defer<void>();
    private isDestroyingCompileClient = false;

    private async destroyCompileClient(timeout: number) {
        if (this.compileClient && !this.isDestroyingCompileClient) {
            this.isDestroyingCompileClient = true;
            this.compileClient?.end();

            //wait for the compileClient to be closed
            await Promise.race([
                this.compileClientClosed.promise,
                util.sleep(timeout)
            ]);

            this.logger.log('[destroy] compileClient is: ', this.compileClientClosed.isResolved ? 'closed' : 'not closed');

            //destroy the compileClient
            this.compileClient?.removeAllListeners();
            this.compileClient?.destroy();
            this.compileClient = undefined;
            this.isDestroyingCompileClient = false;
        }
    }

    /**
     * Passes the log level down to the RendezvousTracker and ChanperfTracker
     * @param outputLevel the consoleOutput from the launch config
     */
    public setConsoleOutput(outputLevel: string) {
        this.chanperfTracker.setConsoleOutput(outputLevel);
        this.rendezvousTracker.setConsoleOutput(outputLevel);
    }

    /**
     * Sends a call to the RendezvousTracker to clear the current rendezvous history
     */
    public clearRendezvousHistory() {
        this.rendezvousTracker.clearHistory();
    }

    /**
     * Sends a call to the ChanperfTracker to clear the current chanperf history
     */
    public clearChanperfHistory() {
        this.chanperfTracker.clearHistory();
    }

    /**
     * The most recently requested exception breakpoint filters. Stored so we can replay them
     * to the debug protocol client once it connects (the session can send these before the
     * device has launched and the client has finished its handshake).
     */
    private pendingExceptionBreakpointFilters: ExceptionBreakpoint[] | undefined;

    public async setExceptionBreakpoints(filters: ExceptionBreakpoint[]) {
        if (!this.capabilities.supportsExceptionBreakpoints) {
            return undefined;
        }
        //if the client isn't connected yet, queue the filters for replay on connect
        if (!this.connected) {
            this.pendingExceptionBreakpointFilters = filters;
            return undefined;
        }
        return this.client.setExceptionBreakpoints(filters);
    }

    private syncBreakpointsPromise = Promise.resolve();
    public async syncBreakpoints() {
        this.logger.log('syncBreakpoints()');
        //wait for the previous sync to finish
        this.syncBreakpointsPromise = this.syncBreakpointsPromise
            //ignore any errors
            .catch(() => { })
            //run the next sync
            .then(() => this._syncBreakpoints());

        //return the new promise, which will resolve once our latest `syncBreakpoints()` call is finished
        return this.syncBreakpointsPromise;
    }

    public async _syncBreakpoints() {
        //we need to actually be connected to the device before we can push breakpoints. We'll get
        //called again once the debug protocol client has connected.
        if (!this.connected) {
            this.logger.info('Cannot sync breakpoints because the debug protocol client has not connected yet');
            return;
        }
        //we can't send breakpoints unless we're stopped (or in a protocol version that supports sending them while running).
        //So...if we're not stopped, quit now. (we'll get called again when the stop event happens)
        if (!this.capabilities.supportsBreakpointRegistrationWhileRunning && !this.isAtDebuggerPrompt) {
            this.logger.info('Cannot sync breakpoints because the debugger', this.capabilities.supportsBreakpointRegistrationWhileRunning ? 'does not support sending breakpoints while running' : 'is not paused');
            return;
        }

        //compute breakpoint changes since last sync
        const diff = await this.breakpointManager.getDiff(this.projectManager.getAllProjects());
        this.logger.log('Syncing breakpoints', diff);

        if (diff.added.length === 0 && diff.removed.length === 0) {
            this.logger.debug('No breakpoints to sync');
            return;
        }

        //getDiff above can yield to other microtasks. If the protocol client closed while we were
        //awaiting (mid-sync TOCTOU), bail out before dereferencing this.client. The app-exit handler
        //resets the breakpoint baseline so the next reconnect re-pushes any pending changes.
        //See https://github.com/rokucommunity/vscode-brightscript-language/issues/811
        if (!this.client) {
            this.logger.info('Skipping breakpoint sync because the protocol client closed mid-sync');
            return;
        }

        // REMOVE breakpoints (delete these breakpoints from the device)
        if (diff.removed.length > 0) {
            const response = await this.client.removeBreakpoints(
                //TODO handle retrying to remove breakpoints that don't have deviceIds yet but might get one in the future
                diff.removed.map(x => x.deviceId).filter(x => typeof x === 'number')
            );

            if (response.data?.errorCode === ErrorCode.NOT_STOPPED) {
                this.breakpointManager.failedDeletions.push(...diff.removed);
            }
        }

        if (diff.added.length > 0) {
            //the removeBreakpoints await above can also yield; re-check before attempting the add
            if (!this.client) {
                this.logger.info('Skipping breakpoint add because the protocol client closed mid-sync');
                return;
            }
            const breakpointsToSendToDevice = diff.added.map(breakpoint => {
                const hitCount = parseInt(breakpoint.hitCondition);
                return {
                    filePath: breakpoint.pkgPath,
                    lineNumber: breakpoint.line,
                    hitCount: !isNaN(hitCount) ? hitCount : undefined,
                    conditionalExpression: breakpoint.condition,
                    srcHash: breakpoint.srcHash,
                    destHash: breakpoint.destHash,
                    componentLibraryName: breakpoint.componentLibraryName
                };
            });

            //split the list into conditional and non-conditional breakpoints.
            //(TODO we can eliminate this splitting logic once the conditional breakpoints "continue" bug in protocol is fixed)
            const standardBreakpoints: typeof breakpointsToSendToDevice = [];
            const conditionalBreakpoints: typeof breakpointsToSendToDevice = [];
            for (const breakpoint of breakpointsToSendToDevice) {
                if (breakpoint?.conditionalExpression?.trim()) {
                    conditionalBreakpoints.push(breakpoint);
                } else {
                    standardBreakpoints.push(breakpoint);
                }
            }
            for (const breakpoints of [standardBreakpoints, conditionalBreakpoints]) {
                const response = await this.client.addBreakpoints(breakpoints);

                //if the response was successful, and we have the correct number of breakpoints in the response
                if (response.data.errorCode === ErrorCode.OK && response?.data?.breakpoints?.length === breakpoints.length) {
                    for (let i = 0; i < (response?.data?.breakpoints?.length ?? 0); i++) {
                        const deviceBreakpoint = response.data.breakpoints[i];

                        if (typeof deviceBreakpoint?.id === 'number') {
                            //sync this breakpoint's deviceId with the roku-assigned breakpoint ID
                            this.breakpointManager.setBreakpointDeviceId(
                                breakpoints[i].srcHash,
                                breakpoints[i].destHash,
                                deviceBreakpoint.id
                            );
                        }

                        //this breakpoint had an issue. remove it from the client
                        if (deviceBreakpoint.errorCode !== ErrorCode.OK) {
                            this.breakpointManager.deleteBreakpoint(breakpoints[i].srcHash);
                        }
                    }
                    //the entire response was bad. delete these breakpoints from the client
                } else {
                    this.breakpointManager.deleteBreakpoints(
                        breakpoints.map(x => x.srcHash)
                    );
                }
            }
        }
    }

    public isTelnetAdapter(): this is TelnetAdapter {
        return false;
    }

    public isDebugProtocolAdapter(): this is DebugProtocolAdapter {
        return true;
    }
}

export interface StackFrame {
    frameId: number;
    frameIndex: number;
    threadIndex: number;
    filePath: string;
    lineNumber: number;
    functionIdentifier: string;
}

export enum EventName {
    suspend = 'suspend'
}

export interface EvaluateContainer {
    name: string;
    evaluateName: string;
    type: string;
    value?: any;
    keyType?: KeyType;
    namedVariables?: number;
    indexedVariables?: number;
    highLevelType?: HighLevelType;
    children: EvaluateContainer[];
    isCustom?: boolean;
    evaluateNow?: boolean;
    presentationHint?: DebugProtocol.VariablePresentationHint;
}

export enum KeyType {
    string = 'String',
    integer = 'Integer',
    legacy = 'Legacy'
}

export interface Thread {
    isSelected: boolean;
    isDetached?: boolean;
    /**
     * The 1-based line number for the thread
     */
    lineNumber: number;
    filePath: string;
    functionName: string;
    lineContents: string;
    threadId: number;
    osThreadId?: string;
    name?: string;
    type?: string;
}

interface BrightScriptRuntimeError {
    message: string;
    errorCode: string;
}

rokucommunity / roku-debug / 28254649616

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous