test(dgram): expand granular Node parity coverage

test-parity/node-suite/dgram/STATUS.md

@@ -0,0 +1,81 @@
+# `node:dgram` granular parity status
+
+## Upstream evidence
+
+This expansion was reassessed against primary repositories on 2026-07-16:
+
+- Node.js [`608112af`](https://github.com/nodejs/node/tree/608112affae2cf44d2f8a0a6bfe7967193b459c8/test): 82 `test-dgram*` files in `test/parallel` and `test/sequential`.
+- Deno [`f8a17c81`](https://github.com/denoland/deno/blob/f8a17c8171569fa2870d740030aaa59c91fdf9ee/tests/node_compat/config.jsonc): 69 selected `parallel/test-dgram*` or `sequential/test-dgram*` entries.
+- Bun [`c4fad462`](https://github.com/oven-sh/bun/tree/c4fad462e7dc20e5e9780f848db42e1e2f52186d/test/js/node): 68 copied upstream `test-dgram*` files plus Bun's focused `node-dgram.test.js`.
+
+The Perry fixtures are diagnostic adaptations, not verbatim copies. They use ephemeral ports, loopback addresses, sequential round trips, and deterministic summaries rather than upstream harness helpers or fixed ports.
+
+| Perry area | Representative Node files | Deno selection | Bun copy |
+| --- | --- | --- | --- |
+| socket and send validation | `test-dgram-createSocket-type.js`, `test-dgram-send-bad-arguments.js`, `test-dgram-send-invalid-msg-type.js` | all 3 | send cases (2/3) |
+| bind and close lifecycle | `test-dgram-bind.js`, `test-dgram-bind-error-repeat.js`, `test-dgram-close.js` | all 3 | all 3 |
+| AbortSignal | `test-dgram-close-signal.js`, `test-dgram-abort-closed.js` | both | both |
+| connection state | `test-dgram-connect.js` | selected | copied |
+| send overloads and byte counts | `test-dgram-send-callback-buffer.js`, `test-dgram-bytes-length.js`, `test-dgram-connect-send-callback-buffer.js` | all 3 | all 3 |
+| omitted host | `test-dgram-send-default-host.js`, `test-dgram-connect-send-default-host.js` | both | both |
+| empty and multiple sends | `test-dgram-send-empty-buffer.js`, `test-dgram-send-empty-array.js`, `test-dgram-implicit-bind.js` | all 3 (empty buffer is Darwin-disabled/flaky) | all 3 |
+| callback timing | `test-dgram-send-callback-recursive.js` | selected | copied |
+| queue and reference state | `test-dgram-send-queue-info.js`, `test-dgram-ref.js`, `test-dgram-unref.js` | ref/unref (2/3) | ref/unref (2/3) |
+| address and connected-send validation | `test-dgram-send-address-types.js`, `test-dgram-send-bad-arguments.js` | both | both |
+| legacy and advanced send forms | `test-dgram-sendto.js`, `test-dgram-send-callback-buffer-length.js`, `test-dgram-send-callback-multi-buffer.js` | all 3 | all 3 |
+| lookup, errors, and blocking | `test-dgram-custom-lookup.js`, `test-dgram-send-error.js`, `test-dgram-send-cb-quelches-error.js`, `test-dgram-blocklist.js` | lookup/error cases (3/4) | lookup/error cases (3/4) |
+| close, bind conflict, and disposal | `test-dgram-close-is-not-callback.js`, `test-dgram-bind-error-repeat.js`, `test-dgram-async-dispose.mjs` | all 3 | all 3 |
+| controls and buffer metrics | `test-dgram-setTTL.js`, `test-dgram-multicast-setTTL.js`, `test-dgram-socket-buffer-size.js`, `test-dgram-createSocket-type.js` | TTL/create options (3/4) | TTL cases (2/4) |
+| constructor message listener | `test-dgram-udp4.js` | selected | copied |
+
+## Current coverage
+
+The directory contains 38 fixtures: the original 4 broad cases and 34 granular cases added in this expansion.
+
+- `validation/`: socket-type/options matrices, message/list/address validation, connected-send guards, DataView/scatter-gather delivery, legacy `sendto()`, port errors, and offset/length bounds.
+- `lifecycle/`: default/port/options bind overloads, bind conflicts and retry state, custom lookup, close arguments and ordering, async-dispose shape, AbortSignal validation, and post-close abort behavior.
+- `connection/`: invalid ports, pending/connected state guards, disconnect errors, reconnect state, and connect event/callback ordering.
+- `send/`: unconnected and connected overloads, implicit binding, constructor listeners, default address/host behavior, empty buffers/arrays and multiple sends, buffer ranges, block lists, DNS error routing, callback byte counts, and callback asynchrony.
+- `metrics/`: constructor and setter buffer sizes, queue metrics, and `ref()`/`unref()` identity before bind, after bind, and after close.
+- `control/`: deterministic TTL boundary validation.
+- Existing broad cases retain unicast loopback, import/API shape, socket controls, and multicast membership coverage.
+
+The clean Node 26.5.0 focused baseline run is 18/38 parity passes with 20 stable output differences and no compile failures, runtime errors, or skipped fixtures. The differences diagnose:
+
+1. Repeated `connect()` calls and connected range/destination overloads miss `ERR_SOCKET_DGRAM_IS_CONNECTED` guards.
+2. Invalid `signal`, `lookup`, buffer-size, and address options/arguments are accepted.
+3. Successful `send()` callbacks run synchronously.
+4. `sendto()` lacks Node-coded argument errors, scatter-gather and empty arrays are rejected, and buffer offset/length bounds are ignored.
+5. `Symbol.asyncDispose`, custom lookup dispatch, and send block lists are not implemented.
+6. Constructor buffer sizes are ignored, failed binds leave `address()` reporting `EBADF`, and `close` callback/event ordering differs.
+7. `close()` does not return the socket, an empty address is treated as a DNS name, and multicast TTL handles `Infinity` differently.
+
+The work was exercised in coherent batches. The first pass covered core validation, bind/connect lifecycle, basic overloads, callbacks, queue/ref metrics, and AbortSignal. Later batches added 23 cases selected from the larger Node/Deno/Bun corpora: address and advanced-option validation, legacy and connected send forms, custom lookup, close/dispose behavior, bind conflicts and retries, block lists, DNS error routing, buffer metrics/options, TTL boundaries, constructor listeners, message-view/scatter-gather behavior, bounds validation, empty arrays, and implicit-bind state.
+
+## Stopping judgment and exclusions
+
+Further upstream ports were stopped where they would duplicate the cases above or cross into a separate runtime/platform feature:
+
+- **Separate runtime work:** Node's new `bindSync()`/`connectSync()`, descriptor/handle binding, active/pre-aborted signal closure, and repeated bind/close states beyond the deterministic conflict/retry and ordering cases. Surface diagnostics for async disposal, block lists, custom lookup, ranges, and scatter-gather now remain in the suite.
+- **Platform/slow assessment:** `reusePort`, shared ports, cluster/child-process handle transfer, IPv6 loopback/link-local/interface-specific cases without a capability guard, multicast interface/loopback variants, and source-specific multicast beyond the existing smoke fixture.
+- **Kernel-sensitive errors:** message-size, out-of-band buffer, receive errors, implicit-bind failure, and address-specific OS error text.
+- **Scheduler-sensitive races:** close during bind/lookup/listening, recursive send callbacks, error-quelching races, burst close behavior, ping-pong stress, and unref/cluster process-liveness tests.
+- **Redundant upstream variants:** the many connected/unconnected callback, empty-packet, default-host, buffer, typed-array, and multiple-send files are represented by smaller grouped fixtures here.
+
+These exclusions keep the default granular lane deterministic on loopback while preserving the 20 actionable Perry differences as focused regression targets.
+
+## Verification
+
+```text
+NODE_BIN=/tmp/node-v26.5.0/bin/node \
+python3 scripts/node_suite_run.py "$PWD/target/release/perry" "$PWD" dgram
+
+dgram  18  38  47.4  diff=20
+
+cargo fmt --all -- --check
+./scripts/check_file_size.sh
+python3 -m json.tool test-parity/node_suite_baseline.json
+git diff --check
+```
+
+No wider module run is required for this module floor: the executable changes are confined to `node-suite/dgram`, and the baseline runner was measured directly against all 38 dgram fixtures. Aggregate metadata remains the last clean full-suite snapshot.

test-parity/node-suite/dgram/connection/connect-ordering.ts

@@ -0,0 +1,24 @@
+import * as dgram from "node:dgram";
+
+const receiver = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => receiver.bind(0, "127.0.0.1", resolve));
+
+const sender = dgram.createSocket("udp4");
+const order: string[] = [];
+sender.once("connect", () => order.push("event"));
+
+await new Promise<void>((resolve) => {
+  sender.connect(receiver.address().port, "127.0.0.1", () => {
+    order.push("callback");
+    resolve();
+  });
+});
+
+const remote = sender.remoteAddress();
+console.log("connect order:", order.join(","));
+console.log("remote:", remote.address, remote.family, remote.port === receiver.address().port);
+
+await Promise.all([
+  new Promise<void>((resolve) => sender.close(resolve)),
+  new Promise<void>((resolve) => receiver.close(resolve)),
+]);

test-parity/node-suite/dgram/connection/state-transitions.ts

@@ -0,0 +1,47 @@
+import * as dgram from "node:dgram";
+
+function codeOf(fn: () => unknown): string {
+  try {
+    fn();
+    return "none";
+  } catch (error: unknown) {
+    return (error as { code?: string }).code ?? "Error";
+  }
+}
+
+const socket = dgram.createSocket("udp4");
+const firstPeer = dgram.createSocket("udp4");
+const secondPeer = dgram.createSocket("udp4");
+await Promise.all([
+  new Promise<void>((resolve) => firstPeer.bind(0, "127.0.0.1", () => resolve())),
+  new Promise<void>((resolve) => secondPeer.bind(0, "127.0.0.1", () => resolve())),
+]);
+const firstPort = firstPeer.address().port;
+const secondPort = secondPeer.address().port;
+
+console.log("disconnect before connect:", codeOf(() => socket.disconnect()));
+console.log("bad ports:", [0, -1, 65536].map((port) => codeOf(() => socket.connect(port))).join(","));
+
+const firstConnect = new Promise<void>((resolve) => {
+  socket.connect(firstPort, "127.0.0.1", () => resolve());
+});
+console.log("connect while pending:", codeOf(() => socket.connect(firstPort)));
+await firstConnect;
+
+let remote = socket.remoteAddress();
+console.log("first remote:", remote.address, remote.family, remote.port === firstPort);
+console.log("connect while connected:", codeOf(() => socket.connect(secondPort)));
+console.log("disconnect result:", socket.disconnect());
+console.log("remote after disconnect:", codeOf(() => socket.remoteAddress()));
+console.log("repeat disconnect:", codeOf(() => socket.disconnect()));
+
+await new Promise<void>((resolve) => {
+  socket.connect(secondPort, "127.0.0.1", () => resolve());
+});
+remote = socket.remoteAddress();
+console.log("reconnected remote:", remote.address, remote.family, remote.port === secondPort);
+await Promise.all([
+  new Promise<void>((resolve) => socket.close(() => resolve())),
+  new Promise<void>((resolve) => firstPeer.close(() => resolve())),
+  new Promise<void>((resolve) => secondPeer.close(() => resolve())),
+]);

test-parity/node-suite/dgram/control/ttl-validation.ts

@@ -0,0 +1,26 @@
+import * as dgram from "node:dgram";
+
+function codeOf(fn: () => unknown): string {
+  try {
+    fn();
+    return "none";
+  } catch (error: unknown) {
+    return (error as { code?: string }).code ?? "Error";
+  }
+}
+
+const socket = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => socket.bind(0, "127.0.0.1", () => resolve()));
+
+console.log(
+  "ttl invalid:",
+  [0, 256, Infinity, "64"].map((value) => codeOf(() => socket.setTTL(value as never))).join(","),
+);
+console.log(
+  "multicast ttl invalid:",
+  [-1, 256, Infinity, "64"]
+    .map((value) => codeOf(() => socket.setMulticastTTL(value as never)))
+    .join(","),
+);
+console.log("ttl valid:", socket.setTTL(64), socket.setMulticastTTL(0));
+await new Promise<void>((resolve) => socket.close(() => resolve()));

test-parity/node-suite/dgram/lifecycle/abort-signal.ts

@@ -0,0 +1,25 @@
+import * as dgram from "node:dgram";
+
+let invalidSignalSocket: dgram.Socket | undefined;
+function invalidSignalResult(): string {
+  try {
+    invalidSignalSocket = dgram.createSocket({ type: "udp4", signal: {} as AbortSignal });
+    return "accepted";
+  } catch (error: unknown) {
+    return (error as { code?: string }).code ?? "Error";
+  }
+}
+
+console.log("invalid signal:", invalidSignalResult());
+if (invalidSignalSocket) {
+  await new Promise<void>((resolve) => invalidSignalSocket!.close(() => resolve()));
+}
+
+const controller = new AbortController();
+const socket = dgram.createSocket({ type: "udp4", signal: controller.signal });
+let closes = 0;
+socket.on("close", () => closes++);
+await new Promise<void>((resolve) => socket.close(() => resolve()));
+controller.abort();
+await new Promise<void>((resolve) => queueMicrotask(resolve));
+console.log("abort after close:", closes);

test-parity/node-suite/dgram/lifecycle/async-dispose-shape.ts

@@ -0,0 +1,8 @@
+import * as dgram from "node:dgram";
+
+const socket = dgram.createSocket("udp4");
+console.log(
+  "async dispose:",
+  typeof (socket as unknown as Record<symbol, unknown>)[Symbol.asyncDispose],
+);
+await new Promise<void>((resolve) => socket.close(() => resolve()));

test-parity/node-suite/dgram/lifecycle/bind-conflict.ts

@@ -0,0 +1,16 @@
+import * as dgram from "node:dgram";
+
+const first = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => first.bind(0, "127.0.0.1", () => resolve()));
+
+const second = dgram.createSocket("udp4");
+const error = new Promise<string>((resolve) => {
+  second.once("error", (value) => resolve(`${value.code}:${value.syscall}`));
+});
+second.bind(first.address().port, "127.0.0.1");
+console.log("bind conflict:", await error);
+
+await Promise.all([
+  new Promise<void>((resolve) => first.close(() => resolve())),
+  new Promise<void>((resolve) => second.close(() => resolve())),
+]);

