BREAKING(http/server): deprecate serve and serveTls (denoland#3381)

examples/curl_test.ts

@@ -1,5 +1,4 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
-import { serve } from "../http/server.ts";
 import { assertStrictEquals } from "../assert/mod.ts";
 import { dirname, fromFileUrl } from "../path/mod.ts";
 
@@ -9,10 +8,10 @@ Deno.test({
   name: "[examples/curl] send a request to a specified url",
   fn: async () => {
     const abortController = new AbortController();
-    const serverPromise = serve(
-      () => new Response("Hello world"),
+    const serverPromise = Deno.serve(
       { signal: abortController.signal, port: 8081 },
-    );
+      () => new Response("Hello world"),
+    ).finished;
     const decoder = new TextDecoder();
     const command = new Deno.Command(Deno.execPath(), {
       args: [

http/etag.ts

@@ -118,12 +118,11 @@ export async function calculate(
  *   calculate,
  *   ifMatch,
  * } from "https://deno.land/std@$STD_VERSION/http/etag.ts";
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  * import { assert } from "https://deno.land/std@$STD_VERSION/assert/assert.ts"
  *
  * const body = "hello deno!";
  *
- * await serve(async (req) => {
+ * Deno.serve(async (req) => {
  *   const ifMatchValue = req.headers.get("if-match");
  *   const etag = await calculate(body);
  *   assert(etag);
@@ -162,12 +161,11 @@ export function ifMatch(
  *   calculate,
  *   ifNoneMatch,
  * } from "https://deno.land/std@$STD_VERSION/http/etag.ts";
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  * import { assert } from "https://deno.land/std@$STD_VERSION/assert/assert.ts"
  *
  * const body = "hello deno!";
  *
- * await serve(async (req) => {
+ * Deno.serve(async (req) => {
  *   const ifNoneMatchValue = req.headers.get("if-none-match");
  *   const etag = await calculate(body);
  *   assert(etag);

http/file_server.ts

@@ -40,7 +40,6 @@ import {
   SEP_PATTERN,
 } from "../path/mod.ts";
 import { contentType } from "../media_types/content_type.ts";
-import { serve, serveTls } from "./server.ts";
 import { calculate, ifNoneMatch } from "./etag.ts";
 import { isRedirectStatus, Status } from "./http_status.ts";
 import { ByteSliceStream } from "../streams/byte_slice_stream.ts";
@@ -545,10 +544,9 @@ export interface ServeDirOptions {
  * Serves the files under the given directory root (opts.fsRoot).
  *
  * ```ts
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  * import { serveDir } from "https://deno.land/std@$STD_VERSION/http/file_server.ts";
  *
- * serve((req) => {
+ * Deno.serve((req) => {
  *   const pathname = new URL(req.url).pathname;
  *   if (pathname.startsWith("/static")) {
  *     return serveDir(req, {
@@ -772,14 +770,17 @@ function main() {
   const useTls = !!(keyFile && certFile);
 
   if (useTls) {
-    serveTls(handler, {
+    Deno.serve({
       port,
       hostname: host,
-      certFile,
-      keyFile,
-    });
+      cert: Deno.readTextFileSync(certFile),
+      key: Deno.readTextFileSync(keyFile),
+    }, handler);
   } else {
-    serve(handler, { port, hostname: host });
+    Deno.serve({
+      port,
+      hostname: host,
+    }, handler);
   }
 }
 

http/mod.ts

@@ -3,19 +3,6 @@
  * Provides user-friendly {@linkcode serve} on top of Deno's native HTTP server
  * and other utilities for creating HTTP servers and clients.
  *
- * ## Server
- *
- * Server APIs utilizing Deno's
- * [HTTP server APIs](https://deno.land/manual/runtime/http_server_apis#http-server-apis).
- *
- * ```ts
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
- *
- * serve(() => new Response("Hello World\n"));
- *
- * console.log("http://localhost:8000/");
- * ```
- *
  * ## File Server
  *
  * A small program for serving local files over HTTP.
@@ -64,9 +51,8 @@
  *
  * ```ts
  * import { UserAgent } from "https://deno.land/std@$STD_VERSION/http/user_agent.ts";
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  *
- * serve((req) => {
+ * Deno.serve((req) => {
  *   const userAgent = new UserAgent(req.headers.get("user-agent") ?? "");
  *   return new Response(`Hello, ${userAgent.browser.name}
  *     on ${userAgent.os.name} ${userAgent.os.version}!`);

http/server.ts

@@ -16,7 +16,9 @@ const INITIAL_ACCEPT_BACKOFF_DELAY = 5;
 /** Max backoff delay of 1s following a temporary accept failure. */
 const MAX_ACCEPT_BACKOFF_DELAY = 1000;
 
-/** Information about the connection a request arrived on. */
+/**
+ * Information about the connection a request arrived on.
+ */
 export interface ConnInfo {
   /** The local address of the connection. */
   readonly localAddr: Deno.Addr;
@@ -37,7 +39,9 @@ export type Handler = (
   connInfo: ConnInfo,
 ) => Response | Promise<Response>;
 
-/** Options for running an HTTP server. */
+/**
+ * Options for running an HTTP server.
+ */
 export interface ServerInit extends Partial<Deno.ListenOptions> {
   /** The handler to invoke for individual HTTP requests. */
   handler: Handler;
@@ -50,7 +54,9 @@ export interface ServerInit extends Partial<Deno.ListenOptions> {
   onError?: (error: unknown) => Response | Promise<Response>;
 }
 
-/** Used to construct an HTTP server. */
+/**
+ * Used to construct an HTTP server.
+ */
 export class Server {
   #port?: number;
   #host?: string;
@@ -483,7 +489,11 @@ export class Server {
   }
 }
 
-/** Additional serve options. */
+/**
+ * @deprecated (will be removed after 1.0.0) Use `Deno.ServeInit` instead.
+ *
+ * Additional serve options.
+ */
 export interface ServeInit extends Partial<Deno.ListenOptions> {
   /** An AbortSignal to close the server and all connections. */
   signal?: AbortSignal;
@@ -495,6 +505,20 @@ export interface ServeInit extends Partial<Deno.ListenOptions> {
   onListen?: (params: { hostname: string; port: number }) => void;
 }
 
+/**
+ * Additional serve listener options.
+ */
+export interface ServeListenerOptions {
+  /** An 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 started listening */
+  onListen?: (params: { hostname: string; port: number }) => void;
+}
+
 /**
  * Constructs a server, accepts incoming connections on the given listener, and
  * handles requests on these connections with the given handler.
@@ -522,7 +546,7 @@ export interface ServeInit extends Partial<Deno.ListenOptions> {
 export async function serveListener(
   listener: Deno.Listener,
   handler: Handler,
-  options?: Omit<ServeInit, "port" | "hostname">,
+  options?: ServeListenerOptions,
 ) {
   const server = new Server({ handler, onError: options?.onError });
 
@@ -540,7 +564,10 @@ function hostnameForDisplay(hostname: string) {
   return hostname === "0.0.0.0" ? "localhost" : hostname;
 }
 
-/** Serves HTTP requests with the given handler.
+/**
+ * @deprecated (will be removed after 1.0.0) Use `Deno.serve` instead.
+ *
+ * Serves HTTP requests with the given 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 "0.0.0.0".
@@ -620,6 +647,9 @@ export async function serve(
   return await s;
 }
 
+/**
+ * @deprecated (will be removed after 1.0.0) Use `Deno.ServeTlsOptions` instead.
+ */
 export interface ServeTlsInit extends ServeInit {
   /** Server private key in PEM format */
   key?: string;
@@ -634,7 +664,10 @@ export interface ServeTlsInit extends ServeInit {
   certFile?: string;
 }
 
-/** Serves HTTPS requests with the given handler.
+/**
+ * @deprecated (will be removed after 1.0.0) Use `Deno.serve` instead.
+ *
+ * Serves HTTPS requests with the given handler.
  *
  * You must specify `key` or `keyFile` and `cert` or `certFile` options.
  *

http/server_sent_event.ts

@@ -21,9 +21,8 @@
  *   ServerSentEvent,
  *   ServerSentEventStreamTarget,
  * } from "https://deno.land/std@$STD_VERSION/http/server_sent_event.ts";
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  *
- * await serve((request) => {
+ * Deno.serve({ port: 8000 }, (request) => {
  *   const target = new ServerSentEventStreamTarget();
  *   let counter = 0;
  *
@@ -38,7 +37,7 @@
  *
  *   target.addEventListener("close", () => clearInterval(id));
  *   return target.asResponse();
- * }, { port: 8000 });
+ * });
  * ```
  *
  * @module
@@ -101,17 +100,16 @@ class CloseEvent extends Event {
  *   ServerSentEvent,
  *   ServerSentEventStreamTarget,
  * } from "https://deno.land/std@$STD_VERSION/http/server_sent_event.ts";
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  *
- * await serve((request) => {
+ * Deno.serve({ port: 8000 }, (request) => {
  *   const target = new ServerSentEventStreamTarget();
  *   const evt = new ServerSentEvent("message", {
  *     data: { hello: "world" },
  *     id: 1
  *   });
  *   target.dispatchEvent(evt);
  *   return target.asResponse();
- * }, { port: 8000 });
+ * });
  * ```
  */
 export class ServerSentEvent extends Event {
@@ -189,13 +187,12 @@ export interface ServerSentEventTarget extends EventTarget {
    *
    * ```ts
    * import { ServerSentEventStreamTarget } from "https://deno.land/std@$STD_VERSION/http/server_sent_event.ts";
-   * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    *
-   * await serve((request) => {
+   * Deno.serve({ port: 8000 }, (request) => {
    *   const target = new ServerSentEventStreamTarget();
    *   target.dispatchComment("this is a comment");
    *   return target.asResponse();
-   * }, { port: 8000 });
+   * });
    * ```
    */
   dispatchComment(comment: string): boolean;
@@ -217,14 +214,13 @@ export interface ServerSentEventTarget extends EventTarget {
    *   ServerSentEvent,
    *   ServerSentEventStreamTarget,
    * } from "https://deno.land/std@$STD_VERSION/http/server_sent_event.ts";
-   * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    *
-   * await serve((request) => {
+   * Deno.serve({ port: 8000 }, (request) => {
    *   const target = new ServerSentEventStreamTarget();
    *   const evt = new ServerSentEvent("ping", { data: "hello" });
    *   target.dispatchEvent(evt);
    *   return target.asResponse();
-   * }, { port: 8000 });
+   * });
    * ```
    */
   dispatchEvent(event: ServerSentEvent): boolean;
@@ -241,14 +237,13 @@ export interface ServerSentEventTarget extends EventTarget {
    *   ServerSentEvent,
    *   ServerSentEventStreamTarget,
    * } from "https://deno.land/std@$STD_VERSION/http/server_sent_event.ts";
-   * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    *
-   * await serve((request) => {
+   * Deno.serve({ port: 8000 }, (request) => {
    *   const target = new ServerSentEventStreamTarget();
    *   const evt = new ServerSentEvent("ping", { data: "hello" });
    *   target.dispatchEvent(evt);
    *   return target.asResponse();
-   * }, { port: 8000 });
+   * });
    * ```
    */
   dispatchEvent(event: CloseEvent | ErrorEvent): boolean;

http/testdata/file_server_as_library.ts

@@ -1,6 +1,8 @@
-import { serve } from "../server.ts";
 import { serveFile } from "../file_server.ts";
 
-serve((req) => {
-  return serveFile(req, "./testdata/hello.html");
-}, { port: 8000, onListen: () => console.log("Server running...") });
+Deno.serve(
+  { port: 8000, onListen: () => console.log("Server running...") },
+  (req) => {
+    return serveFile(req, "./testdata/hello.html");
+  },
+);

http/user_agent.ts

@@ -983,9 +983,8 @@ export class UserAgent {
    *
    * ```ts
    * import { UserAgent } from "https://deno.land/std@$STD_VERSION/http/user_agent.ts";
-   * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    *
-   * serve((req) => {
+   * Deno.serve((req) => {
    *   const userAgent = new UserAgent(req.headers.get("user-agent") ?? "");
    *   return new Response(`Hello, ${userAgent.browser.name}
    *     on ${userAgent.os.name} ${userAgent.os.version}!`);

json/json_stringify_stream.ts

@@ -56,11 +56,10 @@ export interface StringifyStreamOptions {
  * @example
  * If you want to stream [JSON lines](https://jsonlines.org/) from the server:
  * ```ts
- * import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
  * import { JsonStringifyStream } from "https://deno.land/std@$STD_VERSION/json/json_stringify_stream.ts";
  *
  * // A server that streams one line of JSON every second
- * serve(() => {
+ * Deno.serve(() => {
  *   let intervalId: number | undefined;
  *   const readable = new ReadableStream({
  *     start(controller) {