appium-mac2-driver 4.5.0 → 4.6.0

package/node_modules/@appium/base-driver/lib/basedriver/ipc.ts

@@ -0,0 +1,193 @@
+import EventEmitter from 'node:events';
+
+import {node} from '@appium/support';
+import type {
+  AppiumLogger,
+  IAppiumIpc,
+  IIpcSubscription,
+  IpcData,
+  IpcEvent,
+  IpcMessage,
+  StringRecord,
+} from '@appium/types';
+import {sleep} from 'asyncbox';
+
+import {log} from './logger';
+
+const DEF_MAX_OBJ_SIZE_BYTES = 1024 * 1024; // 1mb seems like plenty for any plugin to pass a message
+const DEF_MAX_TOPICS = 1000;
+
+export const EVT_MESSAGE = 'message';
+export const EVT_UNSUBSCRIBED = 'unsubscribed';
+
+export type AppiumIpcOpts = {
+  maxObjSize?: number;
+  maxTopics?: number;
+  log?: AppiumLogger;
+};
+
+const ASYNC_ITERATOR_STOP = Symbol('asyncIteratorStop');
+
+export class IpcSubscription<T extends IpcData> extends EventEmitter<IpcEvent<T>> implements IIpcSubscription<T> {
+  constructor(
+    public readonly subscriber: string,
+    public readonly topic: string,
+    private readonly ipc: AppiumIpc,
+  ) {
+    super();
+  }
+
+  get isActive() {
+    return this.ipc.subscriptionExists(this.topic, this.subscriber);
+  }
+
+  getMessage(): IpcMessage<T> | undefined {
+    if (!this.isActive) {
+      throw new Error('Cannot get message from subscription after unsubscribing');
+    }
+    return this.ipc.getMessage<T>(this.topic);
+  }
+
+  async publish(data: T): Promise<void> {
+    if (!this.isActive) {
+      throw new Error('Cannot publish data to topic from subscription after unsubscribing');
+    }
+    return await this.ipc.publish<T>(this.topic, this.subscriber, data);
+  }
+
+  unsubscribe(): boolean {
+    if (!this.isActive) {
+      return false;
+    }
+    const unsubscribeRes = this.ipc.unsubscribe(this.topic, this.subscriber);
+    this.emit('unsubscribed');
+    this.removeAllListeners(EVT_MESSAGE);
+    return unsubscribeRes;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<IpcMessage<T>> {
+    // yield any messages that are emitted, but keep an eye out for an unsubscribed that happens
+    // while a caller is waiting on the loop, because we want to exit the loop in case of
+    // unsubscription, even if we were already waiting on the next message.
+    while (this.isActive) {
+      const val = await new Promise<IpcMessage<T> | typeof ASYNC_ITERATOR_STOP>((resolve) => {
+        this.once(EVT_MESSAGE, (message: IpcMessage<T>) => {
+          this.removeAllListeners(EVT_UNSUBSCRIBED);
+          resolve(message);
+        });
+        this.once(EVT_UNSUBSCRIBED, () => {
+          // EVT_MESSAGE listeners are already removed in unsubscribe()
+          resolve(ASYNC_ITERATOR_STOP);
+        });
+      });
+      if (val === ASYNC_ITERATOR_STOP) {
+        break;
+      }
+      yield val;
+    }
+  }
+}
+
+export class AppiumIpc implements IAppiumIpc {
+  protected readonly messageByTopic: StringRecord<IpcMessage<any>> = {};
+  protected readonly subs: StringRecord<Array<IpcSubscription<any>>> = {};
+  protected readonly topics = new Set<string>();
+  protected readonly maxObjSize: number;
+  protected readonly maxTopics: number;
+  protected readonly log: AppiumLogger;
+
+  constructor(opts: AppiumIpcOpts = {}) {
+    this.maxObjSize = opts.maxObjSize ?? DEF_MAX_OBJ_SIZE_BYTES;
+    this.maxTopics = opts.maxTopics ?? DEF_MAX_TOPICS;
+    this.log = opts.log ?? log;
+    this.log.debug(
+      `Initialized new IPC object with max object size of ${this.maxObjSize} bytes ` +
+        `and max topics of ${this.maxTopics}`,
+    );
+  }
+
+  subscribe<T extends IpcData>(topic: string, subscriber: string): IpcSubscription<T> {
+    this.log.info(`Subscribing ${subscriber} to topic '${topic}'`);
+    if (this.subscriptionExists(topic, subscriber)) {
+      throw new Error(`Subscription already exists for topic "${topic}" and subscriber "${subscriber}"`);
+    }
+
+    this.ensureTopic(topic);
+    this.subs[topic] ??= [];
+    const sub = new IpcSubscription<T>(subscriber, topic, this);
+    this.subs[topic].push(sub);
+    return sub;
+  }
+
+  unsubscribe(topic: string, subscriber: string): boolean {
+    this.log.info(`Unsubscribing ${subscriber} from topic '${topic}'`);
+    if (this.subscriptionExists(topic, subscriber)) {
+      this.subs[topic] = this.subs[topic].filter((sub) => sub.subscriber !== subscriber);
+      return true;
+    }
+    return false;
+  }
+
+  async publish<T extends IpcData>(topic: string, publisher: string, data: T): Promise<void> {
+    this.log.debug(`${publisher} is publishing a message to topic ${topic}`);
+
+    this.ensureTopic(topic);
+
+    const messageSize = node.getObjectSize(data);
+    if (messageSize > this.maxObjSize) {
+      throw new Error(
+        `Error when ${publisher} is publishing to topic '${topic}': ` +
+          `Message with size ${messageSize} bytes is bigger than max size of ${this.maxObjSize} bytes`,
+      );
+    }
+
+    let clonedData: T;
+    try {
+      clonedData = structuredClone(data);
+    } catch (e) {
+      throw new Error(`Could not clone data for IPC publish from ${publisher} on topic ${topic}`, {
+        cause: e,
+      });
+    }
+
+    const message: IpcMessage<T> = {publisher, data: clonedData, topic, timestampMs: Date.now()};
+
+    this.messageByTopic[topic] = message;
+
+    const subs = this.subs[topic] ? this.subs[topic].filter((sub) => sub.subscriber !== publisher) : [];
+
+    for (const sub of subs) {
+      sub.emit(EVT_MESSAGE, structuredClone(message));
+    }
+
+    // we don't want to return from publish until the async iterators on subscriptions have had
+    // a chance to observe the emitted value, otherwise some might get lost
+    await sleep(0);
+  }
+
+  getMessage<T extends IpcData>(topic: string): IpcMessage<T> | undefined {
+    if (!this.messageByTopic[topic]) {
+      return;
+    }
+
+    return structuredClone(this.messageByTopic[topic] as IpcMessage<T>);
+  }
+
+  subscriptionExists(topic: string, subscriber: string): boolean {
+    return !!this.subs[topic]?.some((sub) => sub.subscriber === subscriber);
+  }
+
+  protected ensureTopic(topic: string): void {
+    if (this.topics.has(topic)) {
+      return;
+    }
+    if (this.topics.size >= this.maxTopics) {
+      throw new Error(
+        `Cannot create new IPC topic '${topic}': ` +
+          `maximum of ${this.maxTopics} topics per session reached. ` +
+          `Adjust with the --max-ipc-topics server arg.`,
+      );
+    }
+    this.topics.add(topic);
+  }
+}

package/node_modules/@appium/base-driver/lib/basedriver/logger.ts

@@ -0,0 +1,3 @@
+import {logger} from '@appium/support';
+
+export const log = logger.getLogger('BaseDriver');

package/node_modules/@appium/base-driver/lib/basedriver/validation.ts

@@ -0,0 +1,142 @@
+import {util} from '@appium/support';
+import type {Constraint} from '@appium/types';
+
+import {log} from './logger';
+
+export class Validator {
+  private readonly _validators: Record<keyof Constraint, (value: any, options?: any, key?: string) => string | null> = {
+    isString: (value: any, options?: any): string | null => {
+      if (value === undefined || options == null) {
+        return null;
+      }
+
+      if (typeof value === 'string') {
+        return options ? null : 'must not be of type string';
+      }
+
+      return options ? 'must be of type string' : null;
+    },
+    isNumber: (value: any, options?: any): string | null => {
+      if (value === undefined || options == null) {
+        return null;
+      }
+
+      if (typeof value === 'number') {
+        return options ? null : 'must not be of type number';
+      }
+
+      // allow a string value
+      if (options && typeof value === 'string' && !isNaN(Number(value))) {
+        log.warn('Number capability passed in as string. Functionality may be compromised.');
+        return null;
+      }
+
+      return options ? 'must be of type number' : null;
+    },
+    isBoolean: (value: any, options?: any): string | null => {
+      if (value === undefined || options == null) {
+        return null;
+      }
+
+      if (typeof value === 'boolean') {
+        return options ? null : 'must not be of type boolean';
+      }
+
+      // allow a string value
+      if (options && typeof value === 'string' && ['true', 'false', ''].includes(value)) {
+        return null;
+      }
+
+      return options ? 'must be of type boolean' : null;
+    },
+    isObject: (value: any, options?: any): string | null => {
+      if (value === undefined || options == null) {
+        return null;
+      }
+
+      if (util.isPlainObject(value)) {
+        return options ? null : 'must not be a plain object';
+      }
+
+      return options ? 'must be a plain object' : null;
+    },
+    isArray: (value: any, options?: any): string | null => {
+      if (value === undefined || options == null) {
+        return null;
+      }
+
+      if (Array.isArray(value)) {
+        return options ? null : 'must not be of type array';
+      }
+
+      return options ? 'must be of type array' : null;
+    },
+    deprecated: (value: any, options?: any, key?: string): string | null => {
+      if (value !== undefined && options) {
+        log.warn(
+          `The '${key}' capability has been deprecated and must not be used anymore. ` +
+            `Please check the driver documentation for possible alternatives.`,
+        );
+      }
+      return null;
+    },
+    inclusion: (value: any, options?: any): string | null => {
+      if (value === undefined || !options) {
+        return null;
+      }
+      const optionsArr = Array.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => opt === value)) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    inclusionCaseInsensitive: (value: any, options?: any): string | null => {
+      if (value === undefined || !options) {
+        return null;
+      }
+      const optionsArr = Array.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => String(opt).toLowerCase() === String(value).toLowerCase())) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    presence: (value: any, options?: any): string | null => {
+      if (value === undefined && options) {
+        return 'is required to be present';
+      }
+      if (
+        !options?.allowEmpty &&
+        ((value !== undefined && util.isEmpty(value)) || (typeof value === 'string' && !value.trim()))
+      ) {
+        return 'must not be empty or blank';
+      }
+      return null;
+    },
+  };
+
+  validate(values: Record<string, any>, constraints: Record<string, Constraint>): Record<string, string[]> | null {
+    const result: Record<string, string[]> = {};
+    for (const [key, constraint] of Object.entries(constraints)) {
+      const value = values[key];
+      for (const [validatorName, options] of Object.entries(constraint)) {
+        if (!(validatorName in this._validators)) {
+          continue;
+        }
+
+        const validationError = this._validators[validatorName as keyof Constraint](value, options, key);
+        if (validationError == null) {
+          continue;
+        }
+
+        if (key in result) {
+          result[key].push(validationError);
+        } else {
+          result[key] = [validationError];
+        }
+      }
+    }
+    return util.isEmpty(result) ? null : result;
+  }
+}
+
+export const validator = new Validator();

