feat: stabilize Deno.HttpServer.shutdown and Unix socket support (#21463)

This commit stabilizes "Deno.HttpServer.shutdown" API as well as
Unix socket support in "Deno.serve" API.

---------

Co-authored-by: Yoshiya Hinosawa <stibium121@gmail.com>

3 files changed, 130 insertions, 142 deletions

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index b01fea4c0..ef9f68886 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -5939,6 +5939,50 @@ declare namespace Deno {
     handler: ServeHandler;
   }
 
+  export interface ServeUnixOptions {
+    /** The unix domain socket path to listen on. */
+    path: string;
+
+    /** An {@linkcode AbortSignal} to close the server and all connections. */
+    signal?: AbortSignal;
+
+    /** The handler to invoke when route handlers throw an error. */
+    onError?: (error: unknown) => Response | Promise<Response>;
+
+    /** The callback which is called when the server starts listening. */
+    onListen?: (params: { path: string }) => void;
+  }
+
+  /** Information for a unix domain socket HTTP request.
+   *
+   * @category HTTP Server
+   */
+  export interface ServeUnixHandlerInfo {
+    /** The remote address of the connection. */
+    remoteAddr: Deno.UnixAddr;
+  }
+
+  /** A handler for unix domain socket HTTP requests. Consumes a request and returns a response.
+   *
+   * If a handler throws, the server calling the handler will assume the impact
+   * of the error is isolated to the individual request. It will catch the error
+   * and if necessary will close the underlying connection.
+   *
+   * @category HTTP Server
+   */
+  export type ServeUnixHandler = (
+    request: Request,
+    info: ServeUnixHandlerInfo,
+  ) => Response | Promise<Response>;
+
+  /**
+   * @category HTTP Server
+   */
+  export interface ServeUnixInit {
+    /** The handler to invoke to process each incoming request. */
+    handler: ServeUnixHandler;
+  }
+
   /** An instance of the server created using `Deno.serve()` API.
    *
    * @category HTTP Server
@@ -5959,6 +6003,11 @@ declare namespace Deno {
 
     /** Make the server not block the event loop from finishing. */
     unref(): void;
+
+    /** Gracefully close the server. No more new connections will be accepted,
+     * while pending requests will be allowed to finish.
+     */
+    shutdown(): Promise<void>;
   }
 
   /**
@@ -5980,6 +6029,55 @@ declare namespace Deno {
   export function serve(handler: ServeHandler): HttpServer;
   /** Serves HTTP requests with the given option bag and handler.
    *
+   * You can specify the socket path with `path` option.
+   *
+   * ```ts
+   * Deno.serve(
+   *   { path: "path/to/socket" },
+   *   (_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, path: "path/to/socket" },
+   *    (_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 path/to/socket` on listening. If you like to
+   * change this behavior, you can specify a custom `onListen` callback.
+   *
+   * ```ts
+   * Deno.serve({
+   *   onListen({ path }) {
+   *     console.log(`Server started at ${path}`);
+   *     // ... more info specific to your server ..
+   *   },
+   *   path: "path/to/socket",
+   * }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * @category HTTP Server
+   */
+  export function serve(
+    options: ServeUnixOptions,
+    handler: ServeUnixHandler,
+  ): HttpServer;
+  /** 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"`.
    *
@@ -6040,6 +6138,33 @@ declare namespace Deno {
   ): HttpServer;
   /** Serves HTTP requests with the given option bag.
    *
+   * You can specify an object with the path option, which is the
+   * unix domain socket to listen on.
+   *
+   * ```ts
+   * const ac = new AbortController();
+   *
+   * const server = Deno.serve({
+   *   path: "path/to/socket",
+   *   handler: (_req) => new Response("Hello, world"),
+   *   signal: ac.signal,
+   *   onListen({ path }) {
+   *     console.log(`Server started at ${path}`);
+   *   },
+   * });
+   * server.finished.then(() => console.log("Server closed"));
+   *
+   * console.log("Closing server...");
+   * ac.abort();
+   * ```
+   *
+   * @category HTTP Server
+   */
+  export function serve(
+    options: ServeUnixInit & ServeUnixOptions,
+  ): HttpServer;
+  /** 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"`.
    *
diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts
index bdb0493b0..1858f6cd0 100644
--- a/cli/tsc/dts/lib.deno.unstable.d.ts
+++ b/cli/tsc/dts/lib.deno.unstable.d.ts
@@ -2099,138 +2099,6 @@ declare namespace Deno {
     readonly value: bigint;
   }
 
-  /** An instance of the server created using `Deno.serve()` API.
-   *
-   * @category HTTP Server
-   */
-  export interface HttpServer {
-    /** Gracefully close the server. No more new connections will be accepted,
-     * while pending requests will be allowed to finish.
-     */
-    shutdown(): Promise<void>;
-  }
-
-  export interface ServeUnixOptions {
-    /** The unix domain socket path to listen on. */
-    path: string;
-
-    /** An {@linkcode AbortSignal} to close the server and all connections. */
-    signal?: AbortSignal;
-
-    /** The handler to invoke when route handlers throw an error. */
-    onError?: (error: unknown) => Response | Promise<Response>;
-
-    /** The callback which is called when the server starts listening. */
-    onListen?: (params: { path: string }) => void;
-  }
-
-  /** Information for a unix domain socket HTTP request.
-   *
-   * @category HTTP Server
-   */
-  export interface ServeUnixHandlerInfo {
-    /** The remote address of the connection. */
-    remoteAddr: Deno.UnixAddr;
-  }
-
-  /** A handler for unix domain socket HTTP requests. Consumes a request and returns a response.
-   *
-   * If a handler throws, the server calling the handler will assume the impact
-   * of the error is isolated to the individual request. It will catch the error
-   * and if necessary will close the underlying connection.
-   *
-   * @category HTTP Server
-   */
-  export type ServeUnixHandler = (
-    request: Request,
-    info: ServeUnixHandlerInfo,
-  ) => Response | Promise<Response>;
-
-  /**
-   * @category HTTP Server
-   */
-  export interface ServeUnixInit {
-    /** The handler to invoke to process each incoming request. */
-    handler: ServeUnixHandler;
-  }
-
-  /** Serves HTTP requests with the given option bag and handler.
-   *
-   * You can specify the socket path with `path` option.
-   *
-   * ```ts
-   * Deno.serve(
-   *   { path: "path/to/socket" },
-   *   (_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, path: "path/to/socket" },
-   *    (_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 path/to/socket` on listening. If you like to
-   * change this behavior, you can specify a custom `onListen` callback.
-   *
-   * ```ts
-   * Deno.serve({
-   *   onListen({ path }) {
-   *     console.log(`Server started at ${path}`);
-   *     // ... more info specific to your server ..
-   *   },
-   *   path: "path/to/socket",
-   * }, (_req) => new Response("Hello, world"));
-   * ```
-   *
-   * @category HTTP Server
-   */
-  export function serve(
-    options: ServeUnixOptions,
-    handler: ServeUnixHandler,
-  ): Server;
-  /** Serves HTTP requests with the given option bag.
-   *
-   * You can specify an object with the path option, which is the
-   * unix domain socket to listen on.
-   *
-   * ```ts
-   * const ac = new AbortController();
-   *
-   * const server = Deno.serve({
-   *   path: "path/to/socket",
-   *   handler: (_req) => new Response("Hello, world"),
-   *   signal: ac.signal,
-   *   onListen({ path }) {
-   *     console.log(`Server started at ${path}`);
-   *   },
-   * });
-   * server.finished.then(() => console.log("Server closed"));
-   *
-   * console.log("Closing server...");
-   * ac.abort();
-   * ```
-   *
-   * @category HTTP Server
-   */
-  export function serve(
-    options: ServeUnixInit & ServeUnixOptions,
-  ): Server;
-
   /**
    * A namespace containing runtime APIs available in Jupyter notebooks.
    *
diff --git a/ext/http/http_next.rs b/ext/http/http_next.rs
index db63601a0..217ae1c39 100644
--- a/ext/http/http_next.rs
+++ b/ext/http/http_next.rs
@@ -87,6 +87,11 @@ static USE_WRITEV: Lazy<bool> = Lazy::new(|| {
   false
 });
 
+// NOTE(bartlomieju): currently we don't have any unstable HTTP features,
+// but let's keep this const here, because:
+//   a) we still need to support `--unstable-http` flag to not break user's CLI;
+//   b) we might add more unstable features in the future.
+#[allow(dead_code)]
 pub const UNSTABLE_FEATURE_NAME: &str = "http";
 
 /// All HTTP/2 connections start with this byte string.
@@ -1183,16 +1188,6 @@ pub async fn op_http_close(
 
   if graceful {
     http_general_trace!("graceful shutdown");
-    // TODO(bartlomieju): replace with `state.feature_checker.check_or_exit`
-    // once we phase out `check_or_exit_with_legacy_fallback`
-    state
-      .borrow()
-      .feature_checker
-      .check_or_exit_with_legacy_fallback(
-        UNSTABLE_FEATURE_NAME,
-        "Deno.Server.shutdown",
-      );
-
     // In a graceful shutdown, we close the listener and allow all the remaining connections to drain
     join_handle.listen_cancel_handle().cancel();
     poll_fn(|cx| join_handle.server_state.poll_complete(cx)).await;