@appium/base-driver 10.2.0 → 10.2.1

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

@@ -1,11 +1,13 @@
 import _ from 'lodash';
 import path from 'node:path';
 import express from 'express';
+import type {Express, RequestHandler} from 'express';
 import http from 'node:http';
+import type {Server as HttpServer} from 'node:http';
 import favicon from 'serve-favicon';
 import bodyParser from 'body-parser';
 import methodOverride from 'method-override';
-import log from './logger';
+import {log} from './logger';
 import {startLogFormatter, endLogFormatter} from './express-logging';
 import {
   allowCrossDomain,
@@ -18,7 +20,13 @@ import {
   catch404Handler,
   handleLogContext,
 } from './middleware';
-import {guineaPig, guineaPigScrollable, guineaPigAppBanner, welcome, STATIC_DIR} from './static';
+import {
+  guineaPig,
+  guineaPigScrollable,
+  guineaPigAppBanner,
+  welcome,
+  STATIC_DIR,
+} from './static';
 import {produceError, produceCrash} from './crash';
 import {
   addWebSocketHandler,
@@ -29,20 +37,81 @@ import {
 import B from 'bluebird';
 import {DEFAULT_BASE_PATH} from '../constants';
 import {fs, timing} from '@appium/support';
+import type {
+  AppiumServer,
+  ServerArgs,
+  UpdateServerCallback,
+  MethodMap,
+  ExternalDriver,
+  StringRecord,
+} from '@appium/types';
 
 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;
+}
+
+/** Options for {@linkcode configureHttp} */
+export interface ConfigureHttpOpts {
+  httpServer: HttpServer;
+  reject: (error?: unknown) => void;
+  keepAliveTimeout: number;
+  gracefulShutdownTimeout?: number;
+}
+
+/** Options for {@linkcode startServer} */
+export interface StartServerOpts {
+  httpServer: HttpServer;
+  port: number;
+  hostname?: string;
+  keepAliveTimeout: number;
+  requestTimeout?: number;
+}
+
 /**
- *
- * @param {ServerOpts} opts
- * @returns {Promise<AppiumServer>}
+ * @param opts - Server options
+ * @returns Promise resolving to the Appium server instance
  */
-export async function server(opts) {
+export async function server(opts: ServerOpts): Promise<AppiumServer> {
   const {
     routeConfiguringFunction,
     port,
     hostname,
-    cliArgs = /** @type {import('@appium/types').ServerArgs} */ ({}),
+    cliArgs = {},
     allowCors = true,
     basePath = DEFAULT_BASE_PATH,
     extraMethodMap = {},
@@ -54,7 +123,7 @@ export async function server(opts) {
   const app = express();
   const httpServer = await createServer(app, cliArgs);
 
-  return await new B(async (resolve, reject) => {
+  return await new B<AppiumServer>(async (resolve, reject) => {
     // we put an async function as the promise constructor because we want some things to happen in
     // serial (application of plugin updates, for example). But we still need to use a promise here
     // because some elements of server start failure only happen in httpServer listeners. So the
@@ -103,8 +172,9 @@ export async function server(opts) {
 }
 
 /**
- * Sets up some Express middleware and stuff
- * @param {ConfigureServerOpts} opts
+ * Sets up Express middleware and routes.
+ *
+ * @param opts - Configuration options
  */
 export function configureServer({
   app,
@@ -114,7 +184,7 @@ export function configureServer({
   extraMethodMap = {},
   webSocketsMapping = {},
   useLegacyUpgradeHandler = true,
-}) {
+}: ConfigureServerOpts): void {
   basePath = normalizeBasePath(basePath);
 
   app.use(endLogFormatter);
@@ -128,7 +198,7 @@ export function configureServer({
   app.use(`${basePath}/produce_error`, produceError);
   app.use(`${basePath}/crash`, produceCrash);
 
-  // Only use legacy Express middleware for WebSocket upgrades if shouldUpgradeCallback is not available
+  // 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) {
@@ -161,17 +231,17 @@ export function configureServer({
 }
 
 /**
- * Normalize base path string
- * @param {string} basePath
- * @returns {string}
+ * Normalize base path string (leading slash, no trailing slash).
+ *
+ * @param basePath - Raw base path
+ * @returns Normalized base path
  */
-export function normalizeBasePath(basePath) {
+export function normalizeBasePath(basePath: string): string {
   if (!_.isString(basePath)) {
     throw new Error(`Invalid path prefix ${basePath}`);
   }
 
-  // ensure the path prefix does not end in '/', since our method map
-  // starts all paths with '/'
+  // 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
@@ -183,64 +253,78 @@ export function normalizeBasePath(basePath) {
   return basePath;
 }
 
-/**
- *
- * @param {import('express').Express} app
- * @param {Partial<import('@appium/types').ServerArgs>} [cliArgs]
- * @returns {Promise<http.Server>}
- */
-async function createServer (app, cliArgs) {
+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`);
+    throw new Error(
+      `Both certificate path and key path must be provided to enable TLS`
+    );
   }
 
   const certKey = [sslCertificatePath, sslKeyPath];
   const zipped = _.zip(
     await B.all(certKey.map((p) => fs.exists(p))),
     ['certificate', 'key'],
-    certKey,
-  );
+    certKey
+  ) as [boolean, string, string][];
   for (const [exists, desc, p] of zipped) {
     if (!exists) {
-      throw new Error(`The provided SSL ${desc} at '${p}' does not exist or is not accessible`);
+      throw new Error(
+        `The provided SSL ${desc} at '${p}' does not exist or is not accessible`
+      );
     }
   }
-  const [cert, key] = await B.all(certKey.map((p) => fs.readFile(p, 'utf8')));
+  const [cert, key] = await B.all(
+    certKey.map((p) => fs.readFile(p, 'utf8'))
+  ) as [string, string];
   log.debug('Enabling TLS/SPDY on the server using the provided certificate');
 
-  return require('spdy').createServer({
-    cert,
-    key,
-    spdy: {
-      plain: false,
-      ssl: true,
-    }
-  }, app);
+  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
+  );
 }
 
 /**
- * Monkeypatches the `http.Server` instance and returns a {@linkcode AppiumServer}.
- * This function _mutates_ the `httpServer` parameter.
- * @param {ConfigureHttpOpts} opts
- * @returns {AppiumServer}
+ * 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, keepAliveTimeout, gracefulShutdownTimeout}) {
-  /**
-   * @type {AppiumServer}
-   */
-  const appiumServer = /** @type {any} */ (httpServer);
+function configureHttp({
+  httpServer,
+  reject,
+  keepAliveTimeout,
+  gracefulShutdownTimeout,
+}: ConfigureHttpOpts): AppiumServer {
+  const appiumServer = httpServer as unknown as AppiumServer;
   appiumServer.webSocketsMapping = {};
   appiumServer.addWebSocketHandler = addWebSocketHandler;
   appiumServer.removeWebSocketHandler = removeWebSocketHandler;
   appiumServer.removeAllWebSocketHandlers = removeAllWebSocketHandlers;
   appiumServer.getWebSocketHandlers = getWebSocketHandlers;
   appiumServer.isSecure = function isSecure() {
-    // eslint-disable-next-line dot-notation
-    return Boolean(this['_spdyState']?.secure);
+    return Boolean((this as unknown as {_spdyState?: {secure?: boolean}})._spdyState?.secure);
   };
 
   // This avoids Express middleware timeout issues with long-lived WebSocket connections
@@ -248,8 +332,8 @@ function configureHttp({httpServer, reject, keepAliveTimeout, gracefulShutdownTi
   // See: https://github.com/nodejs/node/pull/59824
   if (hasShouldUpgradeCallback(httpServer)) {
     // shouldUpgradeCallback only returns a boolean to indicate if the upgrade should proceed
-    // eslint-disable-next-line dot-notation
-    appiumServer['shouldUpgradeCallback'] = (req) => _.toLower(req.headers?.upgrade) === 'websocket';
+    (appiumServer as unknown as {shouldUpgradeCallback?: (req: http.IncomingMessage) => boolean}).shouldUpgradeCallback = (req) =>
+      _.toLower(req.headers?.upgrade) === 'websocket';
     appiumServer.on('upgrade', (req, socket, head) => {
       if (!tryHandleWebSocketUpgrade(req, socket, head, appiumServer.webSocketsMapping)) {
         socket.destroy();
@@ -261,73 +345,69 @@ function configureHttp({httpServer, reject, keepAliveTimeout, gracefulShutdownTi
   // all connections are closed and the `close` event is emitted
   const originalClose = appiumServer.close.bind(appiumServer);
   appiumServer.close = async () =>
-    await new B((_resolve, _reject) => {
+    await new B<void>((_resolve, _reject) => {
       log.info('Closing Appium HTTP server');
       const timer = new timing.Timer().start();
       const onTimeout = setTimeout(() => {
-        if (gracefulShutdownTimeout > 0) {
+        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.`
+              `This timeout might be customized by the --shutdown-timeout command line ` +
+              `argument. Closing the server anyway.`
           );
         }
         process.exit(process.exitCode ?? 0);
-      }, gracefulShutdownTimeout);
-      httpServer.once('close', () => {
+      }, gracefulShutdownTimeout ?? 0);
+      const onClose = () => {
         log.info(
           `Appium HTTP server has been successfully closed after ` +
-          `${timer.getDuration().asMilliSeconds.toFixed(0)}ms`
+            `${timer.getDuration().asMilliSeconds.toFixed(0)}ms`
         );
         clearTimeout(onTimeout);
         _resolve();
-      });
-      originalClose((/** @type {Error|undefined} */ err) => {
+      };
+      httpServer.once('close', onClose);
+      originalClose((err?: Error) => {
         if (err) {
+          clearTimeout(onTimeout);
+          httpServer.removeListener('close', onClose);
           _reject(err);
         }
       });
     });
 
-  appiumServer.once(
-    'error',
-    /** @param {NodeJS.ErrnoException} err */ (err) => {
-      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.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;
 }
 
-/**
- * Starts an {@linkcode AppiumServer}
- * @param {StartServerOpts} opts
- * @returns {Promise<void>}
- */
 async function startServer({
   httpServer,
   port,
   hostname,
   keepAliveTimeout,
   requestTimeout,
-}) {
-  // If the hostname is omitted, the server will accept
-  // connections on any IP address
-  /** @type {(port: number, hostname?: string) => B<http.Server>} */
-  const start = B.promisify(httpServer.listen, {context: httpServer});
+}: StartServerOpts): Promise<void> {
+  // If the hostname is omitted, the server will accept connections on any IP address
+  const start = B.promisify(httpServer.listen, {
+    context: httpServer,
+  }) as (port: number, hostname?: string) => B<HttpServer>;
   const startPromise = start(port, hostname);
   httpServer.keepAliveTimeout = keepAliveTimeout;
   if (_.isInteger(requestTimeout)) {
@@ -339,92 +419,20 @@ async function startServer({
 }
 
 /**
- * Checks if the provided server instance supports `shouldUpgradeCallback`.
- * This feature was added in Node.js v22.21.0 (LTS) and v24.9.0.
- * @param {import('http').Server} server - The HTTP server instance to check
- * @returns {boolean}
+ * 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) {
+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 {
-    // Use bracket notation to access property that may not exist in type definitions
-    // eslint-disable-next-line dot-notation
-    return typeof server['shouldUpgradeCallback'] !== 'undefined';
+    return (
+      typeof (server as unknown as {shouldUpgradeCallback?: unknown}).shouldUpgradeCallback !==
+      'undefined'
+    );
   } catch {
     return false;
   }
 }
-
-/**
- * Options for {@linkcode startServer}.
- * @typedef StartServerOpts
- * @property {import('http').Server} httpServer - HTTP server instance
- * @property {number} port - Port to run on
- * @property {number} keepAliveTimeout - Keep-alive timeout in milliseconds
- * @property {string} [hostname] - Optional hostname
- * @property {number} [requestTimeout] - The timeout value in milliseconds for
- * receiving the entire request from the client
- */
-
-/**
- * @typedef {import('@appium/types').AppiumServer} AppiumServer
- */
-
-/**
- * @typedef {import('@appium/types').MethodMap<import('@appium/types').ExternalDriver>} MethodMap
- */
-
-/**
- * Options for {@linkcode configureHttp}
- * @typedef ConfigureHttpOpts
- * @property {import('http').Server} httpServer - HTTP server instance
- * @property {(error?: any) => void} reject - Rejection function from `Promise` constructor
- * @property {number} keepAliveTimeout - Keep-alive timeout in milliseconds
- * @property {number} gracefulShutdownTimeout - For how long the server should delay its
- * shutdown before force-closing all open connections to it. Providing zero will force-close
- * the server without waiting for any connections.
- */
-
-/**
- * Options for {@linkcode server}
- * @typedef ServerOpts
- * @property {RouteConfiguringFunction} routeConfiguringFunction
- * @property {number} port
- * @property {import('@appium/types').ServerArgs} [cliArgs]
- * @property {string} [hostname]
- * @property {boolean} [allowCors]
- * @property {string} [basePath]
- * @property {MethodMap} [extraMethodMap]
- * @property {import('@appium/types').UpdateServerCallback[]} [serverUpdaters]
- * @property {number} [keepAliveTimeout]
- * @property {number} [requestTimeout]
- */
-
-/**
- * A function which configures routes
- * @callback RouteConfiguringFunction
- * @param {import('express').Express} app
- * @param {RouteConfiguringFunctionOpts} [opts]
- * @returns {void}
- */
-
-/**
- * Options for a {@linkcode RouteConfiguringFunction}
- * @typedef RouteConfiguringFunctionOpts
- * @property {string} [basePath]
- * @property {MethodMap} [extraMethodMap]
- */
-
-/**
- * Options for {@linkcode configureServer}
- * @typedef ConfigureServerOpts
- * @property {import('express').Express} app
- * @property {RouteConfiguringFunction} addRoutes
- * @property {boolean} [allowCors]
- * @property {string} [basePath]
- * @property {MethodMap} [extraMethodMap]
- * @property {import('@appium/types').StringRecord} [webSocketsMapping={}]
- * @property {boolean} [useLegacyUpgradeHandler=true] - Whether to use legacy Express middleware for WebSocket upgrades.
- *   Set to false when using shouldUpgradeCallback on the HTTP server (Node.js >= 22.21.0 or >= 24.9.0).
- */

package/lib/express/static.ts

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import {log} from './logger';
+import _ from 'lodash';
+import {fs} from '@appium/support';
+import B from 'bluebird';
+import type {Request, Response} from 'express';
+
+export const STATIC_DIR = _.isNull(path.resolve(__dirname).match(/build[/\\]lib[/\\]express$/))
+  ? path.resolve(__dirname, '..', '..', 'static')
+  : path.resolve(__dirname, '..', '..', '..', 'static');
+
+type TemplateParams = Record<string, unknown>;
+
+/** Dynamic page mapped to /test/guinea-pig */
+export async function guineaPig(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig.html');
+}
+
+/** Dynamic page mapped to /test/guinea-pig-scrollable */
+export async function guineaPigScrollable(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig-scrollable.html');
+}
+
+/** Dynamic page mapped to /test/guinea-pig-app-banner */
+export async function guineaPigAppBanner(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig-app-banner.html');
+}
+
+/** Dynamic page mapped to /welcome */
+export async function welcome(req: Request, res: Response): Promise<void> {
+  const params: TemplateParams = {message: "Let's browse!"};
+  log.debug(`Sending welcome response with params: ${JSON.stringify(params)}`);
+  const template = await getTemplate('welcome.html');
+  res.send(template(params));
+}
+
+async function guineaPigTemplate(
+  req: Request,
+  res: Response,
+  page: string
+): Promise<void> {
+  const delay = parseInt(
+    String(req.params.delay ?? (req.query?.delay ?? 0)),
+    10
+  );
+  const throwError = String(req.params.throwError ?? req.query?.throwError ?? '');
+  const params: TemplateParams = {
+    throwError,
+    serverTime: new Date(),
+    userAgent: req.headers['user-agent'],
+    comment: 'None',
+  };
+  if (req.method === 'POST' && req.body && typeof req.body === 'object' && 'comments' in req.body) {
+    params.comment = String((req.body as {comments?: string}).comments ?? params.comment);
+  }
+  log.debug(`Sending guinea pig response with params: ${JSON.stringify(params)}`);
+  if (delay) {
+    log.debug(`Waiting ${delay}ms before responding`);
+    await B.delay(delay);
+  }
+  res.set('content-type', 'text/html');
+  res.cookie('guineacookie1', 'i am a cookie value', {path: '/'});
+  res.cookie('guineacookie2', 'cookié2', {path: '/'});
+  res.cookie('guineacookie3', 'cant access this', {
+    domain: '.blargimarg.com',
+    path: '/',
+  });
+  const template = await getTemplate(page);
+  res.send(template(params));
+}
+
+async function getTemplate(
+  templateName: string
+): Promise<(params: TemplateParams) => string> {
+  const content = await fs.readFile(path.resolve(STATIC_DIR, 'test', templateName));
+  return _.template(content.toString()) as (params: TemplateParams) => string;
+}

package/lib/express/websocket.ts

@@ -0,0 +1,81 @@
+import _ from 'lodash';
+import B from 'bluebird';
+import type {AppiumServer, WSServer} from '@appium/types';
+
+export const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
+
+/**
+ * Adds a WebSocket handler to this server's mapping.
+ * @see AppiumServerExtension.addWebSocketHandler
+ */
+export async function addWebSocketHandler(
+  this: AppiumServer,
+  handlerPathname: string,
+  handlerServer: WSServer
+): Promise<void> {
+  this.webSocketsMapping[handlerPathname] = handlerServer;
+}
+
+/**
+ * Returns WebSocket handlers for this server, optionally filtered by pathname.
+ * @see AppiumServerExtension.getWebSocketHandlers
+ */
+export async function getWebSocketHandlers(
+  this: AppiumServer,
+  keysFilter: string | null = null
+): Promise<Record<string, WSServer>> {
+  return _.toPairs(this.webSocketsMapping).reduce<Record<string, WSServer>>(
+    (acc, [pathname, wsServer]) => {
+      if (!_.isString(keysFilter) || pathname.includes(keysFilter)) {
+        acc[pathname] = wsServer;
+      }
+      return acc;
+    },
+    {}
+  );
+}
+
+/**
+ * Removes a WebSocket handler by pathname.
+ * @see AppiumServerExtension.removeWebSocketHandler
+ */
+export async function removeWebSocketHandler(
+  this: AppiumServer,
+  handlerPathname: string
+): Promise<boolean> {
+  const wsServer = this.webSocketsMapping?.[handlerPathname];
+  if (!wsServer) {
+    return false;
+  }
+
+  try {
+    wsServer.close();
+    for (const client of wsServer.clients || []) {
+      client.terminate();
+    }
+    return true;
+  } catch {
+    // ignore
+  } finally {
+    delete this.webSocketsMapping[handlerPathname];
+  }
+  return false;
+}
+
+/**
+ * Removes all WebSocket handlers from this server.
+ * @see AppiumServerExtension.removeAllWebSocketHandlers
+ */
+export async function removeAllWebSocketHandlers(this: AppiumServer): Promise<boolean> {
+  if (_.isEmpty(this.webSocketsMapping)) {
+    return false;
+  }
+
+  return _.some(
+    await B.all(
+      _.keys(this.webSocketsMapping).map((pathname) =>
+        this.removeWebSocketHandler(pathname)
+      )
+    )
+  );
+}