feat(ext/http): Add `addr` to HttpServer (#23442)

Adds an `addr` field to `HttpServer` to simplify the pattern
`Deno.serve({ onListen({ port } => listenPort = port })`. This becomes:
`const server = Deno.serve({}); port = server.addr.port`.

Changes:
- Refactors `serve` overloads to split TLS out (in preparation for
landing a place for the TLS SNI information)
- Adds an `addr` field to `HttpServer` that matches the `addr` field of
the corresponding `Deno.Listener`s.

1 files changed, 111 insertions, 11 deletions

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index c63b4a261..fc64876f4 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -6217,7 +6217,7 @@ declare namespace Deno {
    */
   export function gid(): number | null;
 
-  /** Information for a HTTP request.
+  /** Additional information for an HTTP request and its connection.
    *
    * @category HTTP Server
    */
@@ -6269,7 +6269,7 @@ declare namespace Deno {
     onError?: (error: unknown) => Response | Promise<Response>;
 
     /** The callback which is called when the server starts listening. */
-    onListen?: (params: { hostname: string; port: number }) => void;
+    onListen?: (localAddr: Deno.NetAddr) => void;
   }
 
   /** Additional options which are used when opening a TLS (HTTPS) server.
@@ -6304,6 +6304,14 @@ declare namespace Deno {
     handler: ServeHandler;
   }
 
+  /**
+   * @category HTTP Server
+   */
+  export interface ServeTlsInit {
+    /** The handler to invoke to process each incoming request. */
+    handler: ServeHandler;
+  }
+
   /** @category HTTP Server */
   export interface ServeUnixOptions {
     /** The unix domain socket path to listen on. */
@@ -6316,7 +6324,7 @@ declare namespace Deno {
     onError?: (error: unknown) => Response | Promise<Response>;
 
     /** The callback which is called when the server starts listening. */
-    onListen?: (params: { path: string }) => void;
+    onListen?: (localAddr: Deno.UnixAddr) => void;
   }
 
   /** Information for a unix domain socket HTTP request.
@@ -6353,12 +6361,16 @@ declare namespace Deno {
    *
    * @category HTTP Server
    */
-  export interface HttpServer extends AsyncDisposable {
+  export interface HttpServer<A extends Deno.Addr = Deno.Addr>
+    extends AsyncDisposable {
     /** A promise that resolves once server finishes - eg. when aborted using
      * the signal passed to {@linkcode ServeOptions.signal}.
      */
     finished: Promise<void>;
 
+    /** The local address this server is listening on. */
+    addr: A;
+
     /**
      * Make the server block the event loop from finishing.
      *
@@ -6395,7 +6407,7 @@ declare namespace Deno {
    *
    * @category HTTP Server
    */
-  export function serve(handler: ServeHandler): HttpServer;
+  export function serve(handler: ServeHandler): HttpServer<Deno.NetAddr>;
   /** Serves HTTP requests with the given option bag and handler.
    *
    * You can specify the socket path with `path` option.
@@ -6444,7 +6456,67 @@ declare namespace Deno {
   export function serve(
     options: ServeUnixOptions,
     handler: ServeUnixHandler,
-  ): HttpServer;
+  ): HttpServer<Deno.UnixAddr>;
+  /** Serves HTTP requests with the given option bag and handler.
+   *
+   * You can specify an object with a port and hostname option, which is the
+   * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`.
+   *
+   * You can change the address to listen on using the `hostname` and `port`
+   * options. The below example serves on port `3000` and hostname `"0.0.0.0"`.
+   *
+   * ```ts
+   * Deno.serve(
+   *   { port: 3000, hostname: "0.0.0.0" },
+   *   (_req) => new Response("Hello, world")
+   * );
+   * ```
+   *
+   * You can stop the server with an {@linkcode AbortSignal}. The abort signal
+   * needs to be passed as the `signal` option in the options bag. The server
+   * aborts when the abort signal is aborted. To wait for the server to close,
+   * await the promise returned from the `Deno.serve` API.
+   *
+   * ```ts
+   * const ac = new AbortController();
+   *
+   * const server = Deno.serve(
+   *    { signal: ac.signal },
+   *    (_req) => new Response("Hello, world")
+   * );
+   * server.finished.then(() => console.log("Server closed"));
+   *
+   * console.log("Closing server...");
+   * ac.abort();
+   * ```
+   *
+   * By default `Deno.serve` prints the message
+   * `Listening on http://<hostname>:<port>/` on listening. If you like to
+   * change this behavior, you can specify a custom `onListen` callback.
+   *
+   * ```ts
+   * Deno.serve({
+   *   onListen({ port, hostname }) {
+   *     console.log(`Server started at http://${hostname}:${port}`);
+   *     // ... more info specific to your server ..
+   *   },
+   * }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * To enable TLS you must specify the `key` and `cert` options.
+   *
+   * ```ts
+   * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
+   * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
+   * Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * @category HTTP Server
+   */
+  export function serve(
+    options: ServeOptions,
+    handler: ServeHandler,
+  ): HttpServer<Deno.NetAddr>;
   /** Serves HTTP requests with the given option bag and handler.
    *
    * You can specify an object with a port and hostname option, which is the
@@ -6503,11 +6575,10 @@ declare namespace Deno {
    */
   export function serve(
     options:
-      | ServeOptions
       | ServeTlsOptions
       | (ServeTlsOptions & TlsCertifiedKeyOptions),
     handler: ServeHandler,
-  ): HttpServer;
+  ): HttpServer<Deno.NetAddr>;
   /** Serves HTTP requests with the given option bag.
    *
    * You can specify an object with the path option, which is the
@@ -6534,7 +6605,7 @@ declare namespace Deno {
    */
   export function serve(
     options: ServeUnixInit & ServeUnixOptions,
-  ): HttpServer;
+  ): HttpServer<Deno.UnixAddr>;
   /** Serves HTTP requests with the given option bag.
    *
    * You can specify an object with a port and hostname option, which is the
@@ -6563,10 +6634,39 @@ declare namespace Deno {
   export function serve(
     options:
       & ServeInit
+      & ServeOptions,
+  ): HttpServer<Deno.NetAddr>;
+  /** Serves HTTP requests with the given option bag.
+   *
+   * You can specify an object with a port and hostname option, which is the
+   * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`.
+   *
+   * ```ts
+   * const ac = new AbortController();
+   *
+   * const server = Deno.serve({
+   *   port: 3000,
+   *   hostname: "0.0.0.0",
+   *   handler: (_req) => new Response("Hello, world"),
+   *   signal: ac.signal,
+   *   onListen({ port, hostname }) {
+   *     console.log(`Server started at http://${hostname}:${port}`);
+   *   },
+   * });
+   * server.finished.then(() => console.log("Server closed"));
+   *
+   * console.log("Closing server...");
+   * ac.abort();
+   * ```
+   *
+   * @category HTTP Server
+   */
+  export function serve(
+    options:
+      & ServeTlsInit
       & (
-        | ServeOptions
         | ServeTlsOptions
         | (ServeTlsOptions & TlsCertifiedKeyOptions)
       ),
-  ): HttpServer;
+  ): HttpServer<Deno.NetAddr>;
 }