test-parity/node-suite/dgram/lifecycle/bind-error-retry.ts

@@ -0,0 +1,33 @@
+import * as dgram from "node:dgram";
+
+const owner = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => owner.bind(0, "127.0.0.1", resolve));
+
+const candidate = dgram.createSocket("udp4");
+const results: string[] = [];
+
+for (let attempt = 0; attempt < 2; attempt++) {
+  const result = await new Promise<string>((resolve) => {
+    candidate.once("error", (value) => {
+      const error = value as Error & { code?: string; syscall?: string };
+      resolve(`${error.code}:${error.syscall}`);
+    });
+    candidate.bind(owner.address().port, "127.0.0.1", () => resolve("listening"));
+  });
+  results.push(result);
+  if (result === "listening") break;
+}
+
+console.log("retry results:", results.join(","));
+let addressState: string;
+try {
+  addressState = `port-${candidate.address().port}`;
+} catch (error: unknown) {
+  addressState = (error as { code?: string }).code ?? "Error";
+}
+console.log("address after errors:", addressState);
+
+await Promise.all([
+  new Promise<void>((resolve) => owner.close(resolve)),
+  new Promise<void>((resolve) => candidate.close(resolve)),
+]);

test-parity/node-suite/dgram/lifecycle/bind-overloads.ts

