net: add createPipe() and createSocketPair()

[kingces95]

Adds a node:pipe module with createPipe(), returning a readable
and writable endpoint owned by the parent process.

The endpoints may be passed to child_process.spawn() stdio. This lets
the parent lend a pipe endpoint to a child without turning the parent
stream itself into child-owned stdio. The parent can then reclaim unread
bytes or lend the same endpoint to a later child.

This is useful for bash-like partial consumption of long-lived streams.
For example, a parent can keep ownership of a Server Sent Event stream
while delegating bounded reads to external tools, then continue parsing
from the exact byte where the child stopped.

The central integration test (test-child-process-leased-pipe.js) writes abc,
lets child A read a, lets child B read b, and then verifies that the parent
can still read c.

Endpoints created by pipe.createPipe() are rejected by spawnSync(), and
an endpoint may only be leased to one child process at a time.

Tests cover node:pipe creation, documentation examples, child stdio
leasing, sequential lease-and-reclaim behavior, lease error cleanup,
spawnSync() rejection, and platform-consistent writable finish
behavior.

[marco-ippolito]

I dont think we should create a new module

[jasnell]

+1, there's no justification for a new top-level module.

[kingces95]

Yep. I'll move it to net.

[kingces95]

I also pushed a small stacked follow-up branch that explores the adjacent uv_socketpair() primitive as net.createSocketPair():

kingces95/node@create-pipe...create-socket-pair

My immediate use case is net.createPipe(); I’m offering this for completeness if reviewers think these APIs should be considered as a small family.

The idea is that net.createPipe() exposes directional OS-backed endpoints, while net.createSocketPair() exposes symmetric duplex OS-backed endpoints, similar in shape to stream.duplexPair() but with real handles.

The follow-up has child-process support for fd >= 3, where the duplex nature is explicit.

[kingces95]

I folded the socket-pair follow-up into the main change.

The updated version keeps both APIs in node:net:

• net.createPipe() returns directional parent-owned endpoints.
• net.createSocketPair() returns a symmetric duplex pair.
• Both can be leased to child processes through stdio, with createSocketPair() limited to fd >= 3.
• The bash/SSE sketch was removed from the test suite.

This should make the PR easier to review as one coherent “parent-owned OS endpoints” feature.

---

The removed sketch is preserved here as a userland workbook/example of the style of shell-like stream composition this API is meant to enable:

https://gist.github.com/kingces95/1e024a1e987ef3956c7ae3513e468c64

[kingces95]

I landed on a single coherent node:net feature shape:

• net.createPipe() exposes directional OS-backed endpoints: { readable, writable }.
• net.createSocketPair() exposes symmetric duplex OS-backed endpoints: [left, right].
• Pipe endpoints can be leased directly to child process stdio, because that maps cleanly to inherited pipe handles on both Unix and Windows.
• Socket-pair endpoints are not accepted as stdio; instead, they use Node’s existing IPC handle-transfer path with subprocess.send(), which matches how socket-like handles already cross process boundaries.
• The parent process owns the endpoint lifecycle, so docs now call out normal stream cleanup: end(), consumption, resume(), or destroy() as appropriate.

So the PR is no longer “just create pipe.” It is a parent-owned OS endpoint proposal: pipes for directional stdio leasing, socket pairs for duplex cross-process communication.