fix: allow --inspect=localhost:0 to resolve hostnames (#34230)

## Summary

Node accepts hostnames in `--inspect=...`, `--inspect-port=...`, and
`inspector.open(port, host)`, resolving them via DNS. Deno's inspector
flag parser and `op_inspector_open` only accepted IP-literal hosts, so
`--inspect=localhost:0` failed at parse time.

- Resolve hostnames via `ToSocketAddrs` in `inspect_value_parser` and
  `op_inspector_open`, preferring IPv4 results to match Node's resolver.
- Add `op_inspector_port`. The `process.debugPort` getter consults it
  so userland sees the ephemeral port chosen by `--inspect=...:0`. An
  explicit `process.debugPort = N` assignment still wins, matching
  Node's mutable semantics.
- For `--inspect-port=N` used without `--inspect[-brk|-wait]`, Node
  updates `process.debugPort` but does not start the inspector. Deno
  doesn't surface `--inspect-port` as a runtime flag, so the node_shim
  translator injects the equivalent `process.debugPort = N;` assignment
  into the eval code used by `-p`/`-e`.
- Enables `parallel/test-inspector-port-zero.js` in the node_compat
  config.

Closes denoland/orchid#142

## Test plan

- New unit test `inspect_value_parser_resolves_hostnames` in
  `cli/args/flags.rs` covers `localhost:0`, `localhost:1234`, and
  `localhost`.
- New unit tests in `libs/node_shim/lib.rs`
  (`test_translate_inspect_port_injects_debug_port_for_print` and
  `test_translate_inspect_port_does_not_inject_when_inspector_enabled`).
-
`tests/node_compat/runner/suite/test/parallel/test-inspector-port-zero.js`
  now passes (verified across 5 consecutive runs).
- Existing inspector tests still pass:
  `test-inspector-debug-end.js`, `test-inspector-has-idle.js`,
  `test-inspector-promises.js`, `test-inspector-open.js`,
  `test-inspector-open-coverage.js`,
  `test-inspector-open-port-integer-overflow.js`.
- Existing inspector parser unit tests still pass:
  `inspect_flag_parsing`, `inspect_wait`, `inspect_default_host`,
  `inspect_publish_uid_flag_parsing`.
- `cargo clippy -p deno_node -p node_shim -p deno --bin deno --lib`
  clean.

Co-authored-by: divybot <divybot@users.noreply.github.com>
Co-authored-by: Divy Srivastava <me@littledivy.com>

Author: divybot

cli/args/flags.rs

@@ -6,6 +6,7 @@ use std::env;
 use std::ffi::OsString;
 use std::net::IpAddr;
 use std::net::SocketAddr;
+use std::net::ToSocketAddrs;
 use std::num::NonZeroU8;
 use std::num::NonZeroU32;
 use std::num::NonZeroUsize;
@@ -5710,6 +5711,26 @@ pub fn inspect_value_parser(host_and_port: &str) -> Result<SocketAddr, String> {
       .map_err(|_| format!("Invalid inspector port '{port}'"))
   }
 
+  // Resolve a host string to an IP address. IPs are returned as-is.
+  // Hostnames (e.g. "localhost") are resolved via DNS so Node's
+  // `--inspect=localhost:0` syntax works. To match Node's resolver,
+  // IPv4 results are preferred when both families are returned.
+  fn resolve_host(host: &str) -> Result<IpAddr, String> {
+    if let Ok(ip) = host.parse::<IpAddr>() {
+      return Ok(ip);
+    }
+    let addrs = (host, 0u16)
+      .to_socket_addrs()
+      .map_err(|e| format!("Invalid inspector host '{host}': {}", e))?
+      .collect::<Vec<_>>();
+    addrs
+      .iter()
+      .find(|a| a.is_ipv4())
+      .or_else(|| addrs.first())
+      .map(|a| a.ip())
+      .ok_or_else(|| format!("Could not resolve inspector host '{host}'"))
+  }
+
   let default_host: IpAddr = DEFAULT_HOST.parse().unwrap();
 
   if host_and_port.is_empty() {
@@ -5744,9 +5765,7 @@ pub fn inspect_value_parser(host_and_port: &str) -> Result<SocketAddr, String> {
       parse_port(port_part)?
     };
 
-    let host_ip = host_part
-      .parse::<IpAddr>()
-      .map_err(|e| format!("Invalid inspector host '{host_part}': {:?}", e))?;
+    let host_ip = resolve_host(host_part)?;
 
     return Ok(SocketAddr::new(host_ip, port));
   }
@@ -5756,9 +5775,7 @@ pub fn inspect_value_parser(host_and_port: &str) -> Result<SocketAddr, String> {
     return Ok(SocketAddr::new(default_host, port));
   }
 
-  let host_ip = host_and_port.parse::<IpAddr>().map_err(|e| {
-    format!("Invalid inspector host '{host_and_port}': {:?}", e)
-  })?;
+  let host_ip = resolve_host(host_and_port)?;
 
   Ok(SocketAddr::new(host_ip, DEFAULT_PORT))
 }