@@ -0,0 +1,28 @@
+import * as dgram from "node:dgram";
+
+for (const mode of ["default", "port", "options"] as const) {
+  const socket = dgram.createSocket("udp4");
+
+  await new Promise<void>((resolve) => {
+    function onListening(this: dgram.Socket) {
+      const address = socket.address();
+      console.log(
+        mode,
+        address.address,
+        address.family,
+        typeof address.port,
+        address.port > 0,
+        this === socket,
+      );
+      socket.close(() => resolve());
+    }
+
+    if (mode === "default") {
+      socket.bind(onListening);
+    } else if (mode === "port") {
+      socket.bind(0, onListening);
+    } else {
+      socket.bind({ port: 0, address: "127.0.0.1" }, onListening);
+    }
+  });
+}

test-parity/node-suite/dgram/lifecycle/close-arguments.ts

@@ -0,0 +1,14 @@
+import * as dgram from "node:dgram";
+
+const socket = dgram.createSocket("udp4");
+let closeEvents = 0;
+socket.on("close", () => closeEvents++);
+const closed = new Promise<void>((resolve) => {
+  socket.once("close", () => queueMicrotask(resolve));
+});
+
+const result = (socket.close as (callback?: unknown) => dgram.Socket)("not a callback");
+await closed;
+
+console.log("close result self:", result === socket);
+console.log("close events:", closeEvents);

