@appium/support 7.0.4 → 7.0.6

package/lib/mjpeg.js

@@ -1,207 +0,0 @@
-import _ from 'lodash';
-import log from './logger';
-import B from 'bluebird';
-import {requireSharp} from './image-util';
-import {Writable} from 'stream';
-import {requirePackage} from './node';
-import axios from 'axios';
-
-// lazy load this, as it might not be available
-let MJpegConsumer = null;
-
-/**
- * @throws {Error} If `mjpeg-consumer` module is not installed or cannot be loaded
- */
-async function initMJpegConsumer() {
-  if (!MJpegConsumer) {
-    try {
-      MJpegConsumer = await requirePackage('mjpeg-consumer');
-    } catch {}
-  }
-  if (!MJpegConsumer) {
-    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.'
-    );
-  }
-}
-
-// amount of time to wait for the first image in the stream
-const MJPEG_SERVER_TIMEOUT_MS = 10000;
-
-/** Class which stores the last bit of data streamed into it */
-class MJpegStream extends Writable {
-  /**
-   * @type {number}
-   */
-  updateCount = 0;
-
-  /**
-   * Create an MJpegStream
-   * @param {string} mJpegUrl - URL of MJPEG-over-HTTP stream
-   * @param {function} [errorHandler=noop] - additional function that will be
-   * called in the case of any errors.
-   * @param {object} [options={}] - Options to pass to the Writable constructor
-   */
-  constructor(mJpegUrl, errorHandler = _.noop, options = {}) {
-    super(options);
-
-    this.errorHandler = errorHandler;
-    this.url = mJpegUrl;
-    this.clear();
-  }
-
-  /**
-   * Get the base64-encoded version of the JPEG
-   *
-   * @returns {?string} base64-encoded JPEG image data
-   * or `null` if no image can be parsed
-   */
-  get lastChunkBase64() {
-    const lastChunk = /** @type {Buffer} */ (this.lastChunk);
-    return !_.isEmpty(this.lastChunk) && _.isBuffer(this.lastChunk)
-      ? lastChunk.toString('base64')
-      : null;
-  }
-
-  /**
-   * Get the PNG version of the JPEG buffer
-   *
-   * @returns {Promise<Buffer?>} PNG image data or `null` if no PNG
-   * image can be parsed
-   */
-  async lastChunkPNG() {
-    const lastChunk = /** @type {Buffer} */ (this.lastChunk);
-    if (_.isEmpty(lastChunk) || !_.isBuffer(lastChunk)) {
-      return null;
-    }
-
-    try {
-      return await requireSharp()(lastChunk).png().toBuffer();
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Get the base64-encoded version of the PNG
-   *
-   * @returns {Promise<string?>} base64-encoded PNG image data
-   * or `null` if no image can be parsed
-   */
-  async lastChunkPNGBase64() {
-    const png = await this.lastChunkPNG();
-    return png ? png.toString('base64') : null;
-  }
-
-  /**
-   * Reset internal state
-   */
-  clear() {
-    this.registerStartSuccess = null;
-    this.registerStartFailure = null;
-    this.responseStream = null;
-    this.consumer = null;
-    this.lastChunk = null;
-    this.updateCount = 0;
-  }
-
-  /**
-   * Start reading the MJpeg stream and storing the last image
-   */
-  async start(serverTimeout = MJPEG_SERVER_TIMEOUT_MS) {
-    // ensure we're not started already
-    this.stop();
-
-    await initMJpegConsumer();
-
-    this.consumer = new MJpegConsumer();
-    const url = this.url;
-    try {
-      this.responseStream = (
-        await axios({
-          url,
-          responseType: 'stream',
-          timeout: serverTimeout,
-        })
-      ).data;
-    } catch (e) {
-      throw new Error(
-        `Cannot connect to the MJPEG stream at ${url}. ` +
-        `Original error: ${_.has(e, 'response') ? JSON.stringify(e.response) : /** @type {Error} */ (e).message}`
-      );
-    }
-
-    const onErr = (/** @type {Error} */ err) => {
-      // Make sure we don't get an outdated screenshot if there was an 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;
-    };
-    // use the deferred pattern so we can wait for the start of the stream
-    // based on what comes in from an external pipe
-    const startPromise = new B((res, rej) => {
-      this.registerStartSuccess = res;
-      this.registerStartFailure = rej;
-    })
-      // start a timeout so that if the server does not return data, we don't
-      // block forever.
-      .timeout(
-        serverTimeout,
-        `Waited ${serverTimeout}ms but the MJPEG server never sent any images`
-      );
-
-    this.responseStream
-      .once('close', onClose)
-      .on('error', onErr) // ensure we do something with errors
-      .pipe(this.consumer) // allow chunking and transforming of jpeg data
-      .pipe(this); // send the actual jpegs to ourself
-
-    await startPromise;
-  }
-
-  /**
-   * Stop reading the MJpeg stream. Ensure we disconnect all the pipes and stop
-   * the HTTP request itself. Then reset the state.
-   */
-  stop() {
-    if (this.consumer) {
-      this.consumer.unpipe(this);
-    }
-    if (this.responseStream) {
-      if (this.consumer) {
-        this.responseStream.unpipe(this.consumer);
-      }
-      this.responseStream.destroy();
-    }
-    this.clear();
-  }
-
-  /**
-   * Override the Writable write() method in order to save the last image and
-   * log the number of images we have received
-   * @override
-   * @param {Buffer} data - binary data streamed from the MJpeg consumer
-   */
-  write(data) {
-    this.lastChunk = data;
-    this.updateCount++;
-
-    if (this.registerStartSuccess) {
-      this.registerStartSuccess();
-      this.registerStartSuccess = null;
-    }
-
-    return true;
-  }
-}
-
-export {MJpegStream};

package/lib/net.js

@@ -1,336 +0,0 @@
-import _ from 'lodash';
-import {fs} from './fs';
-import B from 'bluebird';
-import {toReadableSizeString} from './util';
-import log from './logger';
-import Ftp from 'jsftp';
-import {Timer} from './timing';
-import axios from 'axios';
-import FormData from 'form-data';
-
-const DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
-
-/**
- * Type guard for param to {@linkcode toAxiosAuth}
- * @param {any} value
- * @returns {value is AuthCredentials | import('axios').AxiosBasicCredentials}
- */
-function isAxiosAuth(value) {
-  return _.isPlainObject(value);
-}
-
-/**
- * Converts {@linkcode AuthCredentials} to credentials understood by {@linkcode axios}.
- * @param {AuthCredentials | import('axios').AxiosBasicCredentials} [auth]
- * @returns {import('axios').AxiosBasicCredentials?}
- */
-function toAxiosAuth(auth) {
-  if (!isAxiosAuth(auth)) {
-    return null;
-  }
-
-  const axiosAuth = {
-    username: 'username' in auth ? auth.username : auth.user,
-    password: 'password' in auth ? auth.password : auth.pass,
-  };
-  return axiosAuth.username && axiosAuth.password ? axiosAuth : null;
-}
-
-/**
- * @param {NodeJS.ReadableStream} localFileStream
- * @param {URL} parsedUri
- * @param {HttpUploadOptions & NetOptions} [uploadOptions]
- */
-async function uploadFileToHttp(
-  localFileStream,
-  parsedUri,
-  uploadOptions = /** @type {HttpUploadOptions & NetOptions} */ ({})
-) {
-  const {
-    method = 'POST',
-    timeout = DEFAULT_TIMEOUT_MS,
-    headers,
-    auth,
-    fileFieldName = 'file',
-    formFields,
-  } = uploadOptions;
-  const {href} = parsedUri;
-
-  /** @type {import('axios').RawAxiosRequestConfig} */
-  const requestOpts = {
-    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 = [];
-      if (_.isArray(formFields)) {
-        pairs = formFields;
-      } else if (_.isPlainObject(formFields)) {
-        pairs = _.toPairs(formFields);
-      }
-      for (const [key, value] of pairs) {
-        if (_.toLower(key) !== _.toLower(fileFieldName)) {
-          form.append(key, value);
-        }
-      }
-    }
-    form.append(fileFieldName, localFileStream); // AWS S3 POST upload requires this to be the last field
-    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}`);
-}
-
-/**
- * @param {string | Buffer | NodeJS.ReadableStream} localFileStream
- * @param {URL} parsedUri
- * @param {NotHttpUploadOptions & NetOptions} [uploadOptions]
- */
-async function uploadFileToFtp(
-  localFileStream,
-  parsedUri,
-  uploadOptions = /** @type {NotHttpUploadOptions & NetOptions} */ ({})
-) {
-  const {auth} = uploadOptions;
-  const {hostname, port, protocol, pathname} = parsedUri;
-
-  const ftpOpts = {
-    host: hostname,
-    port: !_.isUndefined(port) ? _.parseInt(port) : 21,
-  };
-  if (auth?.user && auth?.pass) {
-    ftpOpts.user = auth.user;
-    ftpOpts.pass = auth.pass;
-  }
-  log.debug(`${protocol} upload options: ${JSON.stringify(ftpOpts)}`);
-  return await new B((resolve, reject) => {
-    new Ftp(ftpOpts).put(localFileStream, pathname, (err) => {
-      if (err) {
-        reject(err);
-      } else {
-        resolve();
-      }
-    });
-  });
-}
-
-/**
- * Returns `true` if params are valid for {@linkcode uploadFileToHttp}.
- * @param {any} opts
- * @param {URL} url
- * @returns {opts is HttpUploadOptions & NetOptions}
- */
-function isHttpUploadOptions(opts, url) {
-  try {
-    const {protocol} = url;
-    return protocol === 'http:' || protocol === 'https:';
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Returns `true` if params are valid for {@linkcode uploadFileToFtp}.
- * @param {any} opts
- * @param {URL} url
- * @returns {opts is NotHttpUploadOptions & NetOptions}
- */
-function isNotHttpUploadOptions(opts, url) {
-  try {
-    const {protocol} = url;
-    return protocol === 'ftp:';
-  } catch {
-    return false;
-  }
-}
-/**
- * Uploads the given file to a remote location. HTTP(S) and FTP
- * protocols are supported.
- *
- * @param {string} localPath - The path to a file on the local storage.
- * @param {string} remoteUri - The remote URI to upload the file to.
- * @param {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} [uploadOptions]
- * @returns {Promise<void>}
- */
-async function uploadFile(
-  localPath,
-  remoteUri,
-  uploadOptions = /** @type {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} */ ({})
-) {
-  if (!(await fs.exists(localPath))) {
-    throw new Error(`'${localPath}' does not exists 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 (isNotHttpUploadOptions(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)
- *
- * @param {string} remoteUrl - The remote url
- * @param {string} dstPath - The local path to download the file to
- * @param {DownloadOptions & NetOptions} [downloadOptions]
- * @throws {Error} If download operation fails
- */
-async function downloadFile(
-  remoteUrl,
-  dstPath,
-  downloadOptions = /** @type {DownloadOptions & NetOptions} */ ({})
-) {
-  const {isMetered = true, auth, timeout = DEFAULT_TIMEOUT_MS, headers} = downloadOptions;
-
-  /**
-   * @type {import('axios').RawAxiosRequestConfig}
-   */
-  const requestOpts = {
-    url: remoteUrl,
-    responseType: 'stream',
-    timeout,
-  };
-  const axiosAuth = toAxiosAuth(auth);
-  if (axiosAuth) {
-    requestOpts.auth = axiosAuth;
-  }
-  if (_.isPlainObject(headers)) {
-    requestOpts.headers = headers;
-  }
-
-  const timer = new Timer().start();
-  let responseLength;
-  try {
-    const writer = fs.createWriteStream(dstPath);
-    const {data: responseStream, headers: responseHeaders} = await axios(requestOpts);
-    responseLength = parseInt(responseHeaders['content-length'] || '0', 10);
-    responseStream.pipe(writer);
-
-    await new B((resolve, reject) => {
-      responseStream.once('error', reject);
-      writer.once('finish', resolve);
-      writer.once('error', (e) => {
-        responseStream.unpipe(writer);
-        reject(e);
-      });
-    });
-  } catch (err) {
-    throw new Error(`Cannot download the file from ${remoteUrl}: ${err.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`);
-    }
-  }
-}
-
-export {uploadFile, downloadFile};
-
-/**
- * Common options for {@linkcode uploadFile} and {@linkcode downloadFile}.
- * @typedef NetOptions
- * @property {boolean} [isMetered=true] - Whether to log the actual download performance
- * (e.g. timings and speed)
- * @property {AuthCredentials} [auth] - Authentication credentials
- */
-
-/**
- * Specific options for {@linkcode downloadFile}.
- * @typedef DownloadOptions
- * @property {number} [timeout] - The actual request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS}
- * @property {Record<string,any>} [headers] - Request headers mapping
- */
-
-/**
- * Basic auth credentials; used by {@linkcode NetOptions}.
- * @typedef AuthCredentials
- * @property {string} user - Non-empty user name
- * @property {string} pass - Non-empty password
- */
-
-/**
- * This type is used in {@linkcode uploadFile} if the remote location uses the `ftp` protocol, and distinguishes the type from {@linkcode HttpUploadOptions}.
- * @typedef NotHttpUploadOptions
- * @property {never} headers
- * @property {never} method
- * @property {never} timeout
- * @property {never} fileFieldName
- * @property {never} formFields
- */
-
-/**
- * Specific options for {@linkcode uploadFile} if the remote location uses the `http(s)` protocol
- * @typedef HttpUploadOptions
- * @property {import('@appium/types').HTTPHeaders} [headers] - Additional request headers mapping
- * @property {import('axios').Method} [method='POST'] - The HTTP method used for file upload
- * @property {number} [timeout] - The actual request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS}
- * @property {string} [fileFieldName='file'] - The name of the form field containing the file
- * content to be uploaded. Any falsy value make the request to use non-multipart upload
- * @property {Record<string, any> | [string, any][]} [formFields] - The additional form fields
- * to be included into the upload request. This property is only considered if
- * `fileFieldName` is set
- */