package/node_modules/@appium/base-driver/lib/constants.ts

@@ -0,0 +1,19 @@
+import {util} from '@appium/support';
+import type {Protocol} from '@appium/types';
+
+// The default maximum length of a single log record
+// containing http request/response body
+// This value could be globally customized using the --log-filters
+// server feature. Example rule:
+// 	{"pattern": "(.{1,150}).*", "flags": "s", "replacer": "$1"}
+// ^ cuts all log records to maximum 150 chars
+export const MAX_LOG_BODY_LENGTH = 1024;
+export const MJSONWP_ELEMENT_KEY = 'ELEMENT';
+export const W3C_ELEMENT_KEY = util.W3C_WEB_ELEMENT_IDENTIFIER;
+export const PROTOCOLS = {
+  W3C: 'W3C',
+  MJSONWP: 'MJSONWP',
+} as const satisfies Record<Protocol, Protocol>;
+
+// Before Appium 2.0, this default value was '/wd/hub' by historical reasons.
+export const DEFAULT_BASE_PATH = '';

package/node_modules/@appium/base-driver/lib/express/express-logging.ts

@@ -0,0 +1,80 @@
+import {console, logger, util} from '@appium/support';
+import type {Request, RequestHandler, Response} from 'express';
+import morgan from 'morgan';
+
+import {MAX_LOG_BODY_LENGTH} from '../constants';
+import {log} from './logger';
+
+/**
+ * Morgan middleware that logs when the HTTP response finishes.
+ * Logs method, URL, status (color-coded), response time, and content-length.
+ */
+export const endLogFormatter: RequestHandler = morgan(endLogFormatterHandler);
+
+/**
+ * Morgan middleware that logs when the HTTP request is received (immediate).
+ * Logs method and URL; request body is truncated and passed through {@link logger.markSensitive}.
+ */
+export const startLogFormatter: RequestHandler = morgan(startLogFormatterHandler, {
+  immediate: true,
+});
+
+// #region Private types and helpers
+type MorganTokens = unknown;
+type FormatFn = (tokens: MorganTokens, req: Request, res: Response) => string;
+
+function endLogFormatterHandler(tokens: MorganTokens, req: Request, res: Response): undefined {
+  log.info(requestEndLoggingFormat(tokens, req, res));
+  return undefined;
+}
+
+function startLogFormatterHandler(tokens: unknown, req: Request, res: Response): undefined {
+  let reqBody = '';
+  if (req.body) {
+    try {
+      reqBody = util.truncateString(typeof req.body === 'string' ? req.body : JSON.stringify(req.body), {
+        length: MAX_LOG_BODY_LENGTH,
+      });
+    } catch {
+      // ignore
+    }
+  }
+  log.info(requestStartLoggingFormat(tokens, req, res), logger.markSensitive(console.styleText('grey', reqBody)));
+  return undefined;
+}
+
+// Copied the morgan compile function over so that cooler formats may be configured
+function compile(fmt: string): FormatFn {
+  fmt = fmt.replace(/"/g, '\\"');
+  fmt = fmt.replace(/:([-\w]{2,})(?:\[([^\]]+)\])?/g, function replace(_, name, arg) {
+    return `"\n    + (tokens["${name}"](req, res, "${arg}") || "-") + "`;
+  });
+  const js = `  return "${fmt}";`;
+  return new Function('tokens', 'req', 'res', js) as FormatFn;
+}
+
+function requestEndLoggingFormat(tokens: MorganTokens, req: Request, res: Response): string {
+  const status = res.statusCode;
+  let statusStr = ':status';
+  if (status >= 500) {
+    statusStr = console.styleText('red', statusStr);
+  } else if (status >= 400) {
+    statusStr = console.styleText('yellow', statusStr);
+  } else if (status >= 300) {
+    statusStr = console.styleText('cyan', statusStr);
+  } else {
+    statusStr = console.styleText('green', statusStr);
+  }
+  const fn = compile(
+    `${console.styleText('white', '<-- :method :url ')}${statusStr} ${console.styleText(
+      'grey',
+      ':response-time ms - :res[content-length]',
+    )}`,
+  );
+  return fn(tokens, req, res);
+}
+
+const requestStartLoggingFormat = compile(
+  `${console.styleText('white', '-->')} ${console.styleText('white', ':method')} ${console.styleText('white', ':url')}`,
+);
+// #endregion