test-parity/node-suite/dgram/lifecycle/close-ordering.ts

@@ -0,0 +1,17 @@
+import * as dgram from "node:dgram";
+
+const socket = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => socket.bind(0, "127.0.0.1", resolve));
+
+const order: string[] = [];
+const closed = new Promise<void>((resolve) => {
+  socket.once("close", () => {
+    order.push("event");
+    resolve();
+  });
+});
+
+socket.close(() => order.push("callback"));
+await closed;
+await Promise.resolve();
+console.log("close order:", order.join(","));

test-parity/node-suite/dgram/lifecycle/custom-lookup.ts

@@ -0,0 +1,14 @@
+import * as dgram from "node:dgram";
+
+const calls: string[] = [];
+const socket = dgram.createSocket({
+  type: "udp4",
+  lookup(hostname, family, callback) {
+    calls.push(`${hostname}:${family}`);
+    callback(null, "0.0.0.0", 4);
+  },
+});
+
+await new Promise<void>((resolve) => socket.bind(0, () => resolve()));
+console.log("lookup calls:", calls.length, calls[0]?.startsWith("0.0.0.0:") ?? false);
+await new Promise<void>((resolve) => socket.close(() => resolve()));

test-parity/node-suite/dgram/metrics/buffer-sizes.ts

