@appium/support 7.0.5 → 7.0.6

package/lib/mjpeg.ts

@@ -0,0 +1,186 @@
+import _ from 'lodash';
+import log from './logger';
+import B from 'bluebird';
+import {requireSharp} from './image-util';
+import {Writable, type WritableOptions, type Readable} from 'node:stream';
+import {requirePackage} from './node';
+import axios from 'axios';
+
+/** Constructor for mjpeg-consumer (lazy-loaded) */
+type MJpegConsumerConstructor = new () => NodeJS.ReadWriteStream;
+
+let MJpegConsumer: MJpegConsumerConstructor | null = null;
+
+/**
+ * @throws {Error} If `mjpeg-consumer` module is not installed or cannot be loaded
+ */
+async function initMJpegConsumer(): Promise<MJpegConsumerConstructor> {
+  if (!MJpegConsumer) {
+    try {
+      MJpegConsumer = (await requirePackage('mjpeg-consumer')) as MJpegConsumerConstructor;
+    } catch {
+      throw new Error(
+        'mjpeg-consumer module is required to use MJPEG-over-HTTP features. ' +
+          'Please install it first (npm i -g mjpeg-consumer) and restart Appium.'
+      );
+    }
+  }
+  return MJpegConsumer;
+}
+
+const MJPEG_SERVER_TIMEOUT_MS = 10000;
+
+/** Class which stores the last bit of data streamed into it */
+export class MJpegStream extends Writable {
+  readonly errorHandler: (err: Error) => void;
+  readonly url: string;
+  /** Number of JPEG frames received so far (reset on {@linkcode clear}). Use stream['updateCount'] in tests if needed. */
+  private updateCount = 0;
+  /** Last received JPEG chunk (base64 via {@linkcode lastChunkBase64}); `null` when no data yet or after {@linkcode clear}/stop. Use stream['lastChunk'] in tests if needed. */
+  private lastChunk: Buffer | null = null;
+  private registerStartSuccess: (() => void) | null = null;
+  private registerStartFailure: ((err: Error) => void) | null = null;
+  private responseStream: Readable | null = null;
+  private consumer: NodeJS.ReadWriteStream | null = null;
+
+  /**
+   * @param mJpegUrl - URL of MJPEG-over-HTTP stream
+   * @param errorHandler - additional function that will be called in the case of any errors
+   * @param options - Options to pass to the Writable constructor
+   */
+  constructor(
+    mJpegUrl: string,
+    errorHandler: (err: Error) => void = _.noop,
+    options: WritableOptions = {}
+  ) {
+    super(options);
+    this.errorHandler = errorHandler;
+    this.url = mJpegUrl;
+    this.clear();
+  }
+
+  get lastChunkBase64(): string | null {
+    const lastChunk = this.lastChunk;
+    if (lastChunk && !_.isEmpty(lastChunk) && _.isBuffer(lastChunk)) {
+      return lastChunk.toString('base64');
+    }
+    return null;
+  }
+
+  async lastChunkPNG(): Promise<Buffer | null> {
+    const chunk = this.lastChunk;
+    if (!chunk || _.isEmpty(chunk) || !_.isBuffer(chunk)) {
+      return null;
+    }
+    try {
+      return await requireSharp()(chunk).png().toBuffer();
+    } catch (err: any) {
+      log.warn(`Cannot convert MJPEG chunk to PNG: ${err.message}`);
+      return null;
+    }
+  }
+
+  async lastChunkPNGBase64(): Promise<string | null> {
+    const png = await this.lastChunkPNG();
+    return png ? png.toString('base64') : null;
+  }
+
+  clear(): void {
+    this.registerStartSuccess = null;
+    this.registerStartFailure = null;
+    this.responseStream = null;
+    this.consumer = null;
+    this.lastChunk = null;
+    this.updateCount = 0;
+  }
+
+  async start(serverTimeout = MJPEG_SERVER_TIMEOUT_MS): Promise<void> {
+    this.stop();
+
+    const Consumer = await initMJpegConsumer();
+    this.consumer = new Consumer();
+    const url = this.url;
+    try {
+      this.responseStream = (
+        await axios({
+          url,
+          responseType: 'stream',
+          timeout: serverTimeout,
+        })
+      ).data as Readable;
+    } catch (e) {
+      let message: string;
+      if (e && typeof e === 'object' && 'response' in e) {
+        message = JSON.stringify((e as {response: unknown}).response);
+      } else if (e instanceof Error) {
+        message = e.message;
+      } else {
+        message = String(e);
+      }
+      throw new Error(
+        `Cannot connect to the MJPEG stream at ${url}. Original error: ${message}`
+      );
+    }
+
+    const onErr = (err: Error) => {
+      this.lastChunk = null;
+      log.error(`Error getting MJpeg screenshot chunk: ${err.message}`);
+      this.errorHandler(err);
+      if (this.registerStartFailure) {
+        this.registerStartFailure(err);
+      }
+    };
+    const onClose = () => {
+      log.debug(`The connection to MJPEG server at ${url} has been closed`);
+      this.lastChunk = null;
+    };
+
+    // TODO: replace with native Promises in Appium 4
+    const startPromise = new B<void>((res, rej) => {
+      this.registerStartSuccess = res;
+      this.registerStartFailure = rej;
+    }).timeout(
+      serverTimeout,
+      `Waited ${serverTimeout}ms but the MJPEG server never sent any images`
+    );
+
+    (this.responseStream as Readable & {pipe<T extends Writable>(dest: T): T})
+      .once('close', onClose)
+      .on('error', onErr)
+      .pipe(this.consumer as unknown as Writable)
+      .pipe(this);
+
+    await startPromise;
+  }
+
+  stop(): void {
+    if (this.consumer) {
+      this.consumer.unpipe(this);
+    }
+    if (this.responseStream) {
+      if (this.consumer) {
+        this.responseStream.unpipe(this.consumer);
+      }
+      this.responseStream.destroy();
+    }
+    this.clear();
+  }
+
+  /* eslint-disable @typescript-eslint/no-unused-vars -- Writable.write signature requires encoding and callback */
+  /* eslint-disable promise/prefer-await-to-callbacks -- Node Writable.write is callback-based */
+  override write(
+    data: Buffer | string | Uint8Array,
+    encoding?: BufferEncoding | ((error: Error | null) => void),
+    callback?: (error: Error | null) => void
+  ): boolean {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    /* eslint-enable promise/prefer-await-to-callbacks */
+    this.lastChunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    this.updateCount++;
+    if (this.registerStartSuccess) {
+      this.registerStartSuccess();
+      this.registerStartSuccess = null;
+    }
+    return true;
+  }
+}