package/node_modules/@appium/base-driver/lib/express/idempotency.ts

@@ -0,0 +1,198 @@
+import {EventEmitter} from 'node:events';
+
+import {util} from '@appium/support';
+import type {NextFunction, Request, Response} from 'express';
+import {LRUCache} from 'lru-cache';
+
+import {log} from './logger';
+
+interface CachedResponse {
+  method: string;
+  path: string;
+  response: Buffer | null;
+  responseStateListener: EventEmitter | null | undefined;
+}
+
+const IDEMPOTENT_RESPONSES = new LRUCache<string, CachedResponse>({
+  max: 64,
+  ttl: 30 * 60 * 1000,
+  updateAgeOnGet: true,
+  updateAgeOnHas: true,
+  dispose: ({responseStateListener}) => {
+    responseStateListener?.removeAllListeners();
+  },
+});
+const MONITORED_METHODS = ['POST', 'PATCH'];
+const IDEMPOTENCY_KEY_HEADER = 'x-idempotency-key';
+const MAX_CACHED_PAYLOAD_SIZE_BYTES = 1 * 1024 * 1024; // 1 MiB
+
+/**
+ * Middleware that caches and replays responses for idempotent requests using the
+ * `x-idempotency-key` header. Only POST and PATCH are cached.
+ */
+export async function handleIdempotency(req: Request, res: Response, next: NextFunction): Promise<void> {
+  const keyOrArr = req.headers[IDEMPOTENCY_KEY_HEADER];
+  if (util.isEmpty(keyOrArr) || !keyOrArr) {
+    next();
+    return;
+  }
+
+  const key = Array.isArray(keyOrArr) ? keyOrArr[0] : keyOrArr;
+
+  log.updateAsyncContext({idempotencyKey: key});
+
+  if (!MONITORED_METHODS.includes(req.method)) {
+    next();
+    return;
+  }
+
+  log.debug(`Request idempotency key: ${key}`);
+  if (!IDEMPOTENT_RESPONSES.has(key)) {
+    cacheResponse(key, req, res);
+    next();
+    return;
+  }
+
+  const cached = IDEMPOTENT_RESPONSES.get(key);
+  if (!cached) {
+    next();
+    return;
+  }
+  const {method, path, response, responseStateListener} = cached;
+  if (req.method !== method || req.path !== path) {
+    log.warn(`Got two different requests with the same idempotency key '${key}'`);
+    log.warn('Is the client generating idempotency keys properly?');
+    next();
+    return;
+  }
+
+  if (response) {
+    log.info(`The same request with the idempotency key '${key}' has been already processed`);
+    log.info(`Rerouting its response to the current request`);
+    if (!res.socket?.writable) {
+      next();
+      return;
+    }
+    res.socket.write(response.toString('utf8'));
+  } else {
+    log.info(`The same request with the idempotency key '${key}' is being processed`);
+    log.info(`Waiting for the response to be rerouted to the current request`);
+    if (!responseStateListener) {
+      next();
+      return;
+    }
+    responseStateListener.once('ready', (cachedResponse: Buffer | null) => {
+      if (!cachedResponse || !res.socket?.writable) {
+        next();
+        return;
+      }
+      res.socket.write(cachedResponse.toString('utf8'));
+    });
+  }
+}
+
+function cacheResponse(key: string, req: Request, res: Response): void {
+  if (!res.socket) {
+    return;
+  }
+
+  const responseStateListener = new EventEmitter();
+  IDEMPOTENT_RESPONSES.set(key, {
+    method: req.method,
+    path: req.path,
+    response: null,
+    responseStateListener,
+  });
+  const socket = res.socket;
+  const originalSocketWriter = socket.write.bind(socket);
+  const responseRef = new WeakRef(res);
+  let responseChunks: Buffer[] = [];
+  let responseSize = 0;
+  let errorMessage: string | null = null;
+  const patchedWriter = (
+    chunk: unknown,
+    encoding: BufferEncoding | (() => void),
+    next?: (() => void) | ((err?: Error) => void),
+  ): boolean => {
+    if (errorMessage || !responseRef.deref()) {
+      responseChunks = [];
+      responseSize = 0;
+      return originalSocketWriter(
+        chunk as string | Buffer | Uint8Array,
+        encoding as BufferEncoding,
+        next as (err?: Error | null) => void,
+      );
+    }
+
+    const buf = Buffer.isBuffer(chunk)
+      ? chunk
+      : Buffer.from(chunk as string, typeof encoding === 'string' ? encoding : undefined);
+    responseChunks.push(buf);
+    responseSize += buf.length;
+    if (responseSize > MAX_CACHED_PAYLOAD_SIZE_BYTES) {
+      errorMessage =
+        `The actual response size exceeds ` + `the maximum allowed limit of ${MAX_CACHED_PAYLOAD_SIZE_BYTES} bytes`;
+    }
+    return originalSocketWriter(
+      chunk as string | Buffer | Uint8Array,
+      encoding as BufferEncoding,
+      next as (err?: Error | null) => void,
+    );
+  };
+  socket.write = patchedWriter as typeof socket.write;
+  let didEmitReady = false;
+  res.once('error', (e: Error) => {
+    errorMessage = e.message;
+    if (socket.write === patchedWriter) {
+      socket.write = originalSocketWriter;
+    }
+
+    if (!IDEMPOTENT_RESPONSES.has(key)) {
+      log.info(`Could not cache the response identified by '${key}'. ` + `Cache consistency has been damaged`);
+    } else {
+      log.info(`Could not cache the response identified by '${key}': ${errorMessage}`);
+      IDEMPOTENT_RESPONSES.delete(key);
+    }
+
+    responseChunks = [];
+    responseSize = 0;
+    if (!didEmitReady) {
+      responseStateListener.emit('ready', null);
+      didEmitReady = true;
+    }
+  });
+  res.once('finish', () => {
+    if (socket.write === patchedWriter) {
+      socket.write = originalSocketWriter;
+    }
+
+    if (!IDEMPOTENT_RESPONSES.has(key)) {
+      log.info(`Could not cache the response identified by '${key}'. ` + `Cache consistency has been damaged`);
+    } else if (errorMessage) {
+      log.info(`Could not cache the response identified by '${key}': ${errorMessage}`);
+      IDEMPOTENT_RESPONSES.delete(key);
+    }
+
+    const value = IDEMPOTENT_RESPONSES.get(key);
+    if (value) {
+      value.response = Buffer.concat(responseChunks);
+    }
+    responseChunks = [];
+    responseSize = 0;
+    if (!didEmitReady) {
+      responseStateListener.emit('ready', value?.response ?? null);
+      didEmitReady = true;
+    }
+  });
+  res.once('close', () => {
+    if (socket.write === patchedWriter) {
+      socket.write = originalSocketWriter;
+    }
+
+    if (!didEmitReady) {
+      const value = IDEMPOTENT_RESPONSES.get(key);
+      responseStateListener.emit('ready', value?.response ?? null);
+      didEmitReady = true;
+    }
+  });
+}

package/node_modules/@appium/base-driver/lib/express/logger.ts

@@ -0,0 +1,3 @@
+import {logger} from '@appium/support';
+
+export const log = logger.getLogger('HTTP');