appium-mac2-driver 4.5.1 → 4.6.0

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

@@ -0,0 +1,207 @@
+import type {IncomingMessage} from 'node:http';
+import type {Duplex} from 'node:stream';
+
+import {util} from '@appium/support';
+import type {NextFunction, Request, RequestHandler, Response} from 'express';
+
+import {errors} from '../protocol';
+import {log} from './logger';
+export {handleIdempotency} from './idempotency';
+import type {StringRecord, WSServer} from '@appium/types';
+import {match} from 'path-to-regexp';
+
+import {calcSignature} from '../helpers/session';
+import {getResponseForW3CError} from '../protocol/errors';
+
+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(
+      `^${util.escapeRegExp(basePath)}/session/[a-f0-9-]+/(appium/)?receive_async_response/?$`,
+    );
+    // Match against req.path (query-stripped) so query-string data cannot be used
+    // to smuggle a match for an otherwise unrelated endpoint.
+    if (!receiveAsyncResponseRegExp.test(req.path)) {
+      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.path)?.[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(String(isSensitiveHeaderValue ?? '').toLowerCase()),
+    },
+    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();
+}
+
+/** Options for {@linkcode tryHandleWebSocketUpgrade} */
+export interface WebSocketUpgradeOpts {
+  /** Incoming HTTP request */
+  req: IncomingMessage;
+  /** Network socket */
+  socket: Duplex;
+  /** First packet of the upgraded stream */
+  head: Buffer;
+  /** Path-to-WebSocket-server mapping */
+  webSocketsMapping: StringRecord<WSServer>;
+  /** Whether upgrades carrying an `Origin` header are accepted */
+  allowCors?: boolean;
+}
+
+/**
+ * Attempts to handle a WebSocket upgrade by matching the request path against registered handlers.
+ *
+ * @param opts - Upgrade options
+ * @returns `true` if the upgrade was handled; `false` otherwise
+ */
+export function tryHandleWebSocketUpgrade({
+  req,
+  socket,
+  head,
+  webSocketsMapping,
+  allowCors = false,
+}: WebSocketUpgradeOpts): boolean {
+  if (String(req.headers?.upgrade ?? '').toLowerCase() !== 'websocket') {
+    return false;
+  }
+
+  // WebSocket handshakes are not subject to the Same-Origin Policy; browsers always send Origin
+  if (!allowCors && req.headers.origin !== undefined) {
+    log.warn(`Rejecting the WebSocket upgrade from the browser origin '${req.headers.origin}'`);
+    socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+    return true;
+  }
+
+  let currentPathname: string;
+  try {
+    currentPathname = new URL(req.url ?? '', 'http://localhost').pathname;
+  } catch {
+    currentPathname = req.url ?? '';
+  }
+  for (const [pathname, wsServer] of Object.entries(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
+ * @param allowCors - Whether upgrades carrying an `Origin` header are accepted
+ * @returns Express request handler
+ */
+export function handleUpgrade(webSocketsMapping: StringRecord<WSServer>, allowCors = false): RequestHandler {
+  function handleUpgradeMiddleware(req: Request, res: Response, next: NextFunction): void {
+    if (tryHandleWebSocketUpgrade({req, socket: req.socket, head: Buffer.from(''), webSocketsMapping, allowCors})) {
+      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(
+    isBodyParseError(err) ? new errors.InvalidArgumentError(err.message) : err,
+  );
+  res.status(status).json(body);
+}
+
+/**
+ * Detects the error body-parser raises for a request body that is not valid JSON.
+ * The protocol expects such a request to be rejected as an invalid argument.
+ */
+function isBodyParseError(err: Error): boolean {
+  return (err as Error & {type?: string})?.type === 'entity.parse.failed';
+}
+
+/**
+ * 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 Array.isArray(value) ? value[0] : (value as string | undefined);
+}

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

@@ -0,0 +1,443 @@
+import http from 'node:http';
+import type {Server as HttpServer} from 'node:http';
+import {createRequire} from 'node:module';
+
+// Import env helper directly — not from the test-pages barrel — so Express handlers and
+// fixture code stay unloaded unless APPIUM_ENABLE_LEGACY_TEST_PAGES is set.
+import {fs, timing} from '@appium/support';
+import type {
+  AppiumServer,
+  ExternalDriver,
+  MethodMap,
+  ServerArgs,
+  StringRecord,
+  UpdateServerCallback,
+} from '@appium/types';
+import bodyParser from 'body-parser';
+import express from 'express';
+import type {Express, RequestHandler, Router} from 'express';
+import methodOverride from 'method-override';
+
+import {DEFAULT_BASE_PATH} from '../constants';
+import {isLegacyTestPagesEnabled} from '../test-pages/env';
+import {endLogFormatter, startLogFormatter} from './express-logging';
+import {log} from './logger';
+import {
+  allowCrossDomain,
+  allowCrossDomainAsyncExecute,
+  catch404Handler,
+  catchAllHandler,
+  defaultToJSONContentType,
+  handleIdempotency,
+  handleLogContext,
+  handleUpgrade,
+  tryHandleWebSocketUpgrade,
+} from './middleware';
+import {
+  addWebSocketHandler,
+  getWebSocketHandlers,
+  removeAllWebSocketHandlers,
+  removeWebSocketHandler,
+} from './websocket';
+
+const KEEP_ALIVE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+/** Options for {@linkcode RouteConfiguringFunction} */
+export interface RouteConfiguringFunctionOpts {
+  basePath?: string;
+  extraMethodMap?: MethodMap<ExternalDriver>;
+}
+
+/** A function which configures routes */
+export type RouteConfiguringFunction = (app: Express, opts?: RouteConfiguringFunctionOpts) => void;
+
+/** Options for {@linkcode server} */
+export interface ServerOpts {
+  routeConfiguringFunction: RouteConfiguringFunction;
+  port: number;
+  cliArgs?: Partial<ServerArgs>;
+  hostname?: string;
+  allowCors?: boolean;
+  basePath?: string;
+  extraMethodMap?: MethodMap<ExternalDriver>;
+  serverUpdaters?: UpdateServerCallback[];
+  keepAliveTimeout?: number;
+  requestTimeout?: number;
+}
+
+/** Options for {@linkcode configureServer} */
+export interface ConfigureServerOpts {
+  app: Express;
+  addRoutes: RouteConfiguringFunction;
+  allowCors?: boolean;
+  basePath?: string;
+  extraMethodMap?: MethodMap<ExternalDriver>;
+  webSocketsMapping?: StringRecord;
+  useLegacyUpgradeHandler?: boolean;
+  /** Router mounted before any route is registered; see {@linkcode AppiumServer.frontRouter}. */
+  frontRouter: Router;
+}
+
+/** @internal */
+export interface ConfigureServerInternalOpts extends ConfigureServerOpts {
+  /** @deprecated Appium 4 */
+  registerTestPages?: (app: Express, opts: {basePath: string}) => void;
+}
+
+/** Options for {@linkcode configureHttp} */
+export interface ConfigureHttpOpts {
+  httpServer: HttpServer;
+  reject: (error?: unknown) => void;
+  allowCors?: boolean;
+  keepAliveTimeout: number;
+  gracefulShutdownTimeout?: number;
+}
+
+/** Options for {@linkcode startServer} */
+export interface StartServerOpts {
+  httpServer: HttpServer;
+  port: number;
+  hostname?: string;
+  keepAliveTimeout: number;
+  requestTimeout?: number;
+}
+
+/**
+ * @param opts - Server options
+ * @returns Promise resolving to the Appium server instance
+ */
+export async function server(opts: ServerOpts): Promise<AppiumServer> {
+  const {
+    routeConfiguringFunction,
+    port,
+    hostname,
+    cliArgs = {},
+    allowCors = true,
+    basePath = DEFAULT_BASE_PATH,
+    extraMethodMap = {},
+    serverUpdaters = [],
+    keepAliveTimeout = KEEP_ALIVE_TIMEOUT_MS,
+    requestTimeout,
+  } = opts;
+
+  const app = express();
+  const httpServer = await createServer(app, cliArgs);
+
+  return await new Promise<AppiumServer>((resolve, reject) => {
+    // we use a promise here because some elements of server start failure only happen in
+    // httpServer listeners. The async IIFE runs setup serially (e.g. plugin updates) while
+    // configureHttp can still reject via the listener registered below.
+    void (async () => {
+      try {
+        const appiumServer = configureHttp({
+          httpServer,
+          reject,
+          allowCors,
+          keepAliveTimeout,
+          gracefulShutdownTimeout: cliArgs.shutdownTimeout,
+        });
+        const useLegacyUpgradeHandler = !hasShouldUpgradeCallback(httpServer);
+        let registerTestPages: ConfigureServerInternalOpts['registerTestPages'];
+        if (isLegacyTestPagesEnabled()) {
+          const require = createRequire(__filename);
+          registerTestPages = require('../test-pages').registerTestPages;
+        }
+        configureServer({
+          app,
+          addRoutes: routeConfiguringFunction,
+          allowCors,
+          basePath,
+          extraMethodMap,
+          webSocketsMapping: appiumServer.webSocketsMapping,
+          useLegacyUpgradeHandler,
+          registerTestPages,
+          frontRouter: appiumServer.frontRouter,
+        } as ConfigureServerInternalOpts);
+        // allow extensions to update the app and http server objects
+        for (const updater of serverUpdaters) {
+          await updater(app, appiumServer, cliArgs);
+        }
+
+        // once all configurations and updaters have been applied, make sure to set up a catchall
+        // handler so that anything unknown 404s. But do this after everything else since we don't
+        // want to block extensions' ability to add routes if they want.
+        app.all('/*all', catch404Handler);
+
+        await startServer({
+          httpServer,
+          hostname,
+          port,
+          keepAliveTimeout,
+          requestTimeout,
+        });
+
+        resolve(appiumServer);
+      } catch (err) {
+        reject(err);
+      }
+    })();
+  });
+}
+
+/**
+ * Sets up Express middleware and routes.
+ *
+ * @param opts - Configuration options
+ */
+export function configureServer(opts: ConfigureServerOpts): void {
+  const {
+    app,
+    addRoutes,
+    allowCors = true,
+    basePath: rawBasePath = DEFAULT_BASE_PATH,
+    extraMethodMap = {},
+    webSocketsMapping = {},
+    useLegacyUpgradeHandler = true,
+    frontRouter,
+  } = opts;
+  const {registerTestPages} = opts as ConfigureServerInternalOpts;
+  const basePath = normalizeBasePath(rawBasePath);
+
+  app.use(endLogFormatter);
+  app.use(handleLogContext);
+
+  if (registerTestPages) {
+    registerTestPages(app, {basePath});
+  }
+
+  // Only use legacy Express middleware for WebSocket upgrades if shouldUpgradeCallback is not available.
+  // When shouldUpgradeCallback is available, upgrades are handled directly on the HTTP server
+  // to avoid Express middleware timeout issues with long-lived connections
+  if (useLegacyUpgradeHandler) {
+    app.use(handleUpgrade(webSocketsMapping, allowCors));
+  }
+  if (allowCors) {
+    app.use(allowCrossDomain);
+  } else {
+    app.use(allowCrossDomainAsyncExecute(basePath));
+  }
+  app.use(handleIdempotency);
+  app.use(defaultToJSONContentType);
+  app.use(bodyParser.urlencoded({extended: true}));
+  app.use(methodOverride());
+
+  // make sure appium never fails because of a file size upload limit
+  app.use(bodyParser.json({limit: '1gb'}));
+
+  // set up start logging (which depends on bodyParser doing its thing)
+  app.use(startLogFormatter);
+
+  // mounted before any route, so middleware added later (e.g. via `updateServer`) still runs first
+  app.use(frontRouter);
+
+  addRoutes(app, {basePath, extraMethodMap});
+
+  // Express only passes errors to an error handler registered after the middleware
+  // that raised them, so this one must be the last of all.
+  app.use(catchAllHandler);
+}
+
+/**
+ * Normalize base path string (leading slash, no trailing slash).
+ *
+ * @param basePath - Raw base path
+ * @returns Normalized base path
+ */
+export function normalizeBasePath(basePath: string): string {
+  if (typeof basePath !== 'string') {
+    throw new Error(`Invalid path prefix ${basePath}`);
+  }
+
+  // ensure the path prefix does not end in '/', since our method map starts all paths with '/'
+  basePath = basePath.replace(/\/$/, '');
+
+  // likewise, ensure the path prefix does always START with /, unless the path
+  // is empty meaning no base path at all
+  if (basePath !== '' && !basePath.startsWith('/')) {
+    basePath = `/${basePath}`;
+  }
+
+  return basePath;
+}
+
+async function createServer(app: Express, cliArgs?: Partial<ServerArgs>): Promise<HttpServer> {
+  const {sslCertificatePath, sslKeyPath} = cliArgs ?? {};
+  if (!sslCertificatePath && !sslKeyPath) {
+    return http.createServer(app);
+  }
+  if (!sslCertificatePath || !sslKeyPath) {
+    throw new Error(`Both certificate path and key path must be provided to enable TLS`);
+  }
+
+  const certKey = [sslCertificatePath, sslKeyPath];
+  const [certExists, keyExists] = await Promise.all(certKey.map((p) => fs.exists(p)));
+  for (const [exists, desc, p] of [
+    [certExists, 'certificate', sslCertificatePath],
+    [keyExists, 'key', sslKeyPath],
+  ]) {
+    if (!exists) {
+      throw new Error(`The provided SSL ${desc} at '${p}' does not exist or is not accessible`);
+    }
+  }
+  const [cert, key] = (await Promise.all(certKey.map((p) => fs.readFile(p, 'utf8')))) as [string, string];
+  log.debug('Enabling TLS/SPDY on the server using the provided certificate');
+
+  const spdy = require('spdy') as {
+    createServer: (
+      options: {cert: string; key: string; spdy: {plain: boolean; ssl: boolean}},
+      requestListener: RequestHandler,
+    ) => HttpServer;
+  };
+  return spdy.createServer(
+    {
+      cert,
+      key,
+      spdy: {
+        plain: false,
+        ssl: true,
+      },
+    },
+    app,
+  );
+}
+
+/**
+ * Attaches Appium-specific behavior to the HTTP server and returns it as {@linkcode AppiumServer}.
+ * Mutates the `httpServer` parameter.
+ *
+ * @param opts - Configuration options
+ * @returns The same server instance typed as AppiumServer
+ */
+function configureHttp({
+  httpServer,
+  reject,
+  allowCors,
+  keepAliveTimeout,
+  gracefulShutdownTimeout,
+}: ConfigureHttpOpts): AppiumServer {
+  const appiumServer = httpServer as unknown as AppiumServer;
+  appiumServer.webSocketsMapping = {};
+  appiumServer.frontRouter = express.Router();
+  appiumServer.addWebSocketHandler = addWebSocketHandler;
+  appiumServer.removeWebSocketHandler = removeWebSocketHandler;
+  appiumServer.removeAllWebSocketHandlers = removeAllWebSocketHandlers;
+  appiumServer.getWebSocketHandlers = getWebSocketHandlers;
+  appiumServer.isSecure = function isSecure() {
+    return Boolean((this as unknown as {_spdyState?: {secure?: boolean}})._spdyState?.secure);
+  };
+
+  // This avoids Express middleware timeout issues with long-lived WebSocket connections
+  // See: https://github.com/appium/appium/issues/20760
+  // See: https://github.com/nodejs/node/pull/59824
+  if (hasShouldUpgradeCallback(httpServer)) {
+    // shouldUpgradeCallback only returns a boolean to indicate if the upgrade should proceed
+    (
+      appiumServer as unknown as {shouldUpgradeCallback?: (req: http.IncomingMessage) => boolean}
+    ).shouldUpgradeCallback = (req) => String(req.headers?.upgrade ?? '').toLowerCase() === 'websocket';
+    appiumServer.on('upgrade', (req, socket, head) => {
+      if (
+        !tryHandleWebSocketUpgrade({req, socket, head, webSocketsMapping: appiumServer.webSocketsMapping, allowCors})
+      ) {
+        socket.destroy();
+      }
+    });
+  }
+
+  // http.Server.close() only stops new connections, but we need to wait until
+  // all connections are closed and the `close` event is emitted
+  const originalClose = appiumServer.close.bind(appiumServer) as (callback?: (err?: Error | null) => void) => void;
+  appiumServer.close = async () =>
+    await new Promise<void>((_resolve, _reject) => {
+      log.info('Closing Appium HTTP server');
+      const timer = new timing.Timer().start();
+      const onTimeout = setTimeout(() => {
+        if ((gracefulShutdownTimeout ?? 0) > 0) {
+          log.info(
+            `Not all active connections have been closed within ${gracefulShutdownTimeout}ms. ` +
+              `This timeout might be customized by the --shutdown-timeout command line ` +
+              `argument. Closing the server anyway.`,
+          );
+        }
+        process.exit(process.exitCode ?? 0);
+      }, gracefulShutdownTimeout ?? 0);
+      const onClose = () => {
+        log.info(
+          `Appium HTTP server has been successfully closed after ` +
+            `${timer.getDuration().asMilliSeconds.toFixed(0)}ms`,
+        );
+        clearTimeout(onTimeout);
+        _resolve();
+      };
+      httpServer.once('close', onClose);
+      originalClose((err?: Error | null) => {
+        if (err) {
+          clearTimeout(onTimeout);
+          httpServer.removeListener('close', onClose);
+          _reject(err);
+        }
+      });
+    });
+
+  appiumServer.once('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRNOTAVAIL') {
+      log.error('Could not start REST http interface listener. ' + 'Requested address is not available.');
+    } else {
+      log.error(
+        'Could not start REST http interface listener. The requested ' +
+          'port may already be in use. Please make sure there is no ' +
+          'other instance of this server running already.',
+      );
+    }
+    reject(err);
+  });
+
+  appiumServer.on('connection', (socket) => socket.setTimeout(keepAliveTimeout));
+
+  return appiumServer;
+}
+
+async function startServer({
+  httpServer,
+  port,
+  hostname,
+  keepAliveTimeout,
+  requestTimeout,
+}: StartServerOpts): Promise<void> {
+  // If the hostname is omitted, the server will accept connections on any IP address
+  const startPromise = new Promise<void>((resolve, reject) => {
+    const onError = (err: Error) => {
+      httpServer.removeListener('listening', onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      httpServer.removeListener('error', onError);
+      resolve();
+    };
+    httpServer.once('error', onError);
+    httpServer.once('listening', onListening);
+    httpServer.listen(port, hostname);
+  });
+  httpServer.keepAliveTimeout = keepAliveTimeout;
+  if (Number.isInteger(requestTimeout)) {
+    httpServer.requestTimeout = Number(requestTimeout);
+  }
+  // headers timeout must be greater than keepAliveTimeout
+  httpServer.headersTimeout = keepAliveTimeout + 5 * 1000;
+  await startPromise;
+}
+
+/**
+ * Checks if the server supports `shouldUpgradeCallback` (Node.js v22.21.0+ / v24.9.0+).
+ *
+ * @param server - The HTTP server instance
+ * @returns true if shouldUpgradeCallback is available
+ */
+function hasShouldUpgradeCallback(server: HttpServer): boolean {
+  // Check if shouldUpgradeCallback is available on http.Server
+  // This is a runtime check that works regardless of TypeScript types
+  try {
+    return typeof (server as unknown as {shouldUpgradeCallback?: unknown}).shouldUpgradeCallback !== 'undefined';
+  } catch {
+    return false;
+  }
+}