#1953

Build # #1953

Build Type

push

Committed by

Commit Message

<a href="https://github.com/rokucommunity/roku-debug/commit/<a class=hub.com/rokucommunity/roku-debug/commit/69e3b9089f805bd08bd51ad170219ab6d762a9e6">69e3b9089<a href="https://github.com/rokucommunity/roku-debug/commit/69e3b9089f805bd08bd51ad170219ab6d762a9e6">">Merge </a><a class="double-link" href="https://github.com/rokucommunity/roku-debug/commit/<a class="double-link" href="https://github.com/rokucommunity/roku-debug/commit/ecf5f8de6e57742443de375f063a3b96311c2ee7">ecf5f8de6</a>">ecf5f8de6</a><a href="https://github.com/rokucommunity/roku-debug/commit/69e3b9089f805bd08bd51ad170219ab6d762a9e6"> into 9f70a081d">9f70a081d</a>

Run Details

997 of 1898 branches covered (52.53%)

Branch coverage included in aggregate %.

1 of 1 new or added line in 1 file covered. (100.0%)

2074 of 3567 relevant lines covered (58.14%)

15.97 hits per line

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

49.07

/src/SceneGraphDebugCommandController.ts

import { logger } from './logging';

// eslint-disable-next-line
const Telnet = require('telnet-client');

export class SceneGraphDebugCommandController {
    constructor(public host: string) {
    }

    private connection: typeof Telnet;

    private shellPrompt = /^>$/img;
    private echoLines = 0;
    public timeout = 5000;
    public execTimeout = 2000;
    private port = 8080;
    private maxBufferLength = 5242880;

    private logger = logger.createLogger(`[${SceneGraphDebugCommandController.name}]`);