@@ -0,0 +1,30 @@
+import * as dgram from "node:dgram";
+
+function codeOf(fn: () => unknown): string {
+  try {
+    fn();
+    return "none";
+  } catch (error: unknown) {
+    return (error as { code?: string }).code ?? "Error";
+  }
+}
+
+const unbound = dgram.createSocket("udp4");
+console.log("unbound send get:", codeOf(() => unbound.getSendBufferSize()));
+console.log("unbound recv set:", codeOf(() => unbound.setRecvBufferSize(8192)));
+await new Promise<void>((resolve) => unbound.close(() => resolve()));
+
+const socket = dgram.createSocket("udp4");
+await new Promise<void>((resolve) => socket.bind(0, "127.0.0.1", () => resolve()));
+console.log(
+  "invalid recv:",
+  [-1, Infinity, "bad"].map((value) => codeOf(() => socket.setRecvBufferSize(value as never))).join(","),
+);
+console.log(
+  "invalid send:",
+  [-1, Infinity, "bad"].map((value) => codeOf(() => socket.setSendBufferSize(value as never))).join(","),
+);
+socket.setRecvBufferSize(10000);
+socket.setSendBufferSize(10000);
+console.log("positive sizes:", socket.getRecvBufferSize() > 0, socket.getSendBufferSize() > 0);
+await new Promise<void>((resolve) => socket.close(() => resolve()));

test-parity/node-suite/dgram/metrics/create-socket-buffer-options.ts

@@ -0,0 +1,15 @@
+import * as dgram from "node:dgram";
+
+const socket = dgram.createSocket({
+  type: "udp4",
+  recvBufferSize: 10_000,
+  sendBufferSize: 15_000,
+});
+await new Promise<void>((resolve) => socket.bind(0, "127.0.0.1", resolve));
+
+const recvSize = socket.getRecvBufferSize();
+const sendSize = socket.getSendBufferSize();
+console.log("receive option applied:", recvSize === 10_000 || recvSize === 20_000);
+console.log("send option applied:", sendSize === 15_000 || sendSize === 30_000);
+
+await new Promise<void>((resolve) => socket.close(resolve));