import * as fs from 'fs'; import * as fsExtra from 'fs-extra'; import * as path from 'path'; import * as net from 'net'; import * as portfinder from 'portfinder'; import type { BrightScriptDebugSession } from './debugSession/BrightScriptDebugSession'; import { LogOutputEvent } from './debugSession/Events'; import type { AssignmentStatement, Position, Range } from 'brighterscript'; import { isDottedSetStatement, isIndexedSetStatement, Expression, DiagnosticSeverity, isAssignmentStatement, isDottedGetExpression, isIndexedGetExpression, isLiteralExpression, isVariableExpression, Parser } from 'brighterscript'; import { serializeError } from './formatUtils'; import { fileUtils } from './FileUtils'; import * as dns from 'dns'; import type { AdapterOptions, DisposableLike } from './interfaces'; import * as needle from 'needle'; import { OutputEvent } from '@vscode/debugadapter'; import { isPromise } from 'util/types'; import type { Logger } from '@rokucommunity/logger'; import type { DeviceConfig, RokuDeploySocket } from 'roku-deploy'; import { isRceDeviceConfigById, isRceDeviceConfigByUrl, isRceDeviceConfig } from 'roku-deploy'; class Util { /** * Resolve a project's staging folder the same way roku-deploy's `stage()` does: the default * staging folder name inside `outDir`. roku-deploy does not expose this resolution, so it is * rolled here and must stay in step with roku-deploy's own defaults. */ public getStagingDir(options: { outDir?: string; cwd?: string }): string { return path.resolve(options.cwd ?? process.cwd(), options.outDir ?? './out', '.roku-deploy-staging'); } /** * Resolve a project's output zip path the same way roku-deploy's `zip()` does: `outFile` * inside `outDir`, with a `.zip` extension enforced. roku-deploy does not expose this * resolution, so it is rolled here and must stay in step with roku-deploy's own defaults. */ public getOutputZipPath(options: { outDir?: string; outFile?: string; cwd?: string }): string { let out = path.resolve(options.cwd ?? process.cwd(), options.outDir ?? './out', options.outFile ?? 'roku-deploy.zip'); if (!out.toLowerCase().endsWith('.zip')) { out += '.zip'; } return out; } /** * If the path does not have a trailing slash, one is appended to it * @param dirPath */ public ensureTrailingSlash(dirPath: string) { return dirPath.substr(dirPath.length - 1) !== '/' ? dirPath + '/' : dirPath; } /** * Determine if a file exists * @param filePath */ public fileExists(filePath: string) { return new Promise((resolve) => { fsExtra.exists(filePath, resolve); }); } /** * Determine if a file exists, comparing its name case insensitively against the entries of its * parent directory. The parent directory path itself must exist as given (on a case-sensitive * filesystem that means with matching case); returns false when it does not. * @param filePath */ public async fileExistsCaseInsensitive(filePath: string): Promise { filePath = fileUtils.standardizePath(filePath); const lowerFilePath = filePath.toLowerCase(); const parentDirectoryPath = path.dirname(filePath); //the file can't exist if its parent directory doesn't exist if (await fsExtra.pathExists(parentDirectoryPath) === false) { return false; } const filesInDirectory = await fsExtra.readdir(parentDirectoryPath); for (const fileName of filesInDirectory) { const fileInDirectoryPath = fileUtils.standardizePath(`${parentDirectoryPath}/${fileName}`); if (fileInDirectoryPath.toLowerCase() === lowerFilePath) { return true; } } return false; } /** * Determines if the given path is a file * @param filePathAbsolute */ public async isFile(filePathAbsolute: string) { try { //get the full path to the file. This should be the same path for files, and the actual path for any symlinks let realPathAbsolute = fs.realpathSync(filePathAbsolute); let stat = await fsExtra.lstat(realPathAbsolute); return stat.isFile(); } catch (e) { // lstatSync throws an error if path doesn't exist return false; } } /** * Removes any leading scheme in the file path * @param filePath */ public removeFileScheme(filePath: string): string { let scheme = this.getFileScheme(filePath); if (scheme) { return filePath.substring(scheme.length); } else { return filePath; } } /** * Gets any leading scheme in the file path * @param filePath */ public getFileScheme(filePath: string): string | null { return /^([\w_-]+:)/.exec(filePath)?.[1]?.toLowerCase(); } /** * Remove a single trailing newline from a string (\n or \r\n) */ public removeTrailingNewline(value: string) { return value.replace(/(.*?)\r?\n$/, '$1'); } /** * Reads the the manifest file and converts to a javascript object skipping empty lines and comments * @param path location of the manifest file */ public async convertManifestToObject(path: string): Promise | undefined> { if (await this.fileExists(path) === false) { return undefined; } else { let fileContents = (await fsExtra.readFile(path)).toString(); let manifestLines = fileContents.split('\n'); let manifestValues = {}; for (const line of manifestLines) { let match = /(\w+)=(.+)/.exec(line); if (match) { manifestValues[match[1]] = match[2]; //add match in all lower case too (for consistency) manifestValues[match[1]?.toLowerCase()] = match[2]; } } return manifestValues; } } /** * Split a comma-delimited string into trimmed, non-empty entries. Returns an empty array when the * value is missing or blank. * @param value the raw string to split (may be undefined) */ public splitAndTrim(value: string | undefined): string[] { return (value ?? '') .split(',') .map(entry => entry.trim()) .filter(entry => entry.length > 0); } /** * Replace the first case-insensitive occurrence of `search` in `subject` with `replace`. * Returns `subject` unchanged when `search` is not found. * @param subject the string that will have its contents replaced * @param search the search text to find in `subject` * @param replace the text to replace `search` with in `subject` */ public stringReplaceInsensitive(subject: string, search: string, replace: string): string { const matchIndex = subject.toLowerCase().indexOf(search.toLowerCase()); if (matchIndex > -1) { return subject.substring(0, matchIndex) + replace + subject.substring(matchIndex + search.length); } else { return subject; } } /** * Checks to see if the port is already in use * @param port target port to check */ public async isPortInUse(port: number): Promise { return new Promise((resolve, reject) => { const tester = net.createServer() .once('error', (err: any) => { if (err.code === 'EADDRINUSE') { resolve(true); } else { reject(err); } }) .once('listening', () => tester.once('close', () => { resolve(false); }).close()) .listen(port); }); } /** * A reference to the current debug session. Used for logging, and set in the debug session constructor */ public _debugSession: BrightScriptDebugSession; /** * Write to the standard brightscript output log so users can see it. (This also writes to the debug server output channel, and the console) * @param message */ public log(message: string) { if (this._debugSession) { this._debugSession.sendEvent(new LogOutputEvent(`DebugServer: ${message}`)); this._debugSession.sendEvent(new OutputEvent(`DebugServer: ${message}\n`, 'stdout')); } } /** * The vscode hover will occasionally forget to include the closing quotemark for quoted strings, * so this attempts to auto-insert a closing quotemark if an opening one was found but is missing the closing one * @param text */ public ensureClosingQuote(text: string) { if (text.startsWith('"') && text.trim().endsWith('"') === false) { text = text.trim() + '"'; } return text; } /** * Test if `position` is in `range`. If the position is at the edges, will return true. * Adapted from core vscode * @param range * @param position */ public rangeContains(range: Range, position: Position) { if (position.line < range.start.line || position.line > range.end.line) { return false; } if (position.line === range.start.line && position.character < range.start.character) { return false; } if (position.line === range.end.line && position.character > range.end.character) { return false; } return true; } /** * Ensures that all roku-emitted beacons are entirely on their own lines */ public ensureDebugPromptOnOwnLine(text: string) { const regexp = /^((.*?)Brightscript\s+Debugger>\s*)(.*?)$/gm; let match: RegExpExecArray; const splitIndexes = [] as number[]; while ((match = regexp.exec(text))) { const leadingAndBeaconText = match[1]; const leadingText = match[2]; const trailingText = match[3]; //if there is text before the beacon, split the line if (leadingText.length > 0) { splitIndexes.push(match.index + leadingText.length); } //if there is text after the beacon, split the line if (trailingText.length > 0) { splitIndexes.push(match.index + leadingAndBeaconText.length); } } let result = text; //inject newlines between each split index for (let i = splitIndexes.length - 1; i >= 0; i--) { const index = splitIndexes[i]; result = result.substring(0, index) + '\n' + result.substring(index); } return result; } /** * Does the string end with the "Brightscript Debugger>" prompt? * @param responseText */ public endsWithDebuggerPrompt(text: string) { let match = /Brightscript\s+Debugger>\s*$/im.exec(text.trim()); return !!match; } /** * Does the string end with the "thread attached......" text, ignoring trailing whitespace. * explanation: https://regex101.com/r/pN6grB/1 */ public endsWithThreadAttachedText(text: string) { if (/thread\s+attached\s*:.*?\(\d*\).*?[\r\n\s]*$/i.exec(text)) { return true; } else { return false; } } /** * Remove those pesky "Thread attached" messages and the debugger prompt following them. * explanation: https://regex101.com/r/OwAWdw/4 */ public removeThreadAttachedText(text: string) { const match = /^([\r\n\s]*thread\s+attached\s*:.*?\(\d*\).*?[\r\n\s]*brightscript\s*debugger>\s*)+/i.exec(text); if (match) { return text.substring(match[0].length); } else { return text; } } /** * Removes the trailing `Brightscript Debugger>` prompt if present. If not present, returns original value * @param value */ public trimDebugPrompt(value: string) { const match = /(.*?)\r?\nBrightscript Debugger>\s*/is.exec(value); if (match) { return match[1]; } else { return value; } } /** * Check if the parameter is an expression * The HACK portion is copied from the getVariablePath function * @param expression */ public isAssignableExpression(expression: string): boolean { let parser = Parser.parse(expression); if ( isAssignmentStatement(parser.ast.statements[0]) || isDottedSetStatement(parser.ast.statements[0]) || isIndexedSetStatement(parser.ast.statements[0]) ) { return false; } //HACK: assign to a variable so it turns into a valid expression, then we'll look at the right-hand-side parser = Parser.parse(`__rokuDebugVar = ${expression}`); if ( //quit if there are parse errors parser.diagnostics.find(x => x.severity === DiagnosticSeverity.Error) || //quit if there are zero statements or more than one statement parser.ast.statements.length !== 1 ) { return false; } let value = (parser.ast.statements[0] as AssignmentStatement).value; return value instanceof Expression; } /** * Get the keys for a given variable expression, or undefined if the expression doesn't make sense. */ public getVariablePath(expression: string): string[] { //HACK: assign to a variable so it turns into a valid expression, then we'll look at the right-hand-side const parser = Parser.parse(`__rokuDebugVar = ${expression}`); if ( //quit if there are parse errors parser.diagnostics.find(x => x.severity === DiagnosticSeverity.Error) || //quit if there are zero statements or more than one statement parser.ast.statements.length !== 1 ) { return undefined; } let value = (parser.ast.statements[0] as AssignmentStatement).value; const parts = [] as string[]; while (value) { if (isVariableExpression(value)) { parts.unshift(value.name.text); return parts; } else if (isDottedGetExpression(value)) { if (value.dot.text.includes('?')) { return; } parts.unshift(value.name.text); value = value.obj; } else if (isIndexedGetExpression(value)) { if (value.questionDotToken?.text.includes('?') || value.openingSquare?.text.includes('?')) { return; } if (isLiteralExpression(value.index)) { parts.unshift( value.index.token.text ); } else { //if we found a non-literal value, this entire variable path is NOT a true variable path return; } value = value.obj; } else { //not valid return; } } } /** * Given a full URL, convert any dns name into its IP address and then return the full URL with the name replaced */ public async resolveUrl(url: string, skipCache = false) { //https://regex101.com/r/cSkoTx/1 const [, protocol, host] = /^((?:http[s]?|ftp):\/\/)?([^:\/\s]+)(:\d+)?([^?#]+)?(\?[^#]+)?(#.*)?$/.exec(url) ?? []; if (host) { const ipAddress = await this.dnsLookup(host); url = protocol + ipAddress + url.substring(protocol.length + host.length); } return url; } /* * Look up the ip address for a hostname. This is cached for the lifetime of the app, or bypassed with the `skipCache` parameter * @param host * @param skipCache * @returns */ public async dnsLookup(host: string, skipCache = false) { if (!this.dnsCache.has(host) || skipCache) { const result = await dns.promises.lookup(host); this.dnsCache.set(host, result.address ?? host); } return this.dnsCache.get(host); } private dnsCache = new Map(); /** * Is this expression the `print` keyword followed by a variable expression (like `a.b` or `a['b'].c`) * @param expression */ public isPrintVarExpression(expression: string) { expression = expression.trim().toLowerCase(); if (expression.startsWith('print') || expression.startsWith('?')) { const parts = this.getVariablePath(expression.replace(/^(print|\?)/, '')); if (parts?.length > 0) { return true; } } return false; } /* * Sleep for the given number of milliseconds * @param milliseconds * @returns */ public sleep(milliseconds: number) { return new Promise(resolve => { setTimeout(resolve, milliseconds); }); } public fence(data: string) { const fence = '--------------------'; return `\n${fence}\n${data}\n${fence}\n`; } public formatTime(ms: number) { const allocate = msUnit => { const units = Math.trunc(ms / msUnit); ms -= units * msUnit; return units; }; const hours = allocate(3600000); const minutes = allocate(60000); const seconds = allocate(1000); return `${hours > 0 ? hours + 'h' : ''}${minutes > 0 ? minutes + 'm' : ''}${seconds > 0 ? seconds + 's' : ''}${ms > 0 ? ms + 'ms' : ''}`; } public normalizeAdapterOptions(options: AdapterOptions) { options.brightScriptConsolePort ??= 8085; options.remotePort ??= 8060; } /** * Set an interval that can be cleared by calling the callback * @param intervalMs the number of milliseconds to wait for the next interval */ public setInterval(callback: (cancel: () => void) => any, intervalMs: number) { const cancel = () => { clearInterval(handle); }; const handle = setInterval(() => { callback(cancel); }, intervalMs); //call immediately callback(cancel); return cancel; } public isNullish(item: any) { return item === undefined || item === null; } /** * Translate our request options into the needle options we want for talking to a Roku. */ private buildNeedleOptions(options?: HttpRequestOptions): needle.NeedleOptions { return { //Roku responses are HTML/XML that we parse by hand; never let needle auto-parse them 'parse_response': false, //never let needle charset-decode a response: a body served with a charset in its //content-type would get every non-utf8 byte replaced with U+FFFD 'decode_response': false, //`timeout` bounds the connection and the time to the first response byte. Deliberately do //NOT set `read_timeout`: its per-chunk re-armed timer can be left running after a request //completes, later firing a spurious `request.destroy()` and keeping the event loop alive. 'open_timeout': options?.timeout, 'response_timeout': options?.timeout, headers: options?.headers, //needle does not send `Connection: close` on modern Node, so the socket to the Roku stays //open after the response and keeps the event loop alive. `agent: false` is also required: //the header alone does not stop Node's pooling `http.globalAgent` from handing back a //keep-alive socket the Roku already closed (an instant ECONNRESET). connection: 'close', agent: false }; } /** * Build our own `HttpResponse` from needle's response. */ private buildHttpResponse(response: needle.NeedleResponse): HttpResponse { return { statusCode: response.statusCode, statusMessage: response.statusMessage, headers: response.headers ?? {}, //with `parse_response`/`decode_response` disabled, needle hands back a Buffer body: response.body === undefined || response.body === null ? '' : response.body.toString() }; } /** * Do an http GET request */ public httpGet(url: string, options?: HttpRequestOptions) { return new Promise((resolve, reject) => { needle.get(url, this.buildNeedleOptions(options), (error, response) => { if (error) { return reject(error); } if (!response) { return reject(new Error(`No response received from ${url}`)); } resolve(this.buildHttpResponse(response)); }); }); } /** * Do an http POST request */ public httpPost(url: string, options?: HttpRequestOptions) { return new Promise((resolve, reject) => { needle.post(url, options?.body ?? null, this.buildNeedleOptions(options), (error, response) => { if (error) { return reject(error); } if (!response) { return reject(new Error(`No response received from ${url}`)); } resolve(this.buildHttpResponse(response)); }); }); } /** * Does the supplied value have at least one defined property with a non-nullish value? */ public hasNonNullishProperty(value: Record) { return Object.values( value ?? {} ).some(x => !this.isNullish(x)); } private minPort = 1024; public async getPort() { let port: number; try { port = await portfinder.getPortPromise({ //startPort port: this.minPort }); } catch { this.minPort = 1024; port = await portfinder.getPortPromise({ //startPort port: this.minPort }); } this.minPort = port + 1; return port; } public isTransientVariable(variableName: string) { return /^__brs_.*?__$/.test(variableName); } public handleLogFragments(currentFragment: string, newFragment: string): { completed: string; remaining: string } { let lastNewlineIndex = newFragment.lastIndexOf('\n'); if (lastNewlineIndex === -1) { return { completed: '', remaining: currentFragment + newFragment }; } let toEmit = currentFragment + newFragment.substring(0, lastNewlineIndex + 1); let remaining = newFragment.substring(lastNewlineIndex + 1); return { completed: toEmit, remaining }; } /** * Execute dispose for a series of disposable items, and empties the array in-place * @param disposables a list of functions or disposables */ public applyDispose(disposables: DisposableLike[]) { let promises = []; let exceptions = []; disposables ??= []; for (const disposable of disposables) { let value: any; try { if (typeof disposable === 'function') { value = disposable(); } else { value = disposable?.dispose?.(); } } catch (e) { exceptions.push(e); } //if this value is a promise, add a .catch to it so we don't bring down the app if (isPromise(value)) { value.catch(e => { console.error('Unhandled promise during dispose', e); }); } } //empty the array disposables.splice(0, disposables.length); } /** * Hydrate the Cloud Emulator api token onto an RCE device option from the `ROKU_RCE_TOKEN` * environment variable when the option does not already carry one. The VS Code extension * injects that variable into the debug adapter process so the token does not have to travel * through the launch config (where it would end up in DAP traffic and logs); a token supplied * directly on the device option always wins. Anything that is not a tokenless RCE device * config is returned unchanged. */ public hydrateRceTokenFromEnv(device: T): T { if (device && isRceDeviceConfig(device) && !device.rceToken && process.env.ROKU_RCE_TOKEN) { return { ...device, rceToken: process.env.ROKU_RCE_TOKEN } as T; } return device; } /** * A short human-readable identifier for a device, safe for log and error messages (never * includes credentials like the rceToken). A local device is identified by its host and an RCE * device by its instanceUrl, id, or esn. */ public getDeviceLabel(device: DeviceConfig): string { //a device may legitimately be absent on early error paths (before a session is configured) if (!device) { return undefined; } if (isRceDeviceConfig(device)) { if (isRceDeviceConfigByUrl(device)) { return device.instanceUrl; } return isRceDeviceConfigById(device) ? String(device.id) : device.esn; } return device.host; } /** * Register the socket events for logging * @param socket - the socket to listen to for events. Accepts a real `net.Socket` as well as * roku-deploy's `RokuDeploySocket` (an RCE device's telnet socket is not a real tcp socket, so its * address-related fields are always undefined; the events below that never fire for it are * harmless no-ops) * @param logger - the logger to use for logging * @param socketType - the type of socket (e.g. "client", "server") */ public registerSocketLogging(socket: net.Socket | RokuDeploySocket, logger: Logger, socketType: string) { // create a new child logger for the socket events let socketLogger = logger.createLogger(`[${socketType}]`); socket.on('error', (error: Error) => { socketLogger.error(`socket error: ${this.getSocketAddressForLogs(socket)}`, error); }); socket.on('close', (hadError: boolean) => { if (hadError) { socketLogger.error(`socket closed with error: ${this.getSocketAddressForLogs(socket)}`); } else { socketLogger.log(`socket closed: ${this.getSocketAddressForLogs(socket)}`); } }); socket.on('end', () => { socketLogger.log(`device signalling to end socket connection: ${this.getSocketAddressForLogs(socket)}`); }); socket.on('timeout', () => { socketLogger.log(`socket timeout. duration: ${socket.timeout}. ${this.getSocketAddressForLogs(socket)}`); }); socket.on('lookup', (err: Error | null, address: string, family: number | null, host: string) => { if (err) { socketLogger.error(`socket lookup error. family: ${family ? `IPv${family}` : 'unknown'} address: ${address}, host: ${host}, error: ${err}`); } else { socketLogger.log(`socket lookup. family: ${family ? `IPv${family}` : 'unknown'} address: ${address}, host: ${host}`); } }); socket.on('connectionAttempt', (ip: string, port: number, family: number) => { socketLogger.log(`socket connection attempt: ${this.getSocketAddressForLogs(socket, ip, port, family)}`); }); socket.on('connectionAttemptFailed', (ip: string, port: number, family: number, error: Error) => { socketLogger.error(`socket connection attempt failed: ${this.getSocketAddressForLogs(socket, ip, port, family)}, error: ${error.message}`); }); socket.on('connectionAttemptTimeout', (ip: string, port: number, family: number) => { socketLogger.log(`socket connection timed out: ${this.getSocketAddressForLogs(socket, ip, port, family)}`); }); socket.on('connect', () => { socketLogger.log(`socket connected: ${this.getSocketAddressForLogs(socket)}`); }); socket.on('ready', () => { socketLogger.log(`socket is ready for use: ${this.getSocketAddressForLogs(socket)}`); }); } private getSocketAddressForLogs(socket: net.Socket | RokuDeploySocket, ip?: string, port?: number, family?: number): string { let familyString: string; if (typeof family === 'number') { familyString = `IPv${family}`; } else { familyString = socket.localFamily; } const remoteString = `remote: ${familyString} ${ip ?? socket.remoteAddress}:${port ?? socket.remotePort}`; if (socket.localAddress !== undefined && socket.localPort !== undefined) { return `local: ${socket.localFamily ? socket.localFamily : ''}${socket.localAddress}:${socket.localPort} -> ${remoteString}`; } else { return remoteString; } } public truncate(value: string, maxLength: number): string { if (value.length > maxLength) { return value.substring(0, maxLength - 3) + '...'; } return value; } /** * Coerce any value into an Error object. If it's already an Error, return it as-is. If it's not, create a new Error with the stringified value as the message * @param error * @returns */ public toError(error: any): Error { if (error?.constructor.name === Error.constructor.name) { return error; } else { return new Error(String(error)); } } } export function defer() { let _resolve: (value?: PromiseLike | T) => void; let _reject: (reason?: any) => void; let promise = new Promise((resolveValue, rejectValue) => { _resolve = resolveValue; _reject = rejectValue; }); return { promise: promise, tryResolve: function tryResolve(value?: PromiseLike | T) { if (!this.isCompleted) { this.resolve(value); } }, resolve: function resolve(value?: PromiseLike | T) { if (!this.isResolved) { this.isResolved = true; _resolve(value); _resolve = undefined; } else { throw new Error( `Attempted to resolve a promise that was already ${this.isResolved ? 'resolved' : 'rejected'}.` + `New value: ${JSON.stringify(value)}` ); } }, tryReject: function tryReject(reason?: any) { if (!this.isCompleted) { this.reject(reason); } }, reject: function reject(reason?: any) { if (!this.isCompleted) { this.isRejected = true; _reject(reason); _reject = undefined; } else { throw new Error( `Attempted to reject a promise that was already ${this.isResolved ? 'resolved' : 'rejected'}.` + `New error message: ${JSON.stringify(serializeError(reason))}` ); } }, isResolved: false, isRejected: false, get isCompleted() { return this.isResolved || this.isRejected; } }; } export const util = new Util(); export interface Deferred { promise: Promise; resolve(value?: T); reject(error?: any); } /** * The subset of request options this library actually supports. Previously this was * `CoreOptions` from `@types/request`; it was narrowed to drop the `postman-request` * dependency, which carried vulnerable transitive deps. */ export interface HttpRequestOptions { /** * Milliseconds to wait for the connection to open and for the first response byte. */ timeout?: number; headers?: Record; body?: string; } /** * The response shape returned by `util.httpPost()`. Deliberately our own type rather than needle's, * so `@types/needle` stays a devDependency and needle is not part of this package's public surface. */ export interface HttpResponse { statusCode: number; statusMessage?: string; /** Response headers, lower-cased names. */ headers: Record; /** The response body, decoded as a utf8 string (empty string for bodyless responses). */ body: string; }