    public async connect(options: { execTimeout?: number; timeout?: number } = {}) {
        this.removeConnection();

        try {
            // Make a new telnet connections object
            let connection = new Telnet();

            connection.on('close', () => {
                this.removeConnection();
            });
            const config = {
                host: this.host,
                port: this.port,
                shellPrompt: this.shellPrompt,
                echoLines: this.echoLines,
                timeout: this.timeout,
                execTimeout: this.execTimeout,
                maxBufferLength: this.maxBufferLength,
                ...options
            };
            this.logger.debug('Establishing telnet connection', config);
            await connection.connect(config);
            this.connection = connection;
        } catch (e) {
            throw new Error((e as Error).message);
        }
    }

    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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        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: <channelId>'
            // 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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        return this.exec('free');
    }

    /**
     * Generate a new developer key.
     */
    public async genkey(): Promise<SceneGraphCommandResponse> {
        return this.exec('genkey');
    }


    /**
     * Displays the current set of images loaded into texture memory.
     */
    public async loadedTextures(): Promise<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        let command = 'logrendezvous';

        if (option !== 'status') {
            command = `${command} ${option}`;
        }

        return this.exec(command);
    }

    /**
     * Show list of all installed plugins.
     */
    public async plugins(): Promise<SceneGraphCommandResponse> {
        return this.exec('plugins');
    }

    /**
     * Simulate a keypress.
     * @param {string[]} keys A list of keys to press in sequence
     */
    public async press(keys: string[]): Promise<SceneGraphCommandResponse> {
        // 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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        return this.exec(`sgperf ${action}`);
    }

    /**
     * Show the current developer key
     */
    public async showkey(): Promise<SceneGraphCommandResponse> {
        return this.exec('showkey');
    }

    /**
     * Send a literal text sequence.
     * @param text string to be sent to the device.
     */
    public async type(text: string): Promise<SceneGraphCommandResponse> {
        // 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<SceneGraphCommandResponse> {
        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<SceneGraphCommandResponse> {
        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<T = undefined> {
    command: string;
    error?: SceneGraphCommandError<T>;
    result: {
        rawResponse: string;
        data?: any;
    };
}

interface SceneGraphCommandError<T = undefined> {
    message: string;
    type: 'socket' | 'device';
    data?: T;
}

1	import { logger } from './logging';	1✔
2
3	// eslint-disable-next-line
4	const Telnet = require('telnet-client');	1✔
5
6	export class SceneGraphDebugCommandController {	1✔
7	constructor(public host: string) {	34✔
8	}
9
10	private connection: typeof Telnet;
11
12	private shellPrompt = /^>$/img;	34✔
13	private echoLines = 0;	34✔
14	public timeout = 5000;	34✔
15	public execTimeout = 2000;	34✔
16	private port = 8080;	34✔
17	private maxBufferLength = 5242880;	34✔
18
19	private logger = logger.createLogger(`[${SceneGraphDebugCommandController.name}]`);	34✔
20
21	public async connect(options: { execTimeout?: number; timeout?: number } = {}) {	×
22	this.removeConnection();	×
23
24	try {	×
25	// Make a new telnet connections object
26	let connection = new Telnet();	×
27
28	connection.on('close', () => {	×
29	this.removeConnection();	×
30	});
31	const config = {	×
32	host: this.host,
33	port: this.port,
34	shellPrompt: this.shellPrompt,
35	echoLines: this.echoLines,
36	timeout: this.timeout,
37	execTimeout: this.execTimeout,
38	maxBufferLength: this.maxBufferLength,
39	...options
40	};
41	this.logger.debug('Establishing telnet connection', config);	×
42	await connection.connect(config);	×
43	this.connection = connection;	×
44	} catch (e) {
45	throw new Error((e as Error).message);	×
46	}
47	}
48
49	private removeConnection() {
50	this.connection = null;	×
51	}
52
53	/**
54	* executes the different bsprof commands used for brightscript profiling.
55	* @param {('pause'\|'resume'\|'status')} option Pause, resume, or get BS profiling status.
56	*/
57	public async bsprof(option: 'pause' \| 'resume' \| 'status'): Promise<SceneGraphCommandResponse> {
58	return this.exec(`bsprof-${option}`);	3✔
59	}
60
61	/**
62	* 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.
63	*
64	* If an interval is provided the device repeats the command the specified number of seconds and outputs the results to port 8085.
65	* (Available since Roku OS 10.0)
66	* @param {{ interval: number }} [options] logging interval in seconds. 0 will stop interval logging.
67	*/
68	public async chanperf(options?: { interval: number }): Promise<SceneGraphCommandResponse> {
69	let command = 'chanperf';	4✔
70
71	if (options) {	4✔
72	// TODO: revisit this as channelId support is documented but the command does not seem to work. Device returns 'ERR: unknown arg: <channelId>'
73	// command = options?.channelId ? `${command} ${options.channelId}` : command;
74	command = options?.interval > -1 ? `${command} -r ${options.interval}` : command;	3!
75	}
76
77	return this.exec(command);	4✔
78	}
79
80	/**
81	* Clear all caches that can affect channel launch time.
82	*/
83	public async clearLaunchCaches(): Promise<SceneGraphCommandResponse> {
84	return this.exec('clear_launch_caches');	1✔
85	}
86
87	/**
88	* 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.
89	* @param {('off'\|'on'\|'toggle')} option
90	*/
91	public async fpsDisplay(option: 'off' \| 'on' \| 'toggle'): Promise<SceneGraphCommandResponse> {
92	let command = 'fps_display';	3✔
93
94	if (option !== 'toggle') {	3✔
95	command = `${command} ${option === 'on' ? 1 : 0}`;	2✔
96	}
97
98	let response = await this.exec(command);	3✔
99	if (!response.error) {	3!
100	response.result.data = `FPS Display: ${option}`;	3✔
101	}
102	return response;	3✔
103	}
104
105	/**
106	* Provides a snapshot of the amount of in-use and free memory on the device.
107	*/
108	public async free(): Promise<SceneGraphCommandResponse> {
109	return this.exec('free');	1✔
110	}
111
112	/**
113	* Generate a new developer key.
114	*/
115	public async genkey(): Promise<SceneGraphCommandResponse> {
116	return this.exec('genkey');	1✔
117	}
118
119
120	/**
121	* Displays the current set of images loaded into texture memory.
122	*/
123	public async loadedTextures(): Promise<SceneGraphCommandResponse> {
124	return this.exec('loaded_textures');	1✔
125	}
126
127	/**
128	* Enable, disable, or checks the status of console logging of thread rendezvous.
129	* @param {('status'\|'off'\|'on')} option
130	*/
131	public async logrendezvous(option: 'status' \| 'off' \| 'on'): Promise<SceneGraphCommandResponse> {
132	let command = 'logrendezvous';	3✔
133
134	if (option !== 'status') {	3✔
135	command = `${command} ${option}`;	2✔
136	}
137
138	return this.exec(command);	3✔
139	}
140
141	/**
142	* Show list of all installed plugins.
143	*/
144	public async plugins(): Promise<SceneGraphCommandResponse> {
145	return this.exec('plugins');	1✔
146	}
147
148	/**
149	* Simulate a keypress.
150	* @param {string[]} keys A list of keys to press in sequence
151	*/
152	public async press(keys: string[]): Promise<SceneGraphCommandResponse> {
153	// Add 1 second per character to the max execution timeout because roku is really slow......
154	return this.exec(`press ${keys.join(', ')}`, { execTimeout: this.execTimeout + (keys.length * 1000) });	2✔
155	}
156
157
158	/**
159	* Prints a list of assets loaded into texture memory and the amount of free, used, and maximum available memory on your device, respectively.
160	* Starting with Roku OS 9.3, the name of each bitmap is included.
161	*/
162	public async r2d2Bitmaps(): Promise<SceneGraphCommandResponse> {
163	return this.exec('r2d2_bitmaps');	1✔
164	}
165
166
167	/**
168	* 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
169	*
170	* The list of available channel ids can be seen with the 'plugins' command. The local device must be linked to a Roku account.
171	*
172	* 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).
173	* (Available since Roku OS 10.0)
174	*
175	* @param {string} channelId
176	*/
177	public async removePlugin(channelId: string): Promise<SceneGraphCommandResponse> {
178	return this.exec(`remove_plugin ${channelId}`);	2✔
179	}
180
181
182	/**
183	* Prints every existing node created by the currently running channel.
184	* 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).
185	* The 'bcsref' count includes references from "m." variable and local variables. Child references and field references do not increase 'bscref' counts.
186	*
187	* 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.
188	* Additionally, any field of type 'node', 'nodearray', or 'assocarray' will add one 'osref' to each node referenced from within that field.
189	* 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.
190	*
191	* 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.
192	* The 'bscref' count provides a more relevant and accurate indication of the resources that the channel itself controls.
193	*
194	* 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.
195	*
196	* @param {string} id This can be 'all', 'roots', or the id of node(s) in your channel.
197	*/
198	public async sgnodes(id: string): Promise<SceneGraphCommandResponse> {
199	return this.exec(`sgnodes ${id}`);	3✔
200	}
201
202
203	/**
204	* 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.
205	* @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.
206	*/
207	public async sgperf(action: 'start' \| 'clear' \| 'report' \| 'stop'): Promise<SceneGraphCommandResponse> {
208	return this.exec(`sgperf ${action}`);	4✔
209	}
210
211	/**
212	* Show the current developer key
213	*/
214	public async showkey(): Promise<SceneGraphCommandResponse> {
215	return this.exec('showkey');	1✔
216	}
217
218	/**
219	* Send a literal text sequence.
220	* @param text string to be sent to the device.
221	*/
222	public async type(text: string): Promise<SceneGraphCommandResponse> {
223	// Add 1 second per character to the max execution timeout because roku is really slow......
224	return this.exec(`type ${text}`, { execTimeout: this.execTimeout + (text.length * 1000) });	1✔
225	}
226
227
228	/**
229	* Changes the number of brightscript warnings displayed on application install.
230	* @param warningLimit maximum number of warnings to show
231	*/
232	public async brightscriptWarnings(warningLimit: number): Promise<SceneGraphCommandResponse> {
233	return this.exec(`brightscript_warnings ${warningLimit ?? 100}`);	×
234	}
235
236
237	/**
238	* Send any custom command to the SceneGraph debug server.
239	*
240	* If this command is called and there is no active connection with the device we will attempt to connect.
241	* In this case once the command has been executed we will then close the connection.
242	* @param {string} command command to be run.
243	*/
244	public async exec(command: string, options: { execTimeout?: number; timeout?: number } = {}): Promise<SceneGraphCommandResponse> {	×
245	let response = this.getBlankResponseObject(command);	×
246	this.logger.log(`Running SceneGraphDebugger command`, { command });	×
247
248	// Set up a short lived connection if a long lived one has not beed started
249	let closeConnectionAfterCommand = !this.connection;	×
250	if (closeConnectionAfterCommand) {	×
251	this.logger.trace('Opening new connection');	×
252	try {	×
253	await this.connect(options);	×
254	} catch (error) {
255	response.error = error;	×
256	}
257	}
258
259	// Send the commend if we have a connection
260	if (this.connection) {	×
261	try {	×
262	response.result.rawResponse = await this.connection.exec(command, options);	×
263	this.logger.debug('Command complete', { command });	×
264	} catch (error) {
265	response.error = error;	×
266	}
267	}
268
269	// Close the connection if we opened a short lived one
270	if (closeConnectionAfterCommand) {	×
271	this.logger.trace('Closing connection');	×
272	await this.end();	×
273	}
274
275	// Tada! Results.
276	return response;	×
277	}
278
279
280	/**
281	* Closes the socket connection to the device
282	*/
283	public async end() {
284	if (this.connection) {	×
285	this.connection.removeListener('close', this.removeConnection);	×
286	try {	×
287	try {	×
288	// Asking the host to close is much faster then running our own connections destroy
289	await this.connection.exec('quit', { shellPrompt: 'Quit command received, exiting.' });	×
290	} catch (error) {
291	this.logger.error(`There was a problem quitting the SceneGraphDebugCommand connection`, error);	×
292	}
293	this.removeConnection();	×
294	} catch (error) {
295	this.removeConnection();	×
296	console.log(error, this.connection);	×
297	}
298	}
299	}
300
301
302	/**
303	* Returns a simple starting object used for responses
304	* @private
305	*/
306	private getBlankResponseObject(command: string): SceneGraphCommandResponse {
307	return {	×
308	command: command,
309	result: {
310	rawResponse: ''
311	}
312	};
313	}
314	}
315
316	export interface SceneGraphCommandResponse<T = undefined> {
317	command: string;
318	error?: SceneGraphCommandError<T>;
319	result: {
320	rawResponse: string;
321	data?: any;
322	};
323	}
324
325	interface SceneGraphCommandError<T = undefined> {
326	message: string;
327	type: 'socket' \| 'device';
328	data?: T;
329	}

rokucommunity / roku-debug / #1953

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