@appium/base-driver 10.2.0 → 10.2.2

package/lib/basedriver/logger.ts

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

package/lib/basedriver/validation.ts

@@ -1,5 +1,5 @@
-import type { Constraint } from '@appium/types';
-import log from './logger';
+import type {Constraint} from '@appium/types';
+import {log} from './logger';
 import _ from 'lodash';
 
 export class Validator {

package/lib/constants.ts

@@ -1,5 +1,5 @@
 import {util} from '@appium/support';
-import {Protocol} from '@appium/types';
+import type {Protocol} from '@appium/types';
 
 // The default maximum length of a single log record
 // containing http request/response body

package/lib/express/crash.ts

@@ -0,0 +1,15 @@
+import {errors} from '../protocol';
+
+/**
+ * Route handler that throws {@link errors.UnknownCommandError} for testing.
+ */
+export function produceError(): never {
+  throw new errors.UnknownCommandError('Produced generic error for testing');
+}
+
+/**
+ * Route handler that throws a generic Error for testing (e.g. crash scenarios).
+ */
+export function produceCrash(): never {
+  throw new Error('We just tried to crash Appium!');
+}

package/lib/express/express-logging.ts

@@ -0,0 +1,84 @@
+import _ from 'lodash';
+import '@colors/colors';
+import morgan from 'morgan';
+import type {Request, RequestHandler, Response} from 'express';
+import {log} from './logger';
+import {MAX_LOG_BODY_LENGTH} from '../constants';
+import {logger} from '@appium/support';
+
+/**
+ * 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): void {
+  log.info(requestEndLoggingFormat(tokens, req, res));
+}
+
+function startLogFormatterHandler(tokens: unknown, req: Request, res: Response): void {
+  let reqBody = '';
+  if (req.body) {
+    try {
+      reqBody = _.truncate(
+        _.isString(req.body) ? req.body : JSON.stringify(req.body),
+        {length: MAX_LOG_BODY_LENGTH}
+      );
+    } catch {
+      // ignore
+    }
+  }
+  log.info(
+    requestStartLoggingFormat(tokens, req, res),
+    logger.markSensitive(reqBody.grey)
+  );
+}
+
+// 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 = statusStr.red;
+  } else if (status >= 400) {
+    statusStr = statusStr.yellow;
+  } else if (status >= 300) {
+    statusStr = statusStr.cyan;
+  } else {
+    statusStr = statusStr.green;
+  }
+  const fn = compile(
+    `${'<-- :method :url '.white}${statusStr} ${':response-time ms - :res[content-length]'.grey}`
+  );
+  return fn(tokens, req, res);
+}
+
+const requestStartLoggingFormat = compile(
+  `${'-->'.white} ${':method'.white} ${':url'.white}`
+);
+// #endregion

package/lib/express/{idempotency.js → idempotency.ts}

@@ -1,37 +1,99 @@
-import log from './logger';
-import { LRUCache } from 'lru-cache';
+import {log} from './logger';
+import {LRUCache} from 'lru-cache';
 import _ from 'lodash';
 import {EventEmitter} from 'node:events';
+import type {Request, Response, NextFunction} from 'express';
 
-const IDEMPOTENT_RESPONSES = new LRUCache({
+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,
-  // @ts-ignore The value must contain responseStateListener
   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
 
 /**
- * @typedef {Object} CachedResponse
- * @property {string} method
- * @property {string} path
- * @property {Buffer?} response
- * @property {EventEmitter|null|undefined} responseStateListener
+ * 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 (_.isEmpty(keyOrArr) || !keyOrArr) {
+    next();
+    return;
+  }
 
-/**
- *
- * @param {string} key
- * @param {import('express').Request} req
- * @param {import('express').Response} res
- */
-function cacheResponse(key, req, res) {
+  const key = _.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;
   }
@@ -46,28 +108,43 @@ function cacheResponse(key, req, res) {
   const socket = res.socket;
   const originalSocketWriter = socket.write.bind(socket);
   const responseRef = new WeakRef(res);
-  let responseChunks = [];
+  let responseChunks: Buffer[] = [];
   let responseSize = 0;
-  let errorMessage = null;
-  const patchedWriter = (chunk, encoding, next) => {
+  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, encoding, next);
+      return originalSocketWriter(
+        chunk as string | Buffer | Uint8Array,
+        encoding as BufferEncoding,
+        next as (err?: Error) => void
+      );
     }
 
-    const buf = Buffer.from(chunk, encoding);
+    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 ` +
+      errorMessage =
+        `The actual response size exceeds ` +
         `the maximum allowed limit of ${MAX_CACHED_PAYLOAD_SIZE_BYTES} bytes`;
     }
-    return originalSocketWriter(chunk, encoding, next);
+    return originalSocketWriter(
+      chunk as string | Buffer | Uint8Array,
+      encoding as BufferEncoding,
+      next as (err?: Error) => void
+    );
   };
-  socket.write = patchedWriter;
+  socket.write = patchedWriter as typeof socket.write;
   let didEmitReady = false;
-  res.once('error', (e) => {
+  res.once('error', (e: Error) => {
     errorMessage = e.message;
     if (socket.write === patchedWriter) {
       socket.write = originalSocketWriter;
@@ -76,7 +153,7 @@ function cacheResponse(key, req, res) {
     if (!IDEMPOTENT_RESPONSES.has(key)) {
       log.info(
         `Could not cache the response identified by '${key}'. ` +
-        `Cache consistency has been damaged`
+          `Cache consistency has been damaged`
       );
     } else {
       log.info(`Could not cache the response identified by '${key}': ${errorMessage}`);
@@ -98,15 +175,13 @@ function cacheResponse(key, req, res) {
     if (!IDEMPOTENT_RESPONSES.has(key)) {
       log.info(
         `Could not cache the response identified by '${key}'. ` +
-        `Cache consistency has been damaged`
+          `Cache consistency has been damaged`
       );
     } else if (errorMessage) {
       log.info(`Could not cache the response identified by '${key}': ${errorMessage}`);
       IDEMPOTENT_RESPONSES.delete(key);
     }
 
-    /** @type {CachedResponse|undefined} */
-    // @ts-ignore The returned type is ok
     const value = IDEMPOTENT_RESPONSES.get(key);
     if (value) {
       value.response = Buffer.concat(responseChunks);
@@ -124,68 +199,9 @@ function cacheResponse(key, req, res) {
     }
 
     if (!didEmitReady) {
-      /** @type {CachedResponse|undefined} */
-      // @ts-ignore The returned type is ok
       const value = IDEMPOTENT_RESPONSES.get(key);
       responseStateListener.emit('ready', value?.response ?? null);
       didEmitReady = true;
     }
   });
 }
-
-/**
- * @param {import('express').Request} req
- * @param {import('express').Response} res
- */
-async function handleIdempotency(req, res, next) {
-  const keyOrArr = req.headers[IDEMPOTENCY_KEY_HEADER];
-  if (_.isEmpty(keyOrArr) || !keyOrArr) {
-    return next();
-  }
-
-  const key = _.isArray(keyOrArr) ? keyOrArr[0] : keyOrArr;
-
-  log.updateAsyncContext({idempotencyKey: key});
-
-  if (!MONITORED_METHODS.includes(req.method)) {
-    // GET, DELETE, etc. requests are idempotent by default
-    // there is no need to cache them
-    return next();
-  }
-
-  log.debug(`Request idempotency key: ${key}`);
-  if (!IDEMPOTENT_RESPONSES.has(key)) {
-    cacheResponse(key, req, res);
-    return next();
-  }
-
-  const {
-    // @ts-ignore We have asserted the presence of the key above
-    method, path, response, responseStateListener,
-  } = IDEMPOTENT_RESPONSES.get(key);
-  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?');
-    return next();
-  }
-
-  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) {
-      return next();
-    }
-    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`);
-    responseStateListener.once('ready', async (/** @type {Buffer?} */ cachedResponse) => {
-      if (!cachedResponse || !res.socket?.writable) {
-        return next();
-      }
-      res.socket.write(cachedResponse.toString('utf8'));
-    });
-  }
-}
-
-export {handleIdempotency};