package/lib/{mkdirp.js → mkdirp.ts}

@@ -1,6 +1,6 @@
 import {fs} from './fs';
+
 /**
  * @deprecated Use `fs.mkdirp` instead.
  */
-const {mkdirp} = fs;
-export {mkdirp};
+export const {mkdirp} = fs;

package/lib/net.ts

@@ -0,0 +1,305 @@
+import _ from 'lodash';
+import {fs} from './fs';
+import {toReadableSizeString} from './util';
+import log from './logger';
+import Ftp from 'jsftp';
+import {Timer} from './timing';
+import axios, {type AxiosBasicCredentials, type Method, type RawAxiosRequestConfig} from 'axios';
+import FormData from 'form-data';
+import type {HTTPHeaders} from '@appium/types';
+
+const DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
+
+/** Common options for {@linkcode uploadFile} and {@linkcode downloadFile}. */
+export interface NetOptions {
+  /** Whether to log the actual download performance (e.g. timings and speed). Defaults to true. */
+  isMetered?: boolean;
+  /** Authentication credentials */
+  auth?: AuthCredentials;
+}
+
+/** Basic auth credentials; used by {@linkcode NetOptions}. */
+export interface AuthCredentials {
+  /** Non-empty user name (or use `username` for axios-style) */
+  user?: string;
+  /** Non-empty password (or use `password` for axios-style) */
+  pass?: string;
+  username?: string;
+  password?: string;
+}
+
+/** Specific options for {@linkcode downloadFile}. */
+export interface DownloadOptions extends NetOptions {
+  /** Request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS} */
+  timeout?: number;
+  /** Request headers mapping */
+  headers?: Record<string, unknown>;
+}
+
+/** Options for {@linkcode uploadFile} when the remote uses the `http(s)` protocol. */
+export interface HttpUploadOptions extends NetOptions {
+  /** Additional request headers */
+  headers?: HTTPHeaders;
+  /** HTTP method for file upload. Defaults to 'POST'. */
+  method?: Method;
+  /** Request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS} */
+  timeout?: number;
+  /**
+   * Name of the form field containing the file. Any falsy value uses non-multipart upload.
+   * Defaults to 'file'.
+   */
+  fileFieldName?: string;
+  /**
+   * Additional form fields. Only considered if `fileFieldName` is set.
+   */
+  formFields?: Record<string, unknown> | [string, unknown][];
+}
+
+/**
+ * Options for {@linkcode uploadFile} when the remote uses the `ftp` protocol.
+ */
+export interface FtpUploadOptions extends NetOptions {}
+
+/** @deprecated Use {@linkcode FtpUploadOptions} instead. */
+export type NotHttpUploadOptions = FtpUploadOptions;
+
+/**
+ * Uploads the given file to a remote location. HTTP(S) and FTP protocols are supported.
+ */
+export async function uploadFile(
+  localPath: string,
+  remoteUri: string,
+  uploadOptions: HttpUploadOptions | FtpUploadOptions = {}
+): Promise<void> {
+  if (!(await fs.exists(localPath))) {
+    throw new Error(`'${localPath}' does not exist or is not accessible`);
+  }
+
+  const {isMetered = true} = uploadOptions;
+  const url = new URL(remoteUri);
+  const {size} = await fs.stat(localPath);
+  if (isMetered) {
+    log.info(`Uploading '${localPath}' of ${toReadableSizeString(size)} size to '${remoteUri}'`);
+  }
+  const timer = new Timer().start();
+  if (isHttpUploadOptions(uploadOptions, url)) {
+    if (!uploadOptions.fileFieldName) {
+      uploadOptions.headers = {
+        ...(_.isPlainObject(uploadOptions.headers) ? uploadOptions.headers : {}),
+        'Content-Length': size,
+      };
+    }
+    await uploadFileToHttp(fs.createReadStream(localPath), url, uploadOptions);
+  } else if (isFtpUploadOptions(uploadOptions, url)) {
+    await uploadFileToFtp(fs.createReadStream(localPath), url, uploadOptions);
+  } else {
+    throw new Error(
+      `Cannot upload the file at '${localPath}' to '${remoteUri}'. ` +
+        `Unsupported remote protocol '${url.protocol}'. ` +
+        `Only http/https and ftp/ftps protocols are supported.`
+    );
+  }
+  if (isMetered) {
+    log.info(
+      `Uploaded '${localPath}' of ${toReadableSizeString(size)} size in ` +
+        `${timer.getDuration().asSeconds.toFixed(3)}s`
+    );
+  }
+}
+
+/**
+ * Downloads the given file via HTTP(S).
+ *
+ * @throws {Error} If download operation fails
+ */
+export async function downloadFile(
+  remoteUrl: string,
+  dstPath: string,
+  downloadOptions: DownloadOptions = {}
+): Promise<void> {
+  const {isMetered = true, auth, timeout = DEFAULT_TIMEOUT_MS, headers} = downloadOptions;
+
+  const requestOpts: RawAxiosRequestConfig = {
+    url: remoteUrl,
+    responseType: 'stream',
+    timeout,
+  };
+  const axiosAuth = toAxiosAuth(auth);
+  if (axiosAuth) {
+    requestOpts.auth = axiosAuth;
+  }
+  if (_.isPlainObject(headers)) {
+    requestOpts.headers = headers as RawAxiosRequestConfig['headers'];
+  }
+
+  const timer = new Timer().start();
+  let responseLength: number;
+  try {
+    const writer = fs.createWriteStream(dstPath);
+    const {data: responseStream, headers: responseHeaders} = await axios(requestOpts);
+    responseLength = parseInt(String(responseHeaders['content-length'] ?? '0'), 10);
+    (responseStream as NodeJS.ReadableStream).pipe(writer);
+
+    await new Promise<void>((resolve, reject) => {
+      (responseStream as NodeJS.ReadableStream).once('error', reject);
+      writer.once('finish', () => resolve());
+      writer.once('error', (e: Error) => {
+        (responseStream as NodeJS.ReadableStream).unpipe(writer);
+        reject(e);
+      });
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot download the file from ${remoteUrl}: ${message}`);
+  }
+
+  const {size} = await fs.stat(dstPath);
+  if (responseLength && size !== responseLength) {
+    await fs.rimraf(dstPath);
+    throw new Error(
+      `The size of the file downloaded from ${remoteUrl} (${size} bytes) ` +
+        `differs from the one in Content-Length response header (${responseLength} bytes)`
+    );
+  }
+  if (isMetered) {
+    const secondsElapsed = timer.getDuration().asSeconds;
+    log.debug(
+      `${remoteUrl} (${toReadableSizeString(size)}) ` +
+        `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`
+    );
+    if (secondsElapsed >= 2) {
+      const bytesPerSec = Math.floor(size / secondsElapsed);
+      log.debug(`Approximate download speed: ${toReadableSizeString(bytesPerSec)}/s`);
+    }
+  }
+}
+
+// #region Private helpers
+
+type AuthLike = AuthCredentials | AxiosBasicCredentials;
+
+function toAxiosAuth(auth: AuthLike | undefined): AxiosBasicCredentials | null {
+  if (!auth || !_.isPlainObject(auth)) {
+    return null;
+  }
+
+  const username = 'username' in auth ? auth.username : auth.user;
+  const password = 'password' in auth ? auth.password : auth.pass;
+  return username && password ? {username, password} : null;
+}
+
+async function uploadFileToHttp(
+  localFileStream: NodeJS.ReadableStream,
+  parsedUri: URL,
+  uploadOptions: HttpUploadOptions = {}
+): Promise<void> {
+  const {
+    method = 'POST',
+    timeout = DEFAULT_TIMEOUT_MS,
+    headers,
+    auth,
+    fileFieldName = 'file',
+    formFields,
+  } = uploadOptions;
+  const {href} = parsedUri;
+
+  const requestOpts: RawAxiosRequestConfig = {
+    url: href,
+    method,
+    timeout,
+    maxContentLength: Infinity,
+    maxBodyLength: Infinity,
+  };
+  const axiosAuth = toAxiosAuth(auth);
+  if (axiosAuth) {
+    requestOpts.auth = axiosAuth;
+  }
+  if (fileFieldName) {
+    const form = new FormData();
+    if (formFields) {
+      let pairs: [string, unknown][] = [];
+      if (_.isArray(formFields)) {
+        pairs = formFields as [string, unknown][];
+      } else if (_.isPlainObject(formFields)) {
+        pairs = _.toPairs(formFields);
+      }
+      for (const [key, value] of pairs) {
+        if (_.toLower(key) !== _.toLower(fileFieldName)) {
+          form.append(key, value as string | Buffer);
+        }
+      }
+    }
+    // AWS S3 POST upload requires this to be the last field; do not move before formFields.
+    form.append(fileFieldName, localFileStream);
+    requestOpts.headers = {
+      ...(_.isPlainObject(headers) ? headers : {}),
+      ...form.getHeaders(),
+    };
+    requestOpts.data = form;
+  } else {
+    if (_.isPlainObject(headers)) {
+      requestOpts.headers = headers;
+    }
+    requestOpts.data = localFileStream;
+  }
+  log.debug(
+    `Performing ${method} to ${href} with options (excluding data): ` +
+      JSON.stringify(_.omit(requestOpts, ['data']))
+  );
+
+  const {status, statusText} = await axios(requestOpts);
+  log.info(`Server response: ${status} ${statusText}`);
+}
+
+async function uploadFileToFtp(
+  localFileStream: string | Buffer | NodeJS.ReadableStream,
+  parsedUri: URL,
+  uploadOptions: FtpUploadOptions = {}
+): Promise<void> {
+  const {auth} = uploadOptions;
+  const {protocol, hostname, port, pathname} = parsedUri;
+
+  const ftpOpts: {host: string; port: number; user?: string; pass?: string} = {
+    host: hostname ?? '',
+    port: port !== undefined && port !== '' ? _.parseInt(port, 10) : 21,
+  };
+  if (auth?.user && auth?.pass) {
+    ftpOpts.user = auth.user;
+    ftpOpts.pass = auth.pass;
+  }
+  log.debug(`${protocol.slice(0, -1)} upload options: ${JSON.stringify(ftpOpts)}`);
+  return await new Promise<void>((resolve, reject) => {
+    new Ftp(ftpOpts).put(localFileStream, pathname, (err) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function isHttpUploadOptions(
+  opts: HttpUploadOptions | FtpUploadOptions,
+  url: URL
+): opts is HttpUploadOptions {
+  try {
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/** Returns true if the URL is FTP, i.e. the options are for FTP upload. */
+function isFtpUploadOptions(
+  opts: HttpUploadOptions | FtpUploadOptions,
+  url: URL
+): opts is FtpUploadOptions {
+  try {
+    return url.protocol === 'ftp:';
+  } catch {
+    return false;
+  }
+}
+
+// #endregion