appium/packages/base-driver/lib/express/server.ts

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;
  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,
          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));
  }
  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,
  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, appiumServer.webSocketsMapping)) {
        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;
  }
}