Breaking: Return an object containing httpServer from runServer API

Summary:
Currently the `runServer` API simply returns the Node.js `HttpServer` (or `HttpsServer`) instance it creates.

Because that's not a type we control, we can't extend this API - for example, it can't expose an imperative `end()`, or anything about the Metro server. We've come up against this limitation with this specific API in the past.

Since we're about to release a major version with other breaking changes, this takes the opportunity to change the return type to `Promise<{httpServer: HttpServer | HttpsServer}>`, thereby making it extensible in subsequent non-breaking changes.

Changelog:
```
 - **[Breaking]**: Metro.runServer - return an object containing `httpServer` rather than the server instance directly

Reviewed By: huntie

Differential Revision: D78099715

fbshipit-source-id: 1aae46cc73a4b9901ef1b9cbffdab66b6d04fd72

Author: robhogan

docs/GettingStarted.md

@@ -76,7 +76,7 @@ app.listen(8081);
 
 ### Method `runServer(config, options)`
 
-Starts a development server based on the given configuration and options. Returns the server.
+Starts a development server based on the given configuration and options. Returns an object with `httpServer`, the Node.js HTTP(S) server.
 We recommend using `runMetro` instead of `runServer`, `runMetro` calls this function.
 
 #### Options
@@ -88,7 +88,7 @@ We recommend using `runMetro` instead of `runServer`, `runMetro` calls this func
 ```js
 const config = await Metro.loadConfig();
 
-const metroHttpServer = await Metro.runServer(config, {
+await Metro.runServer(config, {
   onClose: () => {console.log('metro server and all associated processes are closed')}
 });
 

packages/metro/src/commands/serve.js

@@ -107,7 +107,10 @@ module.exports = (): {
         resetCache: _resetCache,
         ...runServerOptions
       } = argv;
-      server = await MetroApi.runServer(config, runServerOptions);
+      ({httpServer: server} = await MetroApi.runServer(
+        config,
+        runServerOptions,
+      ));
 
       restarting = false;
     }

packages/metro/src/index.flow.js

@@ -85,6 +85,10 @@ export type RunServerOptions = $ReadOnly<{
   }>,
 }>;
 
