feat(unstable): add unix domain socket support to Deno.serve (#20759)

cli/tests/unit/net_test.ts

@@ -9,8 +9,8 @@ import {
  delay,
  execCode,
  execCode2,
+ tmpUnixSocketPath,
 } from "./test_util.ts";
-import { join } from "../../../test_util/std/path/mod.ts";
 
 // Since these tests may run in parallel, ensure this port is unique to this file
 const listenPort = 4503;
@@ -49,11 +49,6 @@ Deno.test(
  },
 );
 
-function tmpUnixSocketPath(): string {
- const folder = Deno.makeTempDirSync();
- return join(folder, "socket");
-}
-
 Deno.test(
  {
  ignore: Deno.build.os === "windows",

cli/tests/unit/serve_test.ts

@@ -15,6 +15,7 @@ import {
  deferred,
  execCode,
  fail,
+ tmpUnixSocketPath,
 } from "./test_util.ts";
 
 // Since these tests may run in parallel, ensure this port is unique to this file
@@ -3715,3 +3716,37 @@ async function curlRequestWithStdErr(args: string[]) {
  assert(success);
  return [new TextDecoder().decode(stdout), new TextDecoder().decode(stderr)];
 }
+
+Deno.test(
+ {
+ ignore: Deno.build.os === "windows",
+ permissions: { run: true, read: true, write: true },
+ },
+ async function httpServerUnixDomainSocket() {
+ const d = deferred();
+ const ac = new AbortController();
+ const filePath = tmpUnixSocketPath();
+ const server = Deno.serve(
+ {
+ signal: ac.signal,
+ path: filePath,
+ onListen(info) {
+ d.resolve(info);
+ },
+ onError: createOnErrorCb(ac),
+ },
+ (_req, { remoteAddr }) => {
+ assertEquals(remoteAddr, { path: filePath, transport: "unix" });
+ return new Response("hello world!");
+ },
+ );
+
+ assertEquals(await d, { path: filePath });
+ assertEquals(
+ "hello world!",
+ await curlRequest(["--unix-socket", filePath, "https://localhost"]),
+ );
+ ac.abort();
+ await server.finished;
+ },
+);

cli/tests/unit/test_util.ts

@@ -2,7 +2,7 @@
 
 import * as colors from "../../../test_util/std/fmt/colors.ts";
 export { colors };
-import { resolve } from "../../../test_util/std/path/mod.ts";
+import { join, resolve } from "../../../test_util/std/path/mod.ts";
 export {
  assert,
  assertEquals,
@@ -81,3 +81,8 @@ export function execCode2(code: string) {
  },
  };
 }
+
+export function tmpUnixSocketPath(): string {
+ const folder = Deno.makeTempDirSync();
+ return join(folder, "socket");
+}

cli/tsc/dts/lib.deno.unstable.d.ts

@@ -1948,6 +1948,127 @@ declare namespace Deno {
  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.
  *

ext/http/00_serve.js

@@ -34,11 +34,12 @@ import {
  ReadableStreamPrototype,
  resourceForReadableStream,
 } from "ext:deno_web/06_streams.js";
-import { listen, TcpConn } from "ext:deno_net/01_net.js";
+import { listen, listenOptionApiName, TcpConn } from "ext:deno_net/01_net.js";
 import { listenTls } from "ext:deno_net/02_tls.js";
 const {
  ArrayPrototypePush,
  Error,
+ ObjectHasOwn,
  ObjectPrototypeIsPrototypeOf,
  PromisePrototypeCatch,
  Symbol,
@@ -272,6 +273,13 @@ class InnerRequest {
  }
 
  get remoteAddr() {
+ const transport = this.#context.listener?.addr.transport;
+ if (transport === "unix" || transport === "unixpacket") {
+ return {
+ transport,
+ path: this.#context.listener.addr.path,
+ };
+ }
  if (this.#methodAndUri === undefined) {
  if (this.#slabId === undefined) {
  throw new TypeError("request closed");
@@ -337,8 +345,9 @@ class CallbackContext {
  serverRid;
  closed;
  closing;
+ listener;
 
- constructor(signal, args) {
+ constructor(signal, args, listener) {
  // The abort signal triggers a non-graceful shutdown
  signal?.addEventListener(
  "abort",
@@ -352,6 +361,7 @@ class CallbackContext {
  this.scheme = args[1];
  this.fallbackHost = args[2];
  this.closed = false;
+ this.listener = listener;
  }
 
  close() {
@@ -519,11 +529,29 @@ function serve(arg1, arg2) {
  }
 
  const wantsHttps = options.cert || options.key;
+ const wantsUnix = ObjectHasOwn(options, "path");
  const signal = options.signal;
  const onError = options.onError ?? function (error) {
  console.error(error);
  return internalServerError();
  };
+
+ if (wantsUnix) {
+ const listener = listen({
+ transport: "unix",
+ path: options.path,
+ [listenOptionApiName]: "Deno.serve",
+ });
+ const path = listener.addr.path;
+ return serveHttpOnListener(listener, signal, handler, onError, () => {
+ if (options.onListen) {
+ options.onListen({ path });
+ } else {
+ console.log(`Listening on ${path}`);
+ }
+ });
+ }
+
  const listenOpts = {
  hostname: options.hostname ?? "0.0.0.0",
  port: options.port ?? 8000,
@@ -581,7 +609,11 @@ function serve(arg1, arg2) {
  * Serve HTTP/1.1 and/or HTTP/2 on an arbitrary listener.
  */
 function serveHttpOnListener(listener, signal, handler, onError, onListen) {
- const context = new CallbackContext(signal, op_http_serve(listener.rid));
+ const context = new CallbackContext(
+ signal,
+ op_http_serve(listener.rid),
+ listener,
+ );
  const callback = mapToCallback(context, handler, onError);
 
  onListen(context.scheme);
@@ -593,7 +625,11 @@ function serveHttpOnListener(listener, signal, handler, onError, onListen) {
  * Serve HTTP/1.1 and/or HTTP/2 on an arbitrary connection.
  */
 function serveHttpOnConnection(connection, signal, handler, onError, onListen) {
- const context = new CallbackContext(signal, op_http_serve_on(connection.rid));
+ const context = new CallbackContext(
+ signal,
+ op_http_serve_on(connection.rid),
+ null,
+ );
  const callback = mapToCallback(context, handler, onError);
 
  onListen(context.scheme);

ext/net/01_net.js

@@ -19,6 +19,7 @@ const {
  ObjectPrototypeIsPrototypeOf,
  PromiseResolve,
  SymbolAsyncIterator,
+ Symbol,
  SymbolFor,
  TypeError,
  TypedArrayPrototypeSubarray,
@@ -416,6 +417,8 @@ class Datagram {
  }
 }
 
+const listenOptionApiName = Symbol("listenOptionApiName");
+
 function listen(args) {
  switch (args.transport ?? "tcp") {
  case "tcp": {
@@ -427,7 +430,10 @@ function listen(args) {
  return new Listener(rid, addr);
  }
  case "unix": {
- const { 0: rid, 1: path } = ops.op_net_listen_unix(args.path);
+ const { 0: rid, 1: path } = ops.op_net_listen_unix(
+ args.path,
+ args[listenOptionApiName] ?? "Deno.listen",
+ );
  const addr = {
  transport: "unix",
  path,
@@ -505,6 +511,7 @@ export {
  Datagram,
  listen,
  Listener,
+ listenOptionApiName,
  resolveDns,
  shutdown,
  TcpConn,

ext/net/ops_unix.rs

@@ -194,15 +194,17 @@ where
 pub fn op_net_listen_unix<NP>(
  state: &mut OpState,
  #[string] path: String,
+ #[string] api_name: String,
 ) -> Result<(ResourceId, Option<String>), AnyError>
 where
  NP: NetPermissions + 'static,
 {
  let address_path = Path::new(&path);
- super::check_unstable(state, "Deno.listen");
+ super::check_unstable(state, &api_name);
  let permissions = state.borrow_mut::<NP>();
- permissions.check_read(address_path, "Deno.listen()")?;
- permissions.check_write(address_path, "Deno.listen()")?;
+ let api_call_expr = format!("{}()", api_name);
+ permissions.check_read(address_path, &api_call_expr)?;
+ permissions.check_write(address_path, &api_call_expr)?;
  let listener = UnixListener::bind(address_path)?;
  let local_addr = listener.local_addr()?;
  let pathname = local_addr.as_pathname().map(pathstring).transpose()?;