net, tls: consolidate the open node:net, node:tls, Bun.connect, Bun.listen and usockets pull requests

docs/runtime/http/server.mdx

@@ -252,7 +252,7 @@ Set `http1: false` to refuse HTTP/1.x clients. Over TLS, clients that offer ALPN
 
 By default, `Bun.serve` closes connections after **10 seconds** of inactivity. A connection is idle when no data is being sent or received. That includes in-flight requests where your handler is still running but hasn't written any bytes to the response yet. Browsers and `fetch()` clients see this as a connection reset.
 
-To configure this, set the `idleTimeout` field (in seconds). The maximum value is `255`, and `0` disables the timeout entirely.
+To configure this, set the `idleTimeout` field (in seconds). The maximum value is `255`, and `0` disables the timeout entirely. Bun checks for idle connections every 4 seconds, so a connection is closed up to 4 seconds after its `idleTimeout` has passed, and never before.
 
 ```ts
 Bun.serve({

docs/runtime/http/tls.mdx

@@ -41,6 +41,22 @@ Bun.serve({
 });
 ```
 
+### Protocol versions
+
+To limit the TLS protocol versions a connection can use, set `minVersion` and `maxVersion`. They take the same names as `node:tls`: `"TLSv1"`, `"TLSv1.1"`, `"TLSv1.2"` and `"TLSv1.3"`. The defaults are `"TLSv1.2"` and `"TLSv1.3"`.
+
+```ts
+Bun.serve({
+  tls: {
+    key: Bun.file("./key.pem"),
+    cert: Bun.file("./cert.pem"),
+    minVersion: "TLSv1.3", // [!code ++]
+  },
+});
+```
+
+The same two options work in every API that takes a `tls` object, such as `fetch`, `Bun.connect` and `Bun.listen`. When `tls` is an array (see [SNI](#server-name-indication-sni) below), every entry uses the range of the first one.
+
 ### CA Certificates
 
 Pass `ca` to override the trusted CA certificates. By default, the server trusts the list of well-known CAs curated by Mozilla; setting `ca` replaces that list.

docs/runtime/networking/fetch.mdx

@@ -499,7 +499,7 @@ An option given on the request takes precedence over the session's, `proxy: fals
 
 The constructor throws for a `proxy` or a `tls.checkServerIdentity` that it cannot use, such as `proxy: 8080`, a `proxy` object without a `url`, or a `checkServerIdentity` that is not a function. For `proxy`, only `undefined`, `null` and `""` mean no option. On a request, `fetch` ignores such a `proxy` (`true` throws), and the request keeps the proxy of its session or of the environment.
 
-Bun rounds `idleTimeout` up to its socket timer, which moves in 4 second steps up to four minutes and in whole minutes beyond that. A connection is never closed before `idleTimeout`, and it can stay open for up to two steps longer. The longest `idleTimeout` is 238 minutes. A larger value means 238 minutes.
+Bun checks socket timers every 4 seconds. A connection is never closed before `idleTimeout`, and it can stay open up to 4 seconds longer.
 
 Without `maxIdleSockets` a session has no limit of its own. The idle connections of all sessions and of plain `fetch` share one bounded pool per kind. When that pool is full, Bun closes the longest-idle connection in it, whichever session it belongs to. A `maxIdleSockets` above the size of the pool has no effect.
 

docs/runtime/networking/tcp.mdx

@@ -135,7 +135,7 @@ const socket = await Bun.connect({
 });
 ```
 
-To require TLS, specify `tls: true`.
+To require TLS, specify `tls: true` or a `tls` options object. An object that sets no option, such as `{}`, is the same as `tls: true`.
 
 ```ts
 // The client
@@ -182,7 +182,9 @@ socket.reload({
 
 ## Buffering
 
-TCP sockets in Bun do not buffer data, so performance-sensitive code should buffer writes itself. For example, this:
+`socket.write()` does not buffer data. It returns the number of bytes the socket accepted, and you send the rest from the `drain` handler. `socket.end(data)` accepts the whole chunk: Bun queues what the socket didn't accept, sends it once the socket is writable again, and then closes the socket. If the queued data can't be sent, `close(socket, error)` gets the error: `EPIPE` or `ECONNRESET` when the peer is gone, `ETIMEDOUT` when the peer reads nothing for the socket's timeout (`socket.timeout(seconds)`, 120 seconds by default on a socket that `Bun.listen` accepted).
+
+Performance-sensitive code should buffer writes itself. For example, this:
 
 ```ts
 socket.write("h");

docs/runtime/nodejs-compat.mdx

@@ -33,7 +33,7 @@ We update this page regularly. It reflects the latest version of Bun's compatibi
 
 ### [`node:dns`](https://nodejs.org/api/dns.html)
 
-🟢 Fully implemented. Missing `resolveTlsa`. Bun ignores the `Resolver` `maxTimeout` option.
+🟢 Fully implemented. Missing `resolveTlsa`. Bun ignores the `Resolver` `maxTimeout` option. On the main thread, `setDefaultResultOrder()` also sets which address family `fetch()` and `Bun.connect()` dial first. That part applies to the whole process, including worker threads, because they share one DNS cache. In a worker thread, it only changes that thread's `dns.lookup()` default.
 
 ### [`node:events`](https://nodejs.org/api/events.html)
 
@@ -49,7 +49,7 @@ We update this page regularly. It reflects the latest version of Bun's compatibi
 
 ### [`node:https`](https://nodejs.org/api/https.html)
 
-🟡 `request`, `get`, `Agent` and `globalAgent` are implemented, including connection pooling. Client sockets are `tls.TLSSocket`s. `https.Server` is `http.Server` with TLS options rather than a `tls.Server`. Its request sockets (`req.socket`) are not `tls.TLSSocket`s: `encrypted`, `authorized` and `servername` work, but `getPeerCertificate()` and `getCipher()` are missing. `setSecureContext()`, `addContext()`, `SNICallback` and `handshakeTimeout` are not supported.
+🟡 `request`, `get`, `Agent` and `globalAgent` are implemented, including connection pooling. `https.Server` extends `http.Server` rather than `tls.Server`, and has `setSecureContext()`, `addContext()`, `getTicketKeys()`, `setTicketKeys()` and `SNICallback`. Client sockets and request sockets (`req.socket`) are `tls.TLSSocket`s. The server does not negotiate ALPN, so `ALPNProtocols` and `ALPNCallback` have no effect and `req.socket.alpnProtocol` is `false`. The `'keylog'` event is not supported, and `'tlsClientError'` is only emitted for an `SNICallback` error and for a handshake that takes longer than `handshakeTimeout`.
 
 ### [`node:os`](https://nodejs.org/api/os.html)
 
@@ -141,7 +141,7 @@ We update this page regularly. It reflects the latest version of Bun's compatibi
 
 ### [`node:tls`](https://nodejs.org/api/tls.html)
 
-🟡 Missing `pskCallback`, OCSP stapling (`requestOCSP`), the server `'newSession'`/`'resumeSession'` events and session ticket keys (`ticketKeys` is ignored). As a result, session resumption does not work across processes. Bun uses BoringSSL, so `tlsSocket.renegotiate()` always fails and `getEphemeralKeyInfo()`/`getSharedSigalgs()` return no information.
+🟡 Missing `pskCallback`, OCSP stapling (`requestOCSP`) and the server `'newSession'`/`'resumeSession'` events. Bun uses BoringSSL, so `tlsSocket.renegotiate()` always fails and `getSharedSigalgs()` returns no information.
 
 ### [`node:util`](https://nodejs.org/api/util.html)
 

packages/bun-types/bun.d.ts

@@ -5138,6 +5138,21 @@ declare module "bun" {
      */
     secureOptions?: number | undefined; // Value is a numeric bitmask of the `SSL_OP_*` options
 
+    /**
+     * The minimum TLS protocol version to allow, by the same names as `node:tls`.
+     *
+     * @default "TLSv1.2"
+     */
+    minVersion?: "TLSv1" | "TLSv1.1" | "TLSv1.2" | "TLSv1.3" | undefined;
+
+    /**
+     * The maximum TLS protocol version to allow. A `maxVersion` below
+     * `"TLSv1.2"` also needs a `minVersion`, because the default minimum is `"TLSv1.2"`.
+     *
+     * @default "TLSv1.3"
+     */
+    maxVersion?: "TLSv1" | "TLSv1.1" | "TLSv1.2" | "TLSv1.3" | undefined;
+
     ALPNProtocols?: string | BufferSource;
 
     ciphers?: string;
@@ -7139,10 +7154,13 @@ declare module "bun" {
      * The socket remains readable until the remote end also closes its write side or the connection is terminated.
      * This sends a TCP FIN packet after writing the data.
      *
+     * Unlike `write()`, `end(data)` accepts the whole chunk. Bytes the socket can't take right away are queued and sent
+     * before the FIN.
+     *
      * @param data Optional final data to write before closing. Same types as `write()`.
      * @param byteOffset Optional offset for buffer data.
      * @param byteLength Optional length for buffer data.
-     * @returns The number of bytes written for the final chunk. Returns `-1` if the socket was already closed or shutting down.
+     * @returns The byte length of the final chunk. Returns `-1` if the socket was already closed or shutting down.
      * @example
      * ```ts
      * // send some data and close the write side
@@ -7167,11 +7185,14 @@ declare module "bun" {
     ref(): void;
 
     /**
-     * Set a timeout until the socket automatically closes.
+     * Call the {@link SocketHandler.timeout `timeout`} handler once, `seconds` seconds from now.
      *
-     * To reset the timeout, call this function again.
+     * The socket stays open. Call {@link end `end()`} or {@link terminate `terminate()`} in the handler to close it.
+     * Both drop the data an earlier `end(data)` queued and the peer hasn't taken yet.
      *
-     * When a timeout happens, the `timeout` callback is called and the socket is closed.
+     * Reads and writes don't restart the timer. To reset the timeout, call this function again. `0` cancels it.
+     *
+     * Bun checks socket timeouts every 4 seconds, so the handler can run up to 4 seconds late. It never runs early.
      */
     timeout(seconds: number): void;
 
@@ -7585,6 +7606,11 @@ declare module "bun" {
 
   interface TLSUpgradeOptions<Data> {
     data?: Data;
+    /**
+     * TLS configuration for the upgraded socket.
+     *
+     * On a client socket, an object that sets no option, such as `{}`, is the same as `true`.
+     */
     tls: TLSOptions | boolean;
     socket: SocketHandler<Data>;
   }
@@ -7622,11 +7648,16 @@ declare module "bun" {
      * handler, this is called only after the handshake completes.
      */
     open?(socket: Socket<Data>): void | Promise<void>;
+    /**
+     * Called once the socket has closed. `error` is set when the connection
+     * failed: a read reported a reset (`syscall: "read"`), or the peer was gone
+     * before the data queued by `end(data)` was sent (`syscall: "write"`).
+     */
     close?(socket: Socket<Data>, error?: Error): void | Promise<void>;
     /**
      * Called when a handler throws, and when an established TLS session fails
-     * (a record that does not decrypt, a fatal alert from the peer). After a
-     * TLS failure the socket closes, with or without this handler.
+     * (a record that does not decrypt, a fatal alert from the peer). After a TLS
+     * failure the socket closes, with or without this handler.
      */
     error?(socket: Socket<Data>, error: Error): void | Promise<void>;
     data?(socket: Socket<Data>, data: BinaryTypeList[DataBinaryType]): void | Promise<void>;
@@ -7661,7 +7692,8 @@ declare module "bun" {
     connectError?(socket: Socket<Data>, error: Error): void | Promise<void>;
 
     /**
-     * Called when a message times out.
+     * Called when the timeout set by {@link Socket.timeout `socket.timeout()`} expires. A socket accepted by
+     * `Bun.listen` starts with a 120 second timeout. The socket stays open.
      */
     timeout?(socket: Socket<Data>): void | Promise<void>;
     /**
@@ -7728,6 +7760,20 @@ declare module "bun" {
      * @default false
      */
     exclusive?: boolean;
+    /**
+     * Set `SO_REUSEPORT` so multiple processes can bind to the same port, which is useful for load balancing.
+     *
+     * Ignored when {@link exclusive} is `true`.
+     *
+     * @default false
+     */
+    reusePort?: boolean;
+    /**
+     * Set `IPV6_V6ONLY` so a socket bound to an IPv6 address doesn't also accept IPv4 connections.
+     *
+     * @default false
+     */
+    ipv6Only?: boolean;
     /**
      * Whether to allow half-open connections.
      *
@@ -7756,22 +7802,24 @@ declare module "bun" {
      */
     port: number;
     /**
-     * TLS configuration with which to create the socket
+     * TLS configuration with which to create the socket.
+     *
+     * `true` or any options object connects with TLS. An object that sets no
+     * option, such as `{}`, is the same as `true`. Omit `tls` or pass `false`
+     * to connect without TLS.
      */
     tls?: TLSOptions | boolean;
     /**
-     * Whether to use exclusive mode.
-     *
-     * When set to `true`, the socket binds exclusively to the specified address:port
-     * combination, preventing other processes from binding to the same port.
-     *
-     * When `false` (default), other sockets may be able to bind to the same port
-     * depending on the operating system's socket sharing capabilities and settings.
-     *
-     * @default false
+     * @deprecated Has no effect on a client socket. This is a {@link Bun.listen} option (see {@link TCPSocketListenOptions}).
      */
     exclusive?: boolean;
+    /**
+     * @deprecated Has no effect on a client socket. This is a {@link Bun.listen} option (see {@link TCPSocketListenOptions}).
+     */
     reusePort?: boolean;
+    /**
+     * @deprecated Has no effect on a client socket. This is a {@link Bun.listen} option (see {@link TCPSocketListenOptions}).
+     */
     ipv6Only?: boolean;
   }
 
@@ -7782,14 +7830,20 @@ declare module "bun" {
     unix: string;
 
     /**
-     * TLS configuration with which to create the socket
+     * TLS configuration with which to create the socket.
+     *
+     * For {@link Bun.connect}, `true` or any options object connects with TLS.
+     * An object that sets no option, such as `{}`, is the same as `true`.
      */
     tls?: TLSOptions | boolean;
   }
 
   interface FdSocketOptions<Data = undefined> extends SocketOptions<Data> {
     /**
-     * TLS configuration with which to create the socket
+     * TLS configuration with which to create the socket.
+     *
+     * `true` or any options object connects with TLS. An object that sets no
+     * option, such as `{}`, is the same as `true`.
      */
     tls?: TLSOptions | boolean;
     /**
@@ -9420,11 +9474,8 @@ declare module "bun" {
       | {
           /**
            * Seconds an idle connection stays in the pool before it is closed.
-           * The socket timer is coarse: it moves in 4 second steps up to four
-           * minutes, and in whole minutes beyond that. Bun rounds the value up
-           * to the timer, so a connection is never closed before `idleTimeout`,
-           * and it can stay open for up to two steps longer. The longest is
-           * 238 minutes (14280), and a larger value means that.
+           * Bun checks socket timers every 4 seconds, so a connection is never
+           * closed before `idleTimeout` and can stay open up to 4 seconds longer.
            *
            * @default 300
            */