Update types and improve docs for server.enhanceMiddleware

Summary:
Resolves #739.

Usage example / types fix is inspired by use in `react-native-community/cli-plugin-metro`:
https://github.com/react-native-community/cli/blob/main/packages/cli-plugin-metro/src/commands/start/runServer.ts#L87-L97

Changelog: **[Types]** Update config and `Server` types to use broader types from `connect` package

Reviewed By: motiz88

Differential Revision: D46228146

fbshipit-source-id: 63718ae44bed12735bd798a9c819b128aeb5a9d6

Author: huntie

docs/Configuration.md

@@ -607,9 +607,23 @@ Whether we should enable CMD+R hotkey for refreshing the bundle.
 
 #### `enhanceMiddleware`
 
-Type: `(Middleware, Server) => Middleware`
+Type: `(Middleware, MetroServer) => Middleware`
 
-The possibility to add custom middleware to the server response chain.
+A function that allows attaching custom [`connect`](https://www.npmjs.com/package/connect) middleware to Metro. For example:
+
+:::tip
+You can use [`connect()`](https://www.npmjs.com/package/connect#mount-middleware) as a util to extend the base `metroMiddleware` and to mount additional middleware handlers.
+:::
+
+```ts
+enhanceMiddleware: (metroMiddleware: Middleware, metroServer: MetroServer) => {
+  return connect()
+    .use(metroMiddleware)
+    .use('/custom-endpoint', customEndpointMiddleware());
+},
+```
+
+The `Middleware` type is an alias for [`connect.HandleFunction`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/876b9ec96ba02d0c84b1e49af5890c8f5aa2dfe3/types/connect/index.d.ts#L29).
 
 #### `rewriteRequestUrl`
 

flow-typed/Promise.js

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.

flow-typed/npm/chalk_v4.x.x.js

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.

flow-typed/npm/connect_v3.x.x.js

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ * @oncall react_native
+ */
+
+declare module 'connect' {
+  import type http from 'http';
+
+  declare export type ServerHandle = HandleFunction | http.Server;
+
+  declare type NextFunction = (err?: mixed) => void;
+
+  declare export type NextHandleFunction = (
+    req: IncomingMessage,
+    res: http.ServerResponse,
+    next: NextFunction,
+  ) => void | Promise<void>;
+  declare export type HandleFunction =
+    | NextHandleFunction;
+
+  declare export interface IncomingMessage extends http.IncomingMessage {
+    originalUrl?: http.IncomingMessage['url'];
+  }
+
+  declare export interface Server extends events$EventEmitter {
+    (req: IncomingMessage, res: http.ServerResponse): void;
+
+    use(fn: HandleFunction): Server;
+    use(route: string, fn: HandleFunction): Server;
+
+    listen(
+      port: number,
+      hostname?: string,
+      backlog?: number,
+      callback?: Function,
+    ): http.Server;
+    listen(port: number, hostname?: string, callback?: Function): http.Server;
+    listen(path: string, callback?: Function): http.Server;
+    listen(handle: any, listeningListener?: Function): http.Server;
+  }
+
+  declare type createServer = () => Server;
+
+  declare module.exports: createServer;
+}

packages/metro-config/package.json

@@ -13,6 +13,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "connect": "^3.6.5",
     "cosmiconfig": "^5.0.5",
     "jest-validate": "^29.2.1",
     "metro": "0.76.5",
@@ -21,6 +22,7 @@
     "metro-runtime": "0.76.5"
   },
   "devDependencies": {
+    "@types/connect": "^3.4.35",
     "pretty-format": "^26.5.2",
     "strip-ansi": "^6.0.0"
   },

packages/metro-config/src/configTypes.flow.js

@@ -10,13 +10,14 @@
 
 'use strict';
 
-import type {IncomingMessage, ServerResponse} from 'http';
+import type {HandleFunction, Server} from 'connect';
 import type {CacheStore} from 'metro-cache';
 import typeof MetroCache from 'metro-cache';
 import type {CacheManagerFactory} from 'metro-file-map';
 import type {CustomResolver} from 'metro-resolver';
 import type {JsTransformerConfig} from 'metro-transform-worker';
 import type {TransformResult} from 'metro/src/DeltaBundler';
+import type MetroServer from 'metro/src/Server';
 
 import type {
   DeltaResult,
@@ -25,7 +26,6 @@ import type {
   SerializerOptions,
 } from 'metro/src/DeltaBundler/types.flow.js';
 import type {Reporter} from 'metro/src/lib/reporting';
-import type Server from 'metro/src/Server';
 import type {IntermediateStackFrame} from '../../metro/src/Server/symbolicate';
 
 export type ExtraTransformOptions = {
@@ -52,11 +52,7 @@ export type GetTransformOptions = (
   getDependenciesOf: (string) => Promise<Array<string>>,
 ) => Promise<Partial<ExtraTransformOptions>>;
 
-export type Middleware = (
-  IncomingMessage,
-  ServerResponse,
-  ((e: ?Error) => mixed),
-) => mixed;
+export type Middleware = HandleFunction;
 
 type PerfAnnotations = Partial<{
   string: {[key: string]: string},
@@ -168,7 +164,7 @@ type MetalConfigT = {
 };
 
 type ServerConfigT = {
-  enhanceMiddleware: (Middleware, Server) => Middleware,
+  enhanceMiddleware: (Middleware, MetroServer) => Middleware | Server,
   port: number,
   rewriteRequestUrl: string => string,
   runInspectorProxy: boolean,

packages/metro-config/src/defaults/index.js

@@ -73,7 +73,7 @@ const getDefaultValues = (projectRoot: ?string): ConfigT => ({
   },
 
   server: {
-    enhanceMiddleware: middleware => middleware,
+    enhanceMiddleware: (middleware, _) => middleware,
     port: 8080,
     rewriteRequestUrl: url => url,
     runInspectorProxy: true,

packages/metro-config/types/configTypes.d.ts

@@ -8,7 +8,7 @@
  * @oncall react_native
  */
 
-import type {IncomingMessage, ServerResponse} from 'http';
+import type {HandleFunction, Server} from 'connect';
 import type {CacheStore, MetroCache} from 'metro-cache';
 import type {CustomResolver} from 'metro-resolver';
 import type {JsTransformerConfig} from 'metro-transform-worker';
@@ -20,7 +20,7 @@ import type {
   TransformResult,
 } from 'metro/src/DeltaBundler/types';
 import type {Reporter} from 'metro/src/lib/reporting';
-import type Server from 'metro/src/Server';
+import type MetroServer from 'metro/src/Server';
 
 export interface ExtraTransformOptions {
   readonly preloadedModules: {[path: string]: true} | false;
@@ -45,11 +45,7 @@ export type GetTransformOptions = (
   getDependenciesOf: (filePath: string) => Promise<string[]>,
 ) => Promise<Partial<ExtraTransformOptions>>;
 
-export type Middleware = (
-  incomingMessage: IncomingMessage,
-  serverResponse: ServerResponse,
-  error: (e?: Error) => unknown,
-) => unknown;
+export type Middleware = HandleFunction;
 
 export type PerfAnnotations = Partial<{
   string: {[key: string]: string};
@@ -163,7 +159,10 @@ export interface MetalConfigT {
 }
 
 export interface ServerConfigT {
-  enhanceMiddleware: (middleware: Middleware, server: Server) => Middleware;
+  enhanceMiddleware: (
+    metroMiddleware: Middleware,
+    metroServer: MetroServer,
+  ) => Middleware | Server;
   port: number;
   rewriteRequestUrl: (url: string) => string;
   runInspectorProxy: boolean;

packages/metro/src/Server.js

@@ -31,7 +31,8 @@ import type {
   ResolverInputOptions,
   SplitBundleOptions,
 } from './shared/types.flow';
-import type {IncomingMessage, ServerResponse} from 'http';
+import type {IncomingMessage} from 'connect';
+import type {ServerResponse} from 'http';
 import type {CacheStore} from 'metro-cache';
 import type {ConfigT, RootPerfLogger} from 'metro-config/src/configTypes.flow';
 import type {
@@ -478,11 +479,11 @@ class Server {
   processRequest: (
     IncomingMessage,
     ServerResponse,
-    ((e: ?Error) => mixed),
+    ((e: ?Error) => void),
   ) => void = (
     req: IncomingMessage,
     res: ServerResponse,
-    next: (?Error) => mixed,
+    next: (?Error) => void,
   ) => {
     this._processRequest(req, res, next).catch(next);
   };
@@ -500,7 +501,7 @@ class Server {
   async _processRequest(
     req: IncomingMessage,
     res: ServerResponse,
-    next: (?Error) => mixed,
+    next: (?Error) => void,
   ) {
     const originalUrl = req.url;
     req.url = this._rewriteAndNormalizeUrl(req.url);

packages/metro/src/index.flow.js

@@ -299,6 +299,7 @@ exports.runServer = async (
         ...secureServerOptions,
       };
     }
+    // $FlowFixMe[incompatible-call] 'http' and 'https' Flow types do not match
     httpServer = https.createServer(options, serverApp);
   } else {
     httpServer = http.createServer(serverApp);