import { createRokuDeploySocket } from 'roku-deploy'; import type { DeviceConfig, RokuDeploySocket, SocketOptions } from 'roku-deploy'; import { logger } from './logging'; // eslint-disable-next-line const Telnet = require('telnet-client'); export class SceneGraphDebugCommandController { constructor(device: DeviceConfig, port?: number) { this.device = device; this.port = port ?? 8080; } /** * The roku-deploy device config for the target device */ private device: DeviceConfig; private connection: typeof Telnet; private shellPrompt = /^>$/img; private echoLines = 0; public timeout = 5000; public execTimeout = 2000; private port; private maxBufferLength = 5242880; private logger = logger.createLogger(`[${SceneGraphDebugCommandController.name}]`); /** * Create the transport used to reach the SceneGraph debug server. Extracted to a protected * method so tests can substitute a fake socket. */ protected createRokuDeploySocket(options: SocketOptions): RokuDeploySocket { return createRokuDeploySocket(options); } public async connect(options: { execTimeout?: number; timeout?: number } = {}) { this.removeConnection(); const timeoutMs = options.timeout ?? this.timeout; let socket: RokuDeploySocket | undefined; try { socket = this.createRokuDeploySocket({ device: this.device, port: this.port }); //keep an error listener attached for the socket's whole life: waitForConnectPrompt and //telnet-client each remove or narrow theirs at various points, and a socket 'error' //emitted while no listener is attached would crash the whole process socket.on('error', (error: Error) => { this.logger.debug('SceneGraph debug server socket error', error); }); await this.waitForSocketConnect(socket, timeoutMs); //an injected sock skips telnet-client's own prompt wait entirely (see the comment on //waitForConnectPrompt below), so the greeting has to be consumed here first or it would //otherwise arrive mid-exec and prematurely terminate the first command's response await this.waitForConnectPrompt(socket, timeoutMs); // Make a new telnet connections object let connection = new Telnet(); connection.on('close', () => { this.removeConnection(); }); const config = { port: this.port, shellPrompt: this.shellPrompt, echoLines: this.echoLines, timeout: this.timeout, execTimeout: this.execTimeout, maxBufferLength: this.maxBufferLength, ...options, sock: socket }; this.logger.debug('Establishing telnet connection', config); await connection.connect(config); this.connection = connection; } catch (e) { //the socket was created but never became the live connection, so nothing else will ever //destroy it. Leaving it dangling would leak an open socket or websocket. socket?.destroy(); throw new Error((e as Error).message); } } /** * Waits for the transport-level connection to establish (the tcp handshake for a local device, * or the websocket handshake for an RCE device), racing its 'connect' event against 'error' and * a manual timeout. An injected sock bypasses telnet-client's own connect timeout entirely * (telnet-client resolves immediately for an injected sock, before its timeout is even armed), * so this is the only thing enforcing one here. */ private waitForSocketConnect(socket: RokuDeploySocket, timeoutMs: number): Promise { return new Promise((resolve, reject) => { const cleanup = () => { clearTimeout(timeoutHandle); socket.removeListener('connect', onConnect); socket.removeListener('error', onError); }; const onConnect = () => { cleanup(); resolve(); }; const onError = (error: Error) => { cleanup(); reject(error); }; const timeoutHandle = setTimeout(() => { cleanup(); reject(new Error(`Timed out connecting to the SceneGraph debug server after ${timeoutMs}ms`)); }, timeoutMs); socket.once('connect', onConnect); socket.once('error', onError); socket.connect(); }); } /** * Waits for the connection greeting (a bare `>` shell prompt) to arrive and consumes it before * the socket is handed to telnet-client. This mirrors the prompt wait telnet-client performs * when it owns the socket, which it skips entirely for an injected sock (it treats one as * already `'ready'`); without it the greeting would instead arrive mid-exec, where its prompt * would prematurely terminate the first command's response. Rejects if the prompt does not * arrive within `timeoutMs`. */ private waitForConnectPrompt(socket: RokuDeploySocket, timeoutMs: number): Promise { return new Promise((resolve, reject) => { let accumulatedText = ''; //a fresh non-global copy avoids a stateful lastIndex across calls, since //this.shellPrompt carries the 'g' flag const nonGlobalShellPrompt = new RegExp(this.shellPrompt.source, this.shellPrompt.flags.replace('g', '')); const finish = (error?: Error) => { socket.removeListener('data', onData); clearTimeout(timeoutHandle); if (error) { reject(error); } else { resolve(); } }; const onData = (chunk: Buffer) => { accumulatedText += chunk.toString('utf8'); if (nonGlobalShellPrompt.test(accumulatedText)) { finish(); } }; const timeoutHandle = setTimeout(() => { finish(new Error(`Timed out after ${timeoutMs}ms waiting for the SceneGraph debug server's shell prompt`)); }, timeoutMs); socket.on('data', onData); }); } private removeConnection() { this.connection = null; } /** * executes the different bsprof commands used for brightscript profiling. * @param {('pause'|'resume'|'status')} option Pause, resume, or get BS profiling status. */ public async bsprof(option: 'pause' | 'resume' | 'status'): Promise { return this.exec(`bsprof-${option}`); } /** * Prints the current memory and CPU utilization of a channel (RAM usage is reported in KibiBytes [KiB]). The channel manifest must include the run_as_process=1 attribute to use this command. * * If an interval is provided the device repeats the command the specified number of seconds and outputs the results to port 8085. * (Available since Roku OS 10.0) * @param {{ interval: number }} [options] logging interval in seconds. 0 will stop interval logging. */ public async chanperf(options?: { interval: number }): Promise { let command = 'chanperf'; if (options) { // TODO: revisit this as channelId support is documented but the command does not seem to work. Device returns 'ERR: unknown arg: ' // command = options?.channelId ? `${command} ${options.channelId}` : command; command = options?.interval > -1 ? `${command} -r ${options.interval}` : command; } return this.exec(command); } /** * Clear all caches that can affect channel launch time. */ public async clearLaunchCaches(): Promise { return this.exec('clear_launch_caches'); } /** * Displays frames-per-second and free memory on-screen. Leverage this tool to optimize your channel UI. It presents a 1-second moving average of the current frame rate. * @param {('off'|'on'|'toggle')} option */ public async fpsDisplay(option: 'off' | 'on' | 'toggle'): Promise { let command = 'fps_display'; if (option !== 'toggle') { command = `${command} ${option === 'on' ? 1 : 0}`; } let response = await this.exec(command); if (!response.error) { response.result.data = `FPS Display: ${option}`; } return response; } /** * Provides a snapshot of the amount of in-use and free memory on the device. */ public async free(): Promise { return this.exec('free'); } /** * Generate a new developer key. */ public async genkey(): Promise { return this.exec('genkey'); } /** * Displays the current set of images loaded into texture memory. */ public async loadedTextures(): Promise { return this.exec('loaded_textures'); } /** * Enable, disable, or checks the status of console logging of thread rendezvous. * @param {('status'|'off'|'on')} option */ public async logrendezvous(option: 'status' | 'off' | 'on'): Promise { let command = 'logrendezvous'; if (option !== 'status') { command = `${command} ${option}`; } return this.exec(command); } /** * Show list of all installed plugins. */ public async plugins(): Promise { return this.exec('plugins'); } /** * Simulate a keypress. * @param {string[]} keys A list of keys to press in sequence */ public async press(keys: string[]): Promise { // Add 1 second per character to the max execution timeout because roku is really slow...... return this.exec(`press ${keys.join(', ')}`, { execTimeout: this.execTimeout + (keys.length * 1000) }); } /** * Prints a list of assets loaded into texture memory and the amount of free, used, and maximum available memory on your device, respectively. * Starting with Roku OS 9.3, the name of each bitmap is included. */ public async r2d2Bitmaps(): Promise { return this.exec('r2d2_bitmaps'); } /** * Removes the indicated channel from the local device, as well as from all devices linked to the same Roku account. For example, if a channel has a channel id of "987654_cf9a", then the following command would remove it: remove_plugin 987654_cf9a * * The list of available channel ids can be seen with the 'plugins' command. The local device must be linked to a Roku account. * * To use this command, the local device must be linked to a Roku account. Channels are not removed on another device until it synchronizes with the Roku Channel Store (for example, via an automatic check for updates). * (Available since Roku OS 10.0) * * @param {string} channelId */ public async removePlugin(channelId: string): Promise { return this.exec(`remove_plugin ${channelId}`); } /** * Prints every existing node created by the currently running channel. * As of Roku OS 10.0, this prints the number of 'osref' references to the node (held in the Roku platform) and 'bscref' references (held in the channel application). * The 'bcsref' count includes references from "m." variable and local variables. Child references and field references do not increase 'bscref' counts. * * The 'osref' count also includes child references and references from Roku SceneGraph interface fields. For example, for any node with a parent, the parent will count as one 'osref' on the child. * Additionally, any field of type 'node', 'nodearray', or 'assocarray' will add one 'osref' to each node referenced from within that field. * These could be in variables local to a function, arrays, or associative arrays, including a component global m or an associative array field of a node. * * The reported 'osref' count may vary from release to release of Roku OS; the information here is provided only to give a sense of the kinds of items that the count includes. * The 'bscref' count provides a more relevant and accurate indication of the resources that the channel itself controls. * * The sgnodes all, sgnodes roots, and sgnodes node_ID commands are similar to the getAll() , getRoots() , getRootsMeta(), and getAllMeta() ifSGNodeChildren methods, which can be called on any SceneGraph node. * * @param {string} id This can be 'all', 'roots', or the id of node(s) in your channel. */ public async sgnodes(id: string): Promise { return this.exec(`sgnodes ${id}`); } /** * Provides basic node operation performance metrics. This command tracks all node operations by a thread, whether it's being created or an operation on an existing node, and whether it involves a rendezvous. * @param {('start'|'clear'|'report'|'stop')} action start - enables counting, clear - resets counters to zero, report - prints current counts with rendezvous as a percentage, stop - disables counting. */ public async sgperf(action: 'start' | 'clear' | 'report' | 'stop'): Promise { return this.exec(`sgperf ${action}`); } /** * Show the current developer key */ public async showkey(): Promise { return this.exec('showkey'); } /** * Send a literal text sequence. * @param text string to be sent to the device. */ public async type(text: string): Promise { // Add 1 second per character to the max execution timeout because roku is really slow...... return this.exec(`type ${text}`, { execTimeout: this.execTimeout + (text.length * 1000) }); } /** * Changes the number of brightscript warnings displayed on application install. * @param warningLimit maximum number of warnings to show */ public async brightscriptWarnings(warningLimit: number): Promise { return this.exec(`brightscript_warnings ${warningLimit ?? 100}`); } /** * Send any custom command to the SceneGraph debug server. * * If this command is called and there is no active connection with the device we will attempt to connect. * In this case once the command has been executed we will then close the connection. * @param {string} command command to be run. */ public async exec(command: string, options: { execTimeout?: number; timeout?: number } = {}): Promise { let response = this.getBlankResponseObject(command); this.logger.log(`Running SceneGraphDebugger command`, { command }); // Set up a short lived connection if a long lived one has not beed started let closeConnectionAfterCommand = !this.connection; if (closeConnectionAfterCommand) { this.logger.trace('Opening new connection'); try { await this.connect(options); } catch (error) { response.error = error; } } // Send the commend if we have a connection if (this.connection) { try { response.result.rawResponse = await this.connection.exec(command, options); this.logger.debug('Command complete', { command }); } catch (error) { response.error = error; } } // Close the connection if we opened a short lived one if (closeConnectionAfterCommand) { this.logger.trace('Closing connection'); await this.end(); } // Tada! Results. return response; } /** * Closes the socket connection to the device */ public async end() { if (this.connection) { this.connection.removeListener('close', this.removeConnection); try { try { // Asking the host to close is much faster then running our own connections destroy await this.connection.exec('quit', { shellPrompt: 'Quit command received, exiting.' }); } catch (error) { this.logger.error(`There was a problem quitting the SceneGraphDebugCommand connection`, error); } this.removeConnection(); } catch (error) { this.removeConnection(); console.log(error, this.connection); } } } /** * Returns a simple starting object used for responses * @private */ private getBlankResponseObject(command: string): SceneGraphCommandResponse { return { command: command, result: { rawResponse: '' } }; } } export interface SceneGraphCommandResponse { command: string; error?: SceneGraphCommandError; result: { rawResponse: string; data?: any; }; } interface SceneGraphCommandError { message: string; type: 'socket' | 'device'; data?: T; }