+export type RunServerResult = {
+  httpServer: HttpServer | HttpsServer,
+};
+
 type BuildGraphOptions = {
   entries: $ReadOnlyArray<string>,
   customTransformOptions?: CustomTransformOptions,
@@ -270,7 +274,7 @@ exports.runServer = async (
     websocketEndpoints = {},
     watch,
   }: RunServerOptions = {},
-): Promise<HttpServer | HttpsServer> => {
+): Promise<RunServerResult> => {
   await earlyPortCheck(host, config.server.port);
 
   if (secure != null || secureCert != null || secureKey != null) {
@@ -319,73 +323,68 @@ exports.runServer = async (
   } else {
     httpServer = http.createServer(serverApp);
   }
-  return new Promise(
-    (
-      resolve: (result: HttpServer | HttpsServer) => void,
-      reject: mixed => mixed,
-    ) => {
-      httpServer.on('error', error => {
-        endMiddleware().finally(() => {
-          onError?.(error);
-          reject(error);
-        });
+  return new Promise((resolve, reject) => {
+    httpServer.on('error', error => {
+      endMiddleware().finally(() => {
+        onError?.(error);
+        reject(error);
       });
+    });
 
-      httpServer.listen(config.server.port, host, () => {
-        const {address, port, family} = httpServer.address();
-        config.reporter.update({
-          type: 'server_listening',
-          address,
-          port, // Assigned port if configured with port 0
-          family,
-        });
-
-        websocketEndpoints = {
-          ...websocketEndpoints,
-          '/hot': createWebsocketServer({
-            websocketServer: new MetroHmrServer(
-              metroServer.getBundler(),
-              metroServer.getCreateModuleId(),
-              config,
-            ),
-          }),
-        };
-
-        httpServer.on('upgrade', (request, socket, head) => {
-          const {pathname} = parse(request.url);
-          if (pathname != null && websocketEndpoints[pathname]) {
-            websocketEndpoints[pathname].handleUpgrade(
-              request,
-              socket,
-              head,
-              ws => {
-                websocketEndpoints[pathname].emit('connection', ws, request);
-              },
-            );
-          } else {
-            socket.destroy();
-          }
-        });
-
-        if (onReady) {
-          onReady(httpServer);
-        }
+    httpServer.listen(config.server.port, host, () => {
+      const {address, port, family} = httpServer.address();
+      config.reporter.update({
+        type: 'server_listening',
+        address,
+        port, // Assigned port if configured with port 0
+        family,
+      });
 
-        resolve(httpServer);
+      websocketEndpoints = {
+        ...websocketEndpoints,
+        '/hot': createWebsocketServer({
+          websocketServer: new MetroHmrServer(
+            metroServer.getBundler(),
+            metroServer.getCreateModuleId(),
+            config,
+          ),
+        }),
+      };
+
+      httpServer.on('upgrade', (request, socket, head) => {
+        const {pathname} = parse(request.url);
+        if (pathname != null && websocketEndpoints[pathname]) {
+          websocketEndpoints[pathname].handleUpgrade(
+            request,
+            socket,
+            head,
+            ws => {
+              websocketEndpoints[pathname].emit('connection', ws, request);
+            },
+          );
+        } else {
+          socket.destroy();
+        }
       });
 
-      // Disable any kind of automatic timeout behavior for incoming
-      // requests in case it takes the packager more than the default
-      // timeout of 120 seconds to respond to a request.
-      httpServer.timeout = 0;
+      if (onReady) {
+        onReady(httpServer);
+      }
+
+      resolve({httpServer});
+    });
+
+    // Disable any kind of automatic timeout behavior for incoming
+    // requests in case it takes the packager more than the default
+    // timeout of 120 seconds to respond to a request.
+    httpServer.timeout = 0;
 
-      httpServer.on('close', () => {
-        endMiddleware()?.finally(() => {
-          onClose?.();
-        });
+    httpServer.on('close', () => {
+      endMiddleware()?.finally(() => {
+        onClose?.();
       });
-    },
-  );
+    });
+  });
 };
 
 exports.runBuild = async (

packages/metro/src/integration_tests/__tests__/server-test.js

@@ -60,12 +60,12 @@ describe('Metro development server serves bundles via HTTP', () => {
 
     let onCloseResolve;
     serverClosedPromise = new Promise(resolve => (onCloseResolve = resolve));
-    httpServer = await Metro.runServer(config, {
+    ({httpServer} = await Metro.runServer(config, {
       reporter: {update() {}},
       onClose: () => {
         onCloseResolve();
       },
-    });
+    }));
   });
 
   afterEach(async () => {

packages/metro/src/integration_tests/__tests__/server-torn-down-test.js

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  *
  * @format
+ * @flow strict-local
  * @oncall react_native
  */
 
 const Metro = require('../../..');
+// $FlowFixMe[cannot-resolve-module] - Untyped module
 const asyncHooks = require('async_hooks');
 
 jest.unmock('cosmiconfig');
@@ -18,7 +20,10 @@ jest.useRealTimers();
 jest.setTimeout(10000);
 
 describe('Server torn down test', () => {
-  const active = new Map();
+  const active = new Map<
+    number,
+    {type: string, callStack: string, resource: mixed},
+  >();
   const hook = asyncHooks.createHook({
     init(asyncId, type, _triggerAsyncId, resource) {
       if (
@@ -76,8 +81,7 @@ describe('Server torn down test', () => {
     let onCloseResolve;
     const closePromise = new Promise(resolve => (onCloseResolve = resolve));
 
-    const httpServer = await Metro.runServer(config, {
-      reporter: {update() {}},
+    const {httpServer} = await Metro.runServer(config, {
       onClose: () => {
         onCloseResolve();
       },

packages/metro/types/index.d.ts

@@ -82,6 +82,10 @@ export interface RunServerOptions {
   };
 }
 
+export interface RunServerResult {
+  httpServer: HttpServer | HttpsServer;
+}
+
 export interface RunBuildOptions {
   entry: string;
   dev?: boolean;
@@ -139,7 +143,7 @@ export function createConnectMiddleware(
 export function runServer(
   config: ConfigT,
   options: RunServerOptions,
-): Promise<HttpServer | HttpsServer>;
+): Promise<RunServerResult>;
 
 export function runBuild(
   config: ConfigT,