@@ -16235,6 +16252,27 @@ Usage: deno repl [OPTIONS] [-- [ARGS]...]\n"
     }
   }
 
+  #[test]
+  fn inspect_value_parser_resolves_hostnames() {
+    // Node accepts `--inspect=localhost:0` (and similar hostname forms);
+    // the parser should resolve them via DNS rather than rejecting.
+    let cases = [
+      ("localhost:0", 0),
+      ("localhost:1234", 1234),
+      ("localhost", 9229),
+    ];
+    for (input, expected_port) in cases {
+      let addr = inspect_value_parser(input)
+        .unwrap_or_else(|e| panic!("failed to parse {input:?}: {e}"));
+      assert_eq!(addr.port(), expected_port, "port for {input:?}");
+      assert!(
+        addr.ip().is_loopback(),
+        "expected loopback for {input:?}, got {}",
+        addr.ip()
+      );
+    }
+  }
+
   #[test]
   fn inspect_publish_uid_flag_parsing() {
     // Test with both stderr and http

ext/node/lib.rs

@@ -380,6 +380,7 @@ deno_core::extension!(deno_node,
     ops::inspector::op_inspector_disconnect,
     ops::inspector::op_inspector_emit_protocol_event,
     ops::inspector::op_inspector_enabled,
+    ops::inspector::op_inspector_port,
     ops::udp::op_node_udp_bind,
     ops::udp::op_node_udp_join_multi_v4,
     ops::udp::op_node_udp_leave_multi_v4,

ext/node/ops/inspector.rs

@@ -3,6 +3,7 @@
 use std::cell::RefCell;
 use std::net::IpAddr;
 use std::net::SocketAddr;
+use std::net::ToSocketAddrs;
 use std::rc::Rc;
 
 use deno_core::GarbageCollected;
@@ -27,6 +28,30 @@ pub fn op_inspector_enabled(state: &OpState) -> bool {
   state.try_borrow::<InspectorServerUrl>().is_some()
 }
 
+/// Returns the port the inspector server is listening on, or 0 if the
+/// inspector server has not been started. Used to back Node.js'
+/// `process.debugPort` so it reflects the actual bound port (which is
+/// important when `--inspect=...:0` requests an ephemeral port).
+#[op2(fast)]
+pub fn op_inspector_port(state: &OpState) -> u32 {
+  let Some(url) = state.try_borrow::<InspectorServerUrl>() else {
+    return 0;
+  };
+  // URL looks like `ws://host:port/<uuid>` (or `wss://...`). Parse out
+  // the port. We don't depend on the `url` crate here to keep the op
+  // tiny; the format is fixed by `get_websocket_debugger_url`.
+  let s = url.0.as_str();
+  let Some(after_scheme) = s.split_once("://").map(|(_, rest)| rest) else {
+    return 0;
+  };
+  let host_and_port = after_scheme.split('/').next().unwrap_or("");
+  let port_str = match host_and_port.rsplit_once(':') {
+    Some((_, p)) => p,
+    None => return 0,
+  };
+  port_str.parse::<u16>().map(|p| p as u32).unwrap_or(0)
+}
+
 #[op2(stack_trace)]
 pub fn op_inspector_open(
   state: &mut OpState,
@@ -39,12 +64,34 @@ pub fn op_inspector_open(
   const DEFAULT_PORT: u16 = 9229;
 
   let host_ip: IpAddr = match &host {
-    Some(h) => h.parse().map_err(|e| {
-      InspectorOpenError::InvalidHost(format!(
-        "Invalid inspector host '{}': {}",
-        h, e
-      ))
-    })?,
+    Some(h) => {
+      if let Ok(ip) = h.parse::<IpAddr>() {
+        ip
+      } else {
+        // Resolve hostnames like "localhost" via DNS to match Node's
+        // `inspector.open(port, host)` behavior. Prefer IPv4 results.
+        let addrs = (h.as_str(), 0u16)
+          .to_socket_addrs()
+          .map_err(|e| {
+            InspectorOpenError::InvalidHost(format!(
+              "Invalid inspector host '{}': {}",
+              h, e
+            ))
+          })?
+          .collect::<Vec<_>>();
+        addrs
+          .iter()
+          .find(|a| a.is_ipv4())
+          .or_else(|| addrs.first())
+          .map(|a| a.ip())
+          .ok_or_else(|| {
+            InspectorOpenError::InvalidHost(format!(
+              "Could not resolve inspector host '{}'",
+              h
+            ))
+          })?
+      }
+    }
     None => DEFAULT_HOST,
   };
   let port = port.unwrap_or(DEFAULT_PORT);

ext/node/polyfills/process.ts

@@ -23,6 +23,7 @@ import {
   op_getgroups,
   op_inspector_close,
   op_inspector_enabled,
+  op_inspector_port,
   op_node_load_env_file,
   op_node_process_constrained_memory,
   op_node_process_kill,
@@ -904,8 +905,17 @@ Object.defineProperty(process, "argv0", {
  */
 // Node's default inspector port (kDefaultInspectorPort in src/node_options.h).
 let _debugPort = 9229;
+let _debugPortWasSet = false;
 Object.defineProperty(process, "debugPort", {
   get() {
+    // When the inspector is running, report the actual bound port so
+    // `--inspect=...:0` reflects the ephemeral port chosen at bind
+    // time. An explicit assignment via the setter wins over this
+    // (matching Node's mutable `process.debugPort`).
+    if (!_debugPortWasSet) {
+      const port = op_inspector_port();
+      if (port !== 0) return port;
+    }
     return _debugPort;
   },
   set(val) {
@@ -917,6 +927,7 @@ Object.defineProperty(process, "debugPort", {
       );
     }
     _debugPort = port;
+    _debugPortWasSet = true;
   },
   enumerable: true,
   configurable: true,

libs/node_shim/lib.rs

@@ -78,6 +78,10 @@ pub struct DebugOptions {
   pub inspect_publish_uid_string: String,
   pub inspect_publish_uid: InspectPublishUid,
   pub host_port: HostPort,
+  /// True when `--inspect-port` was explicitly passed. Used to make
+  /// `process.debugPort` reflect the requested port even when the
+  /// inspector itself was not enabled, matching Node's behavior.
+  pub inspect_port_explicit: bool,
 }
 
 impl Default for DebugOptions {
@@ -92,6 +96,7 @@ impl Default for DebugOptions {
       inspect_publish_uid_string: "stderr,http".to_string(),
       inspect_publish_uid: InspectPublishUid::default(),
       host_port: HostPort::default(),
+      inspect_port_explicit: false,
     }
   }
 }
@@ -2764,12 +2769,19 @@ impl OptionsParser {
     value: HostPort,
   ) {
     match name {
-      "--inspect-port" => options
-        .per_isolate
-        .per_env
-        .debug_options
-        .host_port
-        .update(&value),
+      "--inspect-port" => {
+        options
+          .per_isolate
+          .per_env
+          .debug_options
+          .host_port
+          .update(&value);
+        options
+          .per_isolate
+          .per_env
+          .debug_options
+          .inspect_port_explicit = true;
+      }
       _ => {
         // Unknown host port option
       }
@@ -3372,10 +3384,28 @@ pub fn translate_to_deno_args(
     let raw_eval_code = eval_string_for_print
       .as_ref()
       .unwrap_or(&env_opts.eval_string);
+
+    // When `--inspect-port=N` is passed without `--inspect[-brk|-wait]`,
+    // Node updates `process.debugPort` to N but does not start the
+    // inspector. Deno doesn't carry `--inspect-port` as a runtime flag,
+    // so emit an equivalent assignment as part of the eval code.
+    let raw_eval_code_owned;
+    let raw_eval_code: &str = if env_opts.debug_options.inspect_port_explicit
+      && !env_opts.debug_options.inspector_enabled
+    {
+      raw_eval_code_owned = format!(
+        "process.debugPort = {}; {}",
+        env_opts.debug_options.host_port.port, raw_eval_code
+      );
+      raw_eval_code_owned.as_str()
+    } else {
+      raw_eval_code.as_str()
+    };
+
     let eval_code = if options.wrap_eval_code {
       wrap_eval_code(raw_eval_code)
     } else {
-      raw_eval_code.clone()
+      raw_eval_code.to_string()
     };
     deno_args.push(eval_code);
 
@@ -4793,6 +4823,45 @@ mod tests {
     );
   }
 
+  #[test]
+  fn test_translate_inspect_port_injects_debug_port_for_print() {
+    // `--inspect-port=N` without `--inspect[-brk|-wait]` should make
+    // `process.debugPort` equal N — matching Node — even though Deno
+    // has no equivalent runtime flag. The translator injects the
+    // assignment into the eval code used by `-p`/`-e`.
+    let parsed =
+      parse_args(svec!["--inspect-port=0", "-p", "process.debugPort"]).unwrap();
+    let result = translate_to_deno_args(parsed, &TranslateOptions::default());
+    let eval_arg = result
+      .deno_args
+      .iter()
+      .find(|a| a.contains("process.debugPort"))
+      .expect("expected an eval arg referencing process.debugPort");
+    assert!(
+      eval_arg.contains("process.debugPort = 0"),
+      "expected process.debugPort assignment in eval arg, got: {eval_arg}"
+    );
+  }
+
+  #[test]
+  fn test_translate_inspect_port_does_not_inject_when_inspector_enabled() {
+    // When `--inspect` is also set, `process.debugPort` is updated by
+    // the inspector itself; we should not inject an assignment.
+    let parsed =
+      parse_args(svec!["--inspect=localhost:0", "-p", "process.debugPort"])
+        .unwrap();
+    let result = translate_to_deno_args(parsed, &TranslateOptions::default());
+    let eval_arg = result
+      .deno_args
+      .iter()
+      .find(|a| a.contains("process.debugPort"))
+      .expect("expected an eval arg referencing process.debugPort");
+    assert!(
+      !eval_arg.contains("process.debugPort ="),
+      "should not inject debugPort assignment, got: {eval_arg}"
+    );
+  }
+
   // ==================== Env File Options Tests ====================
 
   #[test]

tests/node_compat/config.jsonc

@@ -2334,8 +2334,7 @@
     // "parallel/test-inspector-port-zero-cluster.js": {},
     // "parallel/test-inspect-support-for-node_options.js": {},
 
-    // TODO(bartlomieju):: easy, `--inspect` flag doesn't support `localhost`
-    // "parallel/test-inspector-port-zero.js": {},
+    "parallel/test-inspector-port-zero.js": {},
     "parallel/test-inspector-promises.js": {},
     "parallel/test-inspector-reported-host.js": {},
     "parallel/test-inspector-resource-name-to-url.js": {