visaljs 0.0.7 → 0.0.9

package/node/prelude/internal/http_agent.js

@@ -2,15 +2,85 @@
 // at most maxSockets each, the rest of the requests queued; with keepAlive, a socket whose
 // response is done goes to freeSockets (unref'd, so it doesn't keep the program running) for
 // the next request to the same origin, until the agent's timeout or the server's Keep-Alive hint.
+// Ported from Node.js (Copyright Node.js contributors, MIT): node/third_party/nodejs/LICENSE.
+import { httpGuard } from "visaljs:host";
 import { EventEmitter } from "../events.js";
 import { createConnection } from "../net.js";
 import { invalidArgType, invalidArgValue, outOfRange } from "./errors.js";
+import { isIP } from "./net.js";
 
 function freeSocketErrorListener() {
   this.destroy();
   this.emit("agentRemove");
 }
 
+/* Node's free socket data guard: bytes a socket reads while it waits in the pool (no request on it)
+ * would be taken for the next request's response; the socket is destroyed instead. The bytes are
+ * caught in C (httpGuard), before they reach the socket's stream; attaching the next request's
+ * parser takes the guard off. */
+const guardedSockets = new Map();  /* the guarded sockets, by their handle's id */
+
+function onGuardedData(id) {
+  const socket = guardedSockets.get(id);
+  guardedSockets.delete(id);
+  socket?.destroy();
+}
+
+/* Node's maybeEnableKeylog: the sockets' keylog events become the agent's */
+function maybeEnableKeylog(eventName) {
+  if (eventName !== "keylog") return;
+  this.removeListener("newListener", maybeEnableKeylog);
+  const emit = this.emit.bind(this);
+  this._onKeylog = function onkeylog(keylog) {
+    emit("keylog", keylog, this);  /* this: the socket */
+  };
+  for (const set of [this.freeSockets, this.sockets]) {
+    for (const sockets of Object.values(set)) for (const socket of sockets) socket.on("keylog", this._onKeylog);
+  }
+}
+
+function installFreeSocketDataGuard(socket) {
+  /* a TLS socket's reads are records (session tickets, alerts) before they're data: its own */
+  if (socket.encrypted) return;
+  if (socket.readableLength > 0) {
+    socket.destroy();
+    return;
+  }
+  if (socket.connecting) {
+    if (!socket._freeGuardConnect) {  /* once: a socket may come back to the pool before it connects */
+      socket._freeGuardConnect = () => {
+        socket._freeGuardConnect = undefined;
+        installFreeSocketDataGuard(socket);
+      };
+      socket.once("connect", socket._freeGuardConnect);
+    }
+    return;
+  }
+  const id = socket._handle;
+  if (typeof id === "number" && httpGuard(id, onGuardedData)) {
+    guardedSockets.set(id, socket);
+    socket._freeGuardId = id;
+    /* one listener while it's guarded, taken off when it's reused (a kept-alive socket comes back
+     * to the pool after each request) */
+    socket._freeGuardClose = () => removeFreeSocketDataGuard(socket);
+    socket.once("close", socket._freeGuardClose);
+  }
+}
+
+function removeFreeSocketDataGuard(socket) {
+  if (socket._freeGuardConnect) {
+    socket.removeListener("connect", socket._freeGuardConnect);
+    socket._freeGuardConnect = undefined;
+  }
+  if (socket._freeGuardClose) {
+    socket.removeListener("close", socket._freeGuardClose);
+    socket._freeGuardClose = undefined;
+  }
+  const id = socket._freeGuardId;
+  if (id !== undefined && guardedSockets.get(id) === socket) guardedSockets.delete(id);
+  socket._freeGuardId = undefined;
+}
+
 export function Agent(options) {
   if (!(this instanceof Agent)) return new Agent(options);
   EventEmitter.call(this);
@@ -27,6 +97,9 @@ export function Agent(options) {
   this.maxSockets = this.options.maxSockets || Agent.defaultMaxSockets;
   this.maxFreeSockets = this.options.maxFreeSockets || 256;
   this.scheduling = this.options.scheduling || "lifo";
+  /* what the server's Keep-Alive timeout is cut by, so the socket isn't reused as the server closes it */
+  const buffer = this.options.agentKeepAliveTimeoutBuffer;
+  this.agentKeepAliveTimeoutBuffer = typeof buffer === "number" && buffer >= 0 && Number.isFinite(buffer) ? buffer : 1000;
   this.maxTotalSockets = this.options.maxTotalSockets;
   this.totalSocketCount = 0;
   if (this.scheduling !== "fifo" && this.scheduling !== "lifo") throw invalidArgValue("scheduling", "must be one of: 'fifo', 'lifo'", this.scheduling);
@@ -37,6 +110,9 @@ export function Agent(options) {
     this.maxTotalSockets = Infinity;
   }
 
+  /* keylog events only once someone listens: then every socket's, the existing ones' too */
+  this.on("newListener", maybeEnableKeylog);
+
   /* a socket whose request is done: the next queued request's, kept alive, or destroyed */
   this.on("free", (socket, options) => {
     const name = this.getName(options);
@@ -68,6 +144,7 @@ export function Agent(options) {
     socket._httpMessage = null;
     this.removeSocket(socket, options);
     socket.once("error", freeSocketErrorListener);
+    installFreeSocketDataGuard(socket);
     freeSockets.push(socket);
   });
 }
@@ -90,11 +167,34 @@ Agent.prototype.getName = function getName(options = {}) {
   return name;
 };
 
+/* the TLS server name (SNI): the Host header's host, else the host; never an IP address. Plain
+ * HTTP ignores it; https's agent reads it, and its sessions are keyed by it (Node's) */
+function calculateServerName(options, req) {
+  let servername = options.host;
+  const hostHeader = req.getHeader("host");
+  if (hostHeader) {
+    if (typeof hostHeader !== "string") throw invalidArgType("options.headers.host", "of type string", hostHeader);
+    if (hostHeader.startsWith("[")) {
+      const index = hostHeader.indexOf("]");
+      servername = index === -1 ? hostHeader : hostHeader.slice(1, index);
+    } else {
+      servername = hostHeader.split(":", 1)[0];
+    }
+  }
+  if (isIP(servername)) servername = "";
+  return servername;
+}
+
+function normalizeServerName(options, req) {
+  if (!options.servername && options.servername !== "") options.servername = calculateServerName(options, req);
+}
+
 /* a request: a free socket, a new one (under maxSockets), or the queue */
 Agent.prototype.addRequest = function addRequest(req, options, port, localAddress) {
   if (typeof options === "string") options = { __proto__: null, host: options, port, localAddress };
   options = { __proto__: null, ...options, ...this.options };
   if (options.socketPath) options.path = options.socketPath;
+  normalizeServerName(options, req);
   const name = this.getName(options);
   this.sockets[name] ||= [];
   const freeSockets = this.freeSockets[name];
@@ -106,7 +206,12 @@ Agent.prototype.addRequest = function addRequest(req, options, port, localAddres
   }
   const freeLen = freeSockets ? freeSockets.length : 0;
   const sockLen = freeLen + this.sockets[name].length;
+  /* a reused socket takes the request's highWaterMark, as Node's */
+  if (socket && options.highWaterMark != null && socket.writableHighWaterMark !== options.highWaterMark) {
+    socket._writableState.highWaterMark = options.highWaterMark;
+  }
   if (socket) {
+    removeFreeSocketDataGuard(socket);
     this.reuseSocket(socket, req);
     setRequestSocket(this, req, socket);
     this.sockets[name].push(socket);
@@ -125,6 +230,7 @@ Agent.prototype.addRequest = function addRequest(req, options, port, localAddres
 Agent.prototype.createSocket = function createSocket(req, options, cb) {
   options = { __proto__: null, ...options, ...this.options };
   if (options.socketPath) options.path = options.socketPath;
+  normalizeServerName(options, req);
   const name = this.getName(options);
   options._agentKey = name;
   options.encoding = null;
@@ -137,6 +243,7 @@ Agent.prototype.createSocket = function createSocket(req, options, cb) {
     this.sockets[name].push(s);
     this.totalSocketCount++;
     installListeners(this, s, options);
+    if (this._onKeylog) s.on("keylog", this._onKeylog);
     cb(null, s);
   };
   if (this.keepAlive) {
@@ -218,7 +325,7 @@ Agent.prototype.keepSocketAlive = function keepSocketAlive(socket) {
   const hint = socket._httpMessage?.res?.headers["keep-alive"];
   const seconds = hint ? /^timeout=(\d+)/.exec(hint)?.[1] : undefined;
   if (seconds) {
-    let serverHintTimeout = parseInt(seconds, 10) * 1000 - 1000;
+    let serverHintTimeout = parseInt(seconds, 10) * 1000 - this.agentKeepAliveTimeoutBuffer;
     serverHintTimeout = serverHintTimeout > 0 ? serverHintTimeout : 0;
     if (serverHintTimeout === 0) canKeepSocketAlive = false;
     else if (serverHintTimeout < agentTimeout) agentTimeout = serverHintTimeout;
@@ -246,4 +353,9 @@ function setRequestSocket(agent, req, socket) {
   socket.setTimeout(req.timeout);
 }
 
-export const globalAgent = new Agent({ keepAlive: true, scheduling: "lifo", timeout: 5000 });
+export let globalAgent = new Agent({ keepAlive: true, scheduling: "lifo", timeout: 5000 });
+
+/* http.globalAgent's setter: the agent requests use by default from then on, as Node's */
+export function setGlobalAgent(agent) {
+  globalAgent = agent;
+}

package/node/prelude/internal/http_symbols.js

@@ -0,0 +1,3 @@
+// node:http's internal symbols that Node's node:_http_server exports: the server's
+// connections-checking timer.
+export const kConnectionsCheckingInterval = Symbol("http.server.connectionsCheckingInterval");

package/node/prelude/internal/mime.js

@@ -0,0 +1,249 @@
+// util.MIMEType and util.MIMEParams: Node's internal/mime.js (WHATWG MIME Sniffing's parsing):
+// type and subtype lowercased, parameters parsed when first used, first of each name kept,
+// values quoted when serialized if they need it. Linked into programs that name them
+// (internal/features.js): util's MIMEType and MIMEParams build these classes.
+// Ported from Node.js (Copyright Node.js contributors, MIT): node/third_party/nodejs/LICENSE.
+import { MIMEParams as MIMEParamsWrapper, MIMEType as MIMETypeWrapper } from "../util.js";
+import { codeError } from "./errors.js";
+import { provideClass } from "./features.js";
+
+const NOT_HTTP_TOKEN_CODE_POINT = /[^!#$%&'*+\-.^_`|~A-Za-z0-9]/g;
+const NOT_HTTP_QUOTED_STRING_CODE_POINT = /[^\t -~\u0080-ÿ]/g;
+const END_BEGINNING_WHITESPACE = /[^\r\n\t ]|$/;
+const START_ENDING_WHITESPACE = /[\r\n\t ]*$/;
+const EQUALS_SEMICOLON_OR_END = /[;=]|$/;
+const QUOTED_VALUE_PATTERN = /^(?:([\\]$)|[\\][\s\S]|[^"])*(?:(")|$)/u;
+
+function invalidMimeSyntax(production, str, invalidIndex) {
+  const at = invalidIndex !== -1 ? ` at ${invalidIndex}` : "";
+  return codeError(TypeError, "ERR_INVALID_MIME_SYNTAX", `The MIME syntax for a ${production} in "${str}" is invalid` + at);
+}
+
+function toASCIILower(str) {
+  let result = "";
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+    result += char >= "A" && char <= "Z" ? char.toLowerCase() : char;
+  }
+  return result;
+}
+
+function parseTypeAndSubtype(str) {
+  let position = str.search(END_BEGINNING_WHITESPACE);
+  const typeEnd = str.indexOf("/", position);
+  const trimmedType = typeEnd === -1 ? str.slice(position) : str.slice(position, typeEnd);
+  const invalidTypeIndex = trimmedType.search(NOT_HTTP_TOKEN_CODE_POINT);
+  if (trimmedType === "" || invalidTypeIndex !== -1 || typeEnd === -1) throw invalidMimeSyntax("type", str, invalidTypeIndex);
+  position = typeEnd + 1;
+  const type = toASCIILower(trimmedType);
+  const subtypeEnd = str.indexOf(";", position);
+  const rawSubtype = subtypeEnd === -1 ? str.slice(position) : str.slice(position, subtypeEnd);
+  position += rawSubtype.length;
+  if (subtypeEnd !== -1) position += 1;
+  const trimmedSubtype = rawSubtype.slice(0, rawSubtype.search(START_ENDING_WHITESPACE));
+  const invalidSubtypeIndex = trimmedSubtype.search(NOT_HTTP_TOKEN_CODE_POINT);
+  if (trimmedSubtype === "" || invalidSubtypeIndex !== -1) throw invalidMimeSyntax("subtype", str, invalidSubtypeIndex);
+  return { type, subtype: toASCIILower(trimmedSubtype), parametersStringIndex: position };
+}
+
+function removeBackslashes(str) {
+  let ret = "";
+  let i;
+  for (i = 0; i < str.length - 1; i++) {
+    const c = str[i];
+    if (c === "\\") {
+      i++;
+      ret += str[i];
+    } else ret += c;
+  }
+  if (i === str.length - 1) ret += str[i];
+  return ret;
+}
+
+function escapeQuoteOrSolidus(str) {
+  let result = "";
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+    result += char === '"' || char === "\\" ? `\\${char}` : char;
+  }
+  return result;
+}
+
+function encode(value) {
+  if (value.length === 0) return '""';
+  if (value.search(NOT_HTTP_TOKEN_CODE_POINT) === -1) return value;
+  return `"${escapeQuoteOrSolidus(value)}"`;
+}
+
+let instantiateMimeParams;
+
+class MIMEParams {
+  #data = new Map();
+  #processed = true;  /* a MIMEType's are parsed when first used */
+  #string = null;
+
+  static {
+    instantiateMimeParams = (str) => {
+      const instance = new MIMEParams();
+      instance.#string = str;
+      instance.#processed = false;
+      return instance;
+    };
+  }
+
+  delete(name) {
+    this.#parse();
+    this.#data.delete(name);
+  }
+
+  get(name) {
+    this.#parse();
+    return this.#data.has(name) ? this.#data.get(name) : null;
+  }
+
+  has(name) {
+    this.#parse();
+    return this.#data.has(name);
+  }
+
+  set(name, value) {
+    this.#parse();
+    name = `${name}`;
+    value = `${value}`;
+    const invalidNameIndex = name.search(NOT_HTTP_TOKEN_CODE_POINT);
+    if (name.length === 0 || invalidNameIndex !== -1) throw invalidMimeSyntax("parameter name", name, invalidNameIndex);
+    const invalidValueIndex = value.search(NOT_HTTP_QUOTED_STRING_CODE_POINT);
+    if (invalidValueIndex !== -1) throw invalidMimeSyntax("parameter value", value, invalidValueIndex);
+    this.#data.set(name, value);
+  }
+
+  entries() {
+    this.#parse();
+    return this.#data.entries();
+  }
+
+  keys() {
+    this.#parse();
+    return this.#data.keys();
+  }
+
+  values() {
+    this.#parse();
+    return this.#data.values();
+  }
+
+  toString() {
+    this.#parse();
+    let ret = "";
+    for (const [key, value] of this.#data) {
+      if (ret.length) ret += ";";
+      ret += `${key}=${encode(value)}`;
+    }
+    return ret;
+  }
+
+  #parse() {
+    if (this.#processed) return;
+    const paramsMap = this.#data;
+    let position = 0;
+    const str = this.#string;
+    const endOfSource = str.slice(position).search(START_ENDING_WHITESPACE) + position;
+    while (position < endOfSource) {
+      position += str.slice(position).search(END_BEGINNING_WHITESPACE);
+      const afterParameterName = str.slice(position).search(EQUALS_SEMICOLON_OR_END) + position;
+      const parameterString = toASCIILower(str.slice(position, afterParameterName));
+      position = afterParameterName;
+      if (position < endOfSource) {
+        const char = str.charAt(position);
+        position += 1;
+        if (char === ";") continue;  /* a parameter without a value */
+      }
+      if (position >= endOfSource) break;
+      const char = str.charAt(position);
+      let parameterValue;
+      if (char === '"') {
+        position += 1;
+        /* to the closing quote, or the end ($1: an unmatched backslash, $2: the closing quote) */
+        const insideMatch = QUOTED_VALUE_PATTERN.exec(str.slice(position));
+        position += insideMatch[0].length;
+        const inside = insideMatch[1] || insideMatch[2] ? insideMatch[0].slice(0, -1) : insideMatch[0];
+        parameterValue = removeBackslashes(inside);
+        if (insideMatch[1]) parameterValue += "\\";
+      } else {
+        const valueEnd = str.indexOf(";", position);
+        const rawValue = valueEnd === -1 ? str.slice(position) : str.slice(position, valueEnd);
+        position += rawValue.length;
+        const trimmedValue = rawValue.slice(0, rawValue.search(START_ENDING_WHITESPACE));
+        if (trimmedValue === "") continue;
+        parameterValue = trimmedValue;
+      }
+      if (parameterString !== "" && parameterString.search(NOT_HTTP_TOKEN_CODE_POINT) === -1 &&
+        parameterValue.search(NOT_HTTP_QUOTED_STRING_CODE_POINT) === -1 && !paramsMap.has(parameterString)) {
+        paramsMap.set(parameterString, parameterValue);
+      }
+      position++;
+    }
+    this.#data = paramsMap;
+    this.#processed = true;
+  }
+}
+
+const stringifyParams = MIMEParams.prototype.toString;
+Object.defineProperty(MIMEParams.prototype, Symbol.iterator, { configurable: true, value: MIMEParams.prototype.entries, writable: true });
+Object.defineProperty(MIMEParams.prototype, "toJSON", { configurable: true, value: stringifyParams, writable: true });
+
+export class MIMEType {
+  #type;
+  #subtype;
+  #parameters;
+
+  constructor(string) {
+    string = `${string}`;
+    const data = parseTypeAndSubtype(string);
+    this.#type = data.type;
+    this.#subtype = data.subtype;
+    this.#parameters = instantiateMimeParams(string.slice(data.parametersStringIndex));
+  }
+
+  get type() {
+    return this.#type;
+  }
+
+  set type(v) {
+    v = `${v}`;
+    const invalidTypeIndex = v.search(NOT_HTTP_TOKEN_CODE_POINT);
+    if (v.length === 0 || invalidTypeIndex !== -1) throw invalidMimeSyntax("type", v, invalidTypeIndex);
+    this.#type = toASCIILower(v);
+  }
+
+  get subtype() {
+    return this.#subtype;
+  }
+
+  set subtype(v) {
+    v = `${v}`;
+    const invalidSubtypeIndex = v.search(NOT_HTTP_TOKEN_CODE_POINT);
+    if (v.length === 0 || invalidSubtypeIndex !== -1) throw invalidMimeSyntax("subtype", v, invalidSubtypeIndex);
+    this.#subtype = toASCIILower(v);
+  }
+
+  get essence() {
+    return `${this.#type}/${this.#subtype}`;
+  }
+
+  get params() {
+    return this.#parameters;
+  }
+
+  toString() {
+    let ret = `${this.#type}/${this.#subtype}`;
+    const paramStr = stringifyParams.call(this.#parameters);
+    if (paramStr.length) ret += `;${paramStr}`;
+    return ret;
+  }
+}
+
+Object.defineProperty(MIMEType.prototype, "toJSON", { configurable: true, value: MIMEType.prototype.toString, writable: true });
+
+provideClass(MIMEParamsWrapper, MIMEParams);
+provideClass(MIMETypeWrapper, MIMEType);

package/node/prelude/internal/net.js

@@ -1,4 +1,5 @@
 // IP address checks (Node's lib/internal/net.js regexes), shared by node:net and node:dns.
+// Ported from Node.js (Copyright Node.js contributors, MIT): node/third_party/nodejs/LICENSE.
 
 // IPv4 Segment
 const v4Seg = "(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])";

package/node/prelude/internal/net_bound.js

@@ -0,0 +1,123 @@
+// net.BoundSocket, as Node's: a TCP or pipe handle bound at once (its errors thrown by the
+// constructor), neither listening nor connecting until one Server (server.listen(bound)) or Socket
+// (new net.Socket({ handle: bound })) adopts it, which then owns it. No DNS: a host is an IP.
+// Linked into programs that name BoundSocket (internal/features.js); net.js adopts the handle
+// through features.adoptBoundSocket.
+import { netAddress, netBind, netClose, netFd, netOpen } from "visaljs:host";
+import { BoundSocket as Wrapper } from "../net.js";
+import { codeError, invalidArgType, invalidArgValue, validateString } from "./errors.js";
+import { features, provideClass } from "./features.js";
+import { isIP } from "./net.js";
+
+const kConsume = Symbol("kBoundSocketConsume");
+
+const adopted = () => codeError(Error, "ERR_SOCKET_HANDLE_ADOPTED", "The bound socket has already been adopted by a server or socket");
+
+function validateBoolean(value, name) {
+  if (typeof value !== "boolean") throw invalidArgType(name, "of type boolean", value);
+}
+
+class BoundSocket {
+  #handle = null;  /* the host handle's id, until adopted or closed */
+  #address = {};
+  #path;
+
+  constructor(options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) throw invalidArgType("options", "of type object", options);
+    if (options.path !== undefined) {
+      this.#bindPipe(options);
+      return;
+    }
+    const { exceptionWithHostPort, validatePort } = features.net;
+    const port = validatePort(options.port ?? 0, "options.port");
+    const ipv6Only = options.ipv6Only ?? false;
+    validateBoolean(ipv6Only, "options.ipv6Only");
+    const reusePort = options.reusePort ?? false;
+    validateBoolean(reusePort, "options.reusePort");
+    let { host } = options;
+    if (host === undefined || host === null) {
+      host = ipv6Only ? "::" : "0.0.0.0";
+    } else {
+      validateString(host, "options.host");
+      if (isIP(host) === 0) {
+        throw invalidArgValue("options.host", "must be a numeric IP address; net.BoundSocket does not perform DNS resolution", host);
+      }
+    }
+    const id = netOpen(false);
+    let err = netBind(id, host, port, (ipv6Only ? 1 : 0) | (reusePort ? 2 : 0));
+    /* libuv keeps a bind's EADDRINUSE for the next getsockname, listen or connect: asked now, so it
+     * throws here, as Node's */
+    if (err === 0) {
+      const a = netAddress(id, false);
+      if (typeof a === "number") err = a;
+      else this.#address = { address: a[0], family: a[1], port: a[2] };
+    }
+    if (err) {
+      netClose(id);
+      throw exceptionWithHostPort(err, "bind", host, port);
+    }
+    this.#handle = id;
+  }
+
+  /* a Unix domain socket's path (or a Windows named pipe's); one starting with "\0" is in Linux's
+   * abstract namespace */
+  #bindPipe(options) {
+    const { path, host, port, ipv6Only, reusePort } = options;
+    if (host !== undefined || port !== undefined || ipv6Only !== undefined || reusePort !== undefined) {
+      throw invalidArgValue("options", "path is mutually exclusive with host, port, ipv6Only, and reusePort", options);
+    }
+    validateString(path, "options.path");
+    if (path[0] === "\0" && process.platform !== "linux") {
+      throw invalidArgValue("options.path", "abstract socket paths are only supported on Linux", path);
+    }
+    const id = netOpen(true);
+    const err = netBind(id, path);
+    if (err) {
+      netClose(id);
+      throw features.net.errnoException(err, "bind");
+    }
+    this.#handle = id;
+    this.#path = path;
+  }
+
+  /* { address, family, port }, or a pipe's path */
+  address() {
+    if (this.#handle === null) throw adopted();
+    return this.#path ?? this.#address;
+  }
+
+  /* the descriptor, or -1 where sockets have none (Windows) */
+  fd() {
+    if (this.#handle === null) throw adopted();
+    const fd = netFd(this.#handle);
+    return fd < 0 ? -1 : fd;
+  }
+
+  close() {
+    if (this.#handle === null) throw adopted();
+    netClose(this.#handle);
+    this.#handle = null;
+  }
+
+  [Symbol.dispose]() {
+    if (this.#handle !== null) {
+      netClose(this.#handle);
+      this.#handle = null;
+    }
+  }
+
+  get isPipe() {
+    return this.#path !== undefined;
+  }
+
+  [kConsume]() {
+    if (this.#handle === null) throw adopted();
+    const id = this.#handle;
+    this.#handle = null;
+    return { id, path: this.#path };
+  }
+}
+
+/* the handle of a BoundSocket being adopted ({ id, path }), or null for anything else */
+features.adoptBoundSocket = (value) => (value instanceof BoundSocket ? value[kConsume]() : null);
+provideClass(Wrapper, BoundSocket);

package/node/prelude/internal/net_onread.js

@@ -0,0 +1,73 @@
+// net.Socket's onread option, as Node's: the bytes read go into the user's buffer, a buffer's worth
+// at a time, and to its callback instead of 'data'. The callback returning false, or pausing,
+// stops reading, as a read into that buffer would: the bytes not yet given wait for resume().
+// Linked into programs that name onread (internal/features.js).
+import { netReadStart, netReadStop } from "visaljs:host";
+import { features } from "./features.js";
+
+function deliver(socket, bytes) {
+  for (let at = 0; at < bytes.length;) {
+    const { buffer, callback } = socket._onread;
+    const buf = typeof buffer === "function" ? buffer() : buffer;
+    const n = Math.min(buf.length, bytes.length - at);
+    buf.set(bytes.subarray(at, at + n));
+    at += n;
+    const more = callback.call(socket, n, buf) !== false && socket._reading;
+    if (!more) {
+      if (at < bytes.length) socket._onreadRest = bytes.subarray(at);
+      return false;
+    }
+  }
+  return true;
+}
+
+features.onread = {
+  /* bytes read: false stops reading */
+  deliver,
+
+  /* a TLS socket's decrypted bytes: all of them, false when a callback asks to stop (its reads
+   * resume through its own stream, not the bytes kept here) */
+  deliverAll(socket, bytes) {
+    let more = true;
+    for (let at = 0; at < bytes.length;) {
+      const { buffer, callback } = socket._onread;
+      const buf = typeof buffer === "function" ? buffer() : buffer;
+      const n = Math.min(buf.length, bytes.length - at);
+      buf.set(bytes.subarray(at, at + n));
+      at += n;
+      if (callback.call(socket, n, buf) === false) more = false;
+    }
+    return more;
+  },
+
+  /* libuv takes a buffer for the read that finds EOF too: a buffer function is asked for one */
+  eof(socket) {
+    if (typeof socket._onread.buffer === "function") socket._onread.buffer();
+  },
+
+  /* Node's: pausing stops reading from the handle, resuming starts it (a TLS socket reads through
+   * its own stream) */
+  pause(socket) {
+    if (socket.encrypted || socket.connecting || socket._handle === null || !socket._reading) return;
+    socket._reading = false;
+    if (!socket.destroyed) {
+      const err = netReadStop(socket._handle);
+      if (err) socket.destroy(features.net.errnoException(err, "read"));
+    }
+  },
+
+  resume(socket) {
+    if (!socket.encrypted && !socket.connecting && socket._handle !== null && !socket._reading) socket._startReading();
+  },
+
+  /* reading again: the bytes left from the last read first, as the next read */
+  rest(socket) {
+    const rest = socket._onreadRest;
+    socket._onreadRest = null;
+    process.nextTick(() => {
+      if (socket.destroyed || socket._handle === null) return;
+      if (deliver(socket, rest)) netReadStart(socket._handle);
+      else socket._reading = false;
+    });
+  },
+};