package/lib/express/logger.ts

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

package/lib/express/middleware.ts

@@ -0,0 +1,187 @@
+import _ from 'lodash';
+import type {NextFunction, Request, RequestHandler, Response} from 'express';
+import type {IncomingMessage} from 'node:http';
+import type {Duplex} from 'node:stream';
+import {log} from './logger';
+import {errors} from '../protocol';
+export {handleIdempotency} from './idempotency';
+import {match} from 'path-to-regexp';
+import {util} from '@appium/support';
+import {calcSignature} from '../helpers/session';
+import {getResponseForW3CError} from '../protocol/errors';
+import type {StringRecord, WSServer} from '@appium/types';
+
+const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
+
+/**
+ * Basic CORS middleware.
+ * Sets permissive CORS headers and responds immediately to `OPTIONS` requests with 200.
+ */
+export function allowCrossDomain(req: Request, res: Response, next: NextFunction): void {
+  res.header('Access-Control-Allow-Origin', '*');
+  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS, DELETE');
+  res.header(
+    'Access-Control-Allow-Headers',
+    'Cache-Control, Pragma, Origin, X-Requested-With, Content-Type, Accept, User-Agent'
+  );
+
+  if (req.method === 'OPTIONS') {
+    res.sendStatus(200);
+    return;
+  }
+  next();
+}
+
+/**
+ * CORS middleware for async execute response endpoints only.
+ * Leaves other routes untouched but applies {@link allowCrossDomain} to async response URLs.
+ *
+ * @param basePath - Server base path (e.g. `/wd/hub` or `/`)
+ * @returns Express request handler
+ */
+export function allowCrossDomainAsyncExecute(basePath: string): RequestHandler {
+  function allowCrossDomainAsyncExecuteHandler(
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): void {
+    const receiveAsyncResponseRegExp = new RegExp(
+      `${_.escapeRegExp(basePath)}/session/[a-f0-9-]+/(appium/)?receive_async_response`
+    );
+    if (!receiveAsyncResponseRegExp.test(req.url)) {
+      next();
+      return;
+    }
+    allowCrossDomain(req, res, next);
+  }
+
+  return allowCrossDomainAsyncExecuteHandler;
+}
+
+/**
+ * Populates the logger's async context with request and session metadata.
+ * Derives `requestId`, optional session id/signature, and `isSensitive` flag from headers/URL.
+ */
+export function handleLogContext(req: Request, _res: Response, next: NextFunction): void {
+  const requestId = fetchHeaderValue(req, 'x-request-id') || util.uuidV4();
+
+  const sessionId = SESSION_ID_PATTERN.exec(req.url)?.[1];
+  const sessionInfo = sessionId ? {sessionId, sessionSignature: calcSignature(sessionId)} : {};
+  const isSensitiveHeaderValue = fetchHeaderValue(req, 'x-appium-is-sensitive');
+
+  log.updateAsyncContext(
+    {
+      requestId,
+      ...sessionInfo,
+      isSensitive: ['true', '1', 'yes'].includes(_.toLower(isSensitiveHeaderValue)),
+    },
+    true
+  );
+
+  next();
+}
+
+/**
+ * Ensures requests default to JSON content-type when none is provided.
+ */
+export function defaultToJSONContentType(
+  req: Request,
+  _res: Response,
+  next: NextFunction
+): void {
+  if (!req.headers['content-type']) {
+    req.headers['content-type'] = 'application/json; charset=utf-8';
+  }
+  next();
+}
+
+/**
+ * Attempts to handle a WebSocket upgrade by matching the request path against registered handlers.
+ *
+ * @param req - Incoming HTTP request
+ * @param socket - Network socket
+ * @param head - First packet of the upgraded stream
+ * @param webSocketsMapping - Path-to-WebSocket-server mapping
+ * @returns `true` if the upgrade was handled; `false` otherwise
+ */
+export function tryHandleWebSocketUpgrade(
+  req: IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+  webSocketsMapping: StringRecord<WSServer>
+): boolean {
+  if (_.toLower(req.headers?.upgrade) !== 'websocket') {
+    return false;
+  }
+
+  let currentPathname: string;
+  try {
+    currentPathname = new URL(req.url ?? '', 'http://localhost').pathname;
+  } catch {
+    currentPathname = req.url ?? '';
+  }
+  for (const [pathname, wsServer] of _.toPairs(webSocketsMapping)) {
+    if (match(pathname)(currentPathname)) {
+      wsServer.handleUpgrade(req, socket, head, (ws) => {
+        wsServer.emit('connection', ws, req);
+      });
+      return true;
+    }
+  }
+  log.info(`Did not match the websocket upgrade request at ${currentPathname} to any known route`);
+  return false;
+}
+
+/**
+ * Express middleware wrapper around {@link tryHandleWebSocketUpgrade}.
+ * Delegates WebSocket upgrades to the mapping and falls through to `next()` otherwise.
+ *
+ * @param webSocketsMapping - Path-to-WebSocket-server mapping
+ * @returns Express request handler
+ */
+export function handleUpgrade(webSocketsMapping: StringRecord<WSServer>): RequestHandler {
+  function handleUpgradeMiddleware(req: Request, res: Response, next: NextFunction): void {
+    if (tryHandleWebSocketUpgrade(req, req.socket, Buffer.from(''), webSocketsMapping)) {
+      return;
+    }
+    next();
+  }
+
+  return handleUpgradeMiddleware;
+}
+
+/**
+ * Final error-handling middleware.
+ * Logs uncaught errors and returns a W3C-formatted error response unless headers were already sent.
+ */
+export function catchAllHandler(
+  err: Error,
+  _req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+
+  log.error(`Uncaught error: ${err.message}`);
+  const [status, body] = getResponseForW3CError(err);
+  res.status(status).json(body);
+}
+
+/**
+ * 404 handler for unmatched routes.
+ * Logs a debug message and responds with `UnknownCommandError` in W3C format.
+ */
+export function catch404Handler(req: Request, res: Response): void {
+  log.debug(`No route found for ${req.url}`);
+  const [status, body] = getResponseForW3CError(new errors.UnknownCommandError());
+  res.status(status).json(body);
+}
+
+function fetchHeaderValue(req: Request, name: string): string | undefined {
+  const value = req.headers[name];
+  return _.isArray(value) ? value[0] : (value as string | undefined);
+}
+