feat(debug-log): create foundation of Roku debug log command

A Roku device has a debug log which is accessible via telnet.  We can use this to provide data via the WD `/session/:sessionId/log` route.

What's here so far is an implementation of a thing which just listens on an arbitrary telnet server and pipes its output to a file, since that's probably unwise to keep in memory.  When the command is issued, the driver can send the contents of the file to the client (and probably truncate it?).

This depends on type changes not yet published in Appium and will fail CI.

Note: The reason for two separate Telnet libs is that one provides a server & client and another only provides a client, but the client in the former is broken and I couldn't find another decent module which creates a dummy telnet server for testing.

Author: boneskull

lib/debug-log.js

@@ -0,0 +1,325 @@
+import {fs} from 'appium/support';
+import log from './logger';
+import _ from 'lodash';
+import slug from 'slug';
+import B from 'bluebird';
+import _fs from 'node:fs';
+import path from 'node:path';
+import envPaths from 'env-paths';
+import {lock} from 'proper-lockfile';
+import {Telnet} from 'telnet-client';
+import {EventEmitter} from 'node:events';
+
+/**
+ * Debug port on Roku device
+ * @see https://developer.roku.com/en-ca/docs/developer-program/debugging/debugging-channels.md
+ */
+export const DEBUG_PORT = 8085;
+
+/**
+ * Base lockfile options, sans the lockfile path
+ * @internal
+ */
+const BASE_LOCK_OPTS = Object.freeze(
+  /** @type {import('proper-lockfile').LockOptions} */ ({
+    realpath: false,
+    fs: _fs,
+    retries: {
+      retries: 3,
+      minTimeout: 100,
+      maxTimeout: 1000,
+      unref: true,
+    },
+  })
+);
+
+const DEFAULT_TELNET_OPTS = Object.freeze(
+  /** @type {import('telnet-client').ConnectOptions} */ ({
+    negotiationMandatory: false,
+    encoding: 'utf8',
+  })
+);
+
+const DEFAULT_ROKU_DEBUG_OPTS = Object.freeze(
+  /** @type {RokuDebugLogOpts} */ ({
+    telnetOpts: DEFAULT_TELNET_OPTS,
+  })
+);
+
+export class RokuDebugLog extends EventEmitter {
+  /**
+   * User-provided opts
+   * @type {RokuDebugLogOpts}
+   */
+  #opts;
+
+  /**
+   * Host of Telnet server
+   * @type {string}
+   */
+  #host;
+
+  /**
+   * Host of Telnet server, slugified for use in filenames
+   * @type {string}
+   */
+  #hostSlug;
+
+  /**
+   * Directory which will contain debug logs
+   * @type {string}
+   */
+  #logDirpath;
+
+  /**
+   * Directory which will contain lockfiles
+   * @type {string}
+   */
+  #lockfileDirpath;
+
+  /** @type {Telnet|undefined} */
+  #telnetClient;
+
+  /**
+   * If logfile is locked, this will be a wrapped unlock function.
+   *
+   * @this {null}
+   * @type {() => Promise<void>|undefined}
+   */
+  #_unlock;
+
+  /**
+   * Sets class props and determines logfile path
+   * @param {string} host
+   * @param {RokuDebugLogOpts} [opts]
+   */
+  constructor(host, opts = {}) {
+    super();
+    this.#host = host;
+    this.#opts = _.defaultsDeep(opts, DEFAULT_ROKU_DEBUG_OPTS);
+
+    this.#hostSlug = RokuDebugLog.slugify(host);
+
+    const {log: logDirpath, temp: lockfileDirpath} = envPaths('appium-roku-driver');
+    this.#logDirpath = logDirpath;
+    this.#lockfileDirpath = lockfileDirpath;
+
+    if (!this.#opts.logPath) {
+      const logFileBasename = `debug-${this.#hostSlug}.log`;
+      this.#opts.logPath = path.join(logDirpath, logFileBasename);
+    }
+  }
+
+  /**
+   * Slugifies a string in preparation for writing to filesystem
+   *
+   * May be used by those wanting to provide a custom `logPath` option to the constructor
+   *
+   * Just a re-export of `slug` module
+   * @see https://npm.im/slug
+   */
+  static slugify = slug;
+
+  /**
+   * Path to the logfile
+   */
+  get logPath() {
+    return this.#opts.logPath;
+  }
+
+  /**
+   * Locks the logfile if we're not using a file descriptor.
+   * @param {string} basename
+   * @param {string} logPath
+   * @param {string} tempDirpath
+   * @param {LockLogfileOpts} [opts]
+   * @returns {Promise<() => Promise<void>>} - An async unlock function. If we're using a file descriptor, this is a no-op.
+   */
+  async #lockLogfile(basename, logPath, tempDirpath, opts = {}) {
+    // `prepare-lockfile` does not support file descriptors
+    if (_.isNil(opts.fd)) {
+      const lockfilePath = path.join(tempDirpath, `${basename}.lock`);
+      const originalUnlock = await lock(logPath, {...BASE_LOCK_OPTS, lockfilePath});
+      const wrappedUnlock = async () => {
+        try {
+          await originalUnlock();
+          log.debug(`Unlocked ${logPath}`);
+        } catch (err) {
+          // todo handle better
+          log.warn(err);
+        }
+      };
+      return wrappedUnlock;
+    }
+    return () => B.resolve();
+  }
+
+  /**
+   * Unlocks lockfile and tries not to leak memory
+   */
+  async #cleanup() {
+    this.#telnetClient = undefined;
+    try {
+      await this.#_unlock?.();
+    } finally {
+      this.#_unlock = undefined;
+    }
+  }
+
+  /**
+   * Prepares filesystem for writing debug log
+   *
+   * Makes the dirs
+   */
+  async #prepareFs() {
+    await B.all([fs.mkdirp(this.#logDirpath), fs.mkdirp(this.#lockfileDirpath)]);
+  }
+
+  /**
+   * Connects to a debug log and pipes its output somewhere.  Returns a wrapper around the socket.
+   * @returns {Promise<void>} - Telnet client
+   */
+  async connect() {
+    await this.#prepareFs();
+
+    this.#_unlock = await this.#lockLogfile(this.#hostSlug, this.logPath, this.#lockfileDirpath, {
+      fd: this.#opts.logFd,
+    });
+    const client = (this.#telnetClient = new Telnet());
+    await client.connect({
+      host: this.#host,
+      port: this.#opts.port,
+      encoding: 'utf8',
+      ...this.#opts.telnetOpts,
+    });
+    log.debug(`Connected to ${this.#host}`);
+
+    client
+      .on('error', (err) => {
+        log.error(err);
+        try {
+          this.emit('error', err);
+        } finally {
+          this.#cleanup();
+        }
+      })
+      .on('close', () => {
+        log.info(`Connection to host ${this.#host} closed`);
+        try {
+          this.emit('close');
+        } finally {
+          this.#cleanup();
+        }
+      })
+      .on('timeout', () => {
+        // inactivity timeout.  'close' will also be emitted (I think), so don't unlock here
+        this.emit('timeout');
+      });
+
+    this.#pipeToLog();
+  }
+
+  /**
+   * Configure a pipe from the connected telnet client to the log file
+   */
+  #pipeToLog = () => {
+    const sock = this.#telnetClient?.getSocket();
+    if (sock) {
+      // note: the encoding may just be `ascii` since that's what telnet is supposed to be
+      sock
+        .setEncoding('utf8')
+        .on('finish', () => {
+          this.emit('finish');
+        })
+        .on('open', () => {
+          log.info(`Now writing to logfile ${this.logPath}`);
+        })
+        .pipe(_fs.createWriteStream(this.logPath, {fd: this.#opts.logFd, encoding: 'utf8'}));
+
+    } else {
+      throw new ReferenceError('Not connected to host');
+    }
+  };
+
+  /**
+   * Resolves w/ the entire contents of the logfile
+   */
+  async getLog() {
+    return await fs.readFile(this.logPath, 'utf8');
+  }
+
+  /**
+   * Truncates the logfile.
+   *
+   * Do not use while connected to the host.
+   */
+  async truncate() {
+    try {
+      await this.#cleanup?.();
+    } catch {
+      throw new Error(`Could not unlock logfile at ${this.logPath}; disconnect first`);
+    }
+    await fs.writeFile(this.logPath, '');
+    log.info(`Truncated logfile at ${this.logPath}`);
+  }
+
+  /**
+   * Read a single chunk from the log
+   * @returns {Promise<string|undefined>}
+   */
+  async nextData() {
+    return await this.#telnetClient?.nextData();
+  }
+
+  /**
+   * Iterates over data coming out of Telnet host
+   * @returns {AsyncGenerator<string>}
+   */
+  async *[Symbol.asyncIterator]() {
+    const sock = this.#telnetClient?.getSocket();
+    if (sock) {
+      for await (const chunk of sock) {
+        yield chunk;
+      }
+    }
+  }
+
+  /**
+   * Disconnect from the host (if connected)
+   */
+  async disconnect() {
+    if (this.#telnetClient) {
+      try {
+        await this.#telnetClient.end();
+      } catch {
+        await this.#telnetClient.destroy();
+      } finally {
+        await this.#cleanup();
+      }
+    }
+  }
+
+  /**
+   * Returns `true` if we're connected to the host
+   */
+  get isConnected() {
+    return Boolean(this.#telnetClient);
+  }
+}
+
+/**
+ * Options for {@linkcode RokuDebugLog}
+ * @typedef RokuDebugLogOpts
+ * @property {number} [port] - Debug port on Roku device; `8085` by default
+ * @property {string} [logPath] - Path to destination
+ * @property {_fs.promises.FileHandle | number} [logFd] - If provided {@linkcode ConnectDebugLogOpts.logPath} will be ignored
+ * @property {import('telnet-client').ConnectOptions} [telnetOpts] - Options for {@linkcode Telnet}
+ */
+
+/**
+ * Options for {@linkcode lockLogfile}
+ * @internal
+ * @private
+ * @typedef LockLogfileOpts
+ * @property {_fs.promises.FileHandle | number} [fd]
+ */