Bun.TCPSocket TypeScript interface | API Reference | Bun

Represents a TCP or TLS socket connection used for network communication. This interface provides methods for reading, writing, managing the connection state, and handling TLS-specific features if applicable.

Sockets are created using Bun.connect() or accepted by a Bun.listen() server.

String containing the selected ALPN protocol. Before a handshake has completed, this value is always null. When a handshake is completed but not ALPN protocol was selected, socket.alpnProtocol equals false.

This property is true if the peer certificate was signed by one of the CAs specified when creating the Socket instance, otherwise false.

The total number of bytes successfully written to the socket since it was established. This includes data currently buffered by the OS but not yet acknowledged by the remote peer.

The user-defined data associated with this socket instance. This can be set when the socket is created via Bun.connect({ data: ... }). It can be read or updated at any time.

// In a socket handler
function open(socket: Socket: string }>) {
console.log(`Socket opened for user: ${socket.data.userId}`);
socket.data.lastActivity = Date.now(); // Update data
}

Get the server that created this socket

This will return undefined if the socket was created by Bun.connect or if the listener has already closed.

Local IP address connected to the socket

"192.168.1.100" | "2001:db8::1"

IP protocol family used for the local endpoint of the socket

"IPv4" | "IPv6"

local port connected to the socket

8080

The ready state of the socket.

You can assume that a positive value means the socket is open and usable

Remote IP address connected to the socket

"192.168.1.100" | "2001:db8::1"

Remote port connected to the socket

8080

Alias for socket.end(). Allows the socket to be used with using declarations for automatic resource management.

async function processSocket() {
using socket = await Bun.connect({ ... });
socket.write("Data");
// socket.end() is called automatically when exiting the scope
}

Closes the socket.

This is a wrapper around end() and shutdown().

Disables TLS renegotiation for this Socket instance. Once called, attempts to renegotiate will trigger an error handler on the Socket.

There is no support for renegotiation as a server. (Attempts by clients will result in a fatal alert so that ClientHello messages cannot be used to flood a server and escape higher-level limits.)

Sends the final data chunk and initiates a graceful shutdown of the socket's write side. After calling end(), no more data can be written using write() or end(). 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.

Optional final data to write before closing. Same types as write().

Optional offset for buffer data.

Optional length for buffer data.

The number of bytes written for the final chunk. Returns -1 if the socket was already closed or shutting down.

// send some data and close the write side
socket.end("Goodbye!");
// or close write side without sending final data
socket.end();

Close the socket immediately

Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

Example

const keyingMaterial = socket.exportKeyingMaterial(
128,
'client finished');

/*
Example return value of keyingMaterial:

12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
74 ef 2c ... 78 more bytes>

number of bytes to retrieve from keying material

an application specific label, typically this will be a value from the IANA Exporter Label Registry.

Optionally provide a context.

requested bytes of the keying material

Exports the keying material of the socket.

The length of the keying material to export.

The label of the keying material to export.

The context of the keying material to export.

Flush any buffered data to the socket This attempts to send the data immediately, but success depends on the network conditions and the receiving end. It might be necessary after several write calls if immediate sending is critical, though often the OS handles flushing efficiently. Note that write calls outside open/data/drain might benefit from manual cork/flush.

Returns the reason why the peer's certificate was not been verified. This property is set only when socket.authorized === false.

Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

Returns an object containing information on the negotiated cipher suite.

For example, a TLSv1.2 protocol with AES256-SHA cipher:

{
"name": "AES256-SHA",
"standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
"version": "SSLv3"
}

Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. Thename property is available only when type is 'ECDH'.

For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.

Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

If the full certificate chain was requested, each certificate will include anissuerCertificate property containing an object representing its issuer's certificate.

A certificate object.

Returns the servername of the socket.

See SSL_get_shared_sigalgs for more information.

List of signature algorithms shared between the server and the client in the order of decreasing preference.

As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

The latest Finished message that has been sent to the socket as part of a SSL/TLS handshake, or undefined if no Finished message has been sent yet.

As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

The latest Finished message that is expected or has actually been received from the socket as part of a SSL/TLS handshake, or undefined if there is no Finished message so far.

For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.

It may be useful for debugging.

See Session Resumption for more information.

Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

Protocol versions are:

See Session Resumption for more information.

true if the session was reused, false otherwise. TLS Only: Checks if the current TLS session was resumed from a previous session. Returns true if the session was resumed, false otherwise.

Keep Bun's process alive at least until this socket is closed

After the socket has closed, the socket is unref'd, the process may exit, and this becomes a no-op

Reset the socket's callbacks. This is useful with bun --hot to facilitate hot reloading.

This will apply to all sockets from the same Listener. it is per socket only for Bun.connect.

If this is a TLS Socket

Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. Set initialDelay (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Only available for already connected sockets, will return false otherwise.

Enabling the keep-alive functionality will set the following socket options: SO_KEEPALIVE=1 TCP_KEEPIDLE=initialDelay TCP_KEEPCNT=10 TCP_KEEPINTVL=1

Default: false

Default: 0

true if is able to setNoDelay and false if it fails.

The socket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.

The maximum TLS fragment size. The maximum value is 16384.

Enable/disable the use of Nagle's algorithm. Only available for already connected sockets, will return false otherwise

Default: true

true if is able to setNoDelay and false if it fails.

Sets the servername of the socket.

Sets the session of the socket.

The session to set.

Sets the verify mode of the socket.

Whether to request a certificate.

Whether to reject unauthorized certificates.

Shuts down the write-half or both halves of the connection. This allows the socket to enter a half-closed state where it can still receive data but can no longer send data (halfClose = true), or close both read and write (halfClose = false, similar to end() but potentially more immediate depending on OS). Calls shutdown(2) syscall internally.

If true, only shuts down the write side (allows receiving). If false or omitted, shuts down both read and write. Defaults to false.

// Stop sending data, but allow receiving
socket.shutdown(true);

// Shutdown both reading and writing
socket.shutdown();

Forcefully closes the socket connection immediately. This is an abrupt termination, unlike the graceful shutdown initiated by end(). It uses SO_LINGER with l_onoff=1 and l_linger=0 before calling close(2). Consider using close() or end() for graceful shutdowns.

socket.terminate();

Set a timeout until the socket automatically closes.

To reset the timeout, call this function again.

When a timeout happens, the timeout callback is called and the socket is closed.

Allow Bun's process to exit even if this socket is still open

After the socket has closed, this function does nothing.

Upgrades the socket to a TLS socket.

The options for the upgrade.

A tuple containing the raw socket and the TLS socket.

Writes data to the socket. This method is unbuffered and non-blocking. This uses the sendto(2) syscall internally.

For optimal performance with multiple small writes, consider batching multiple writes together into a single socket.write() call.

The data to write. Can be a string (encoded as UTF-8), ArrayBuffer, TypedArray, or DataView.

The offset in bytes within the buffer to start writing from. Defaults to 0. Ignored for strings.

The number of bytes to write from the buffer. Defaults to the remaining length of the buffer from the offset. Ignored for strings.

The number of bytes written. Returns -1 if the socket is closed or shutting down. Can return less than the input size if the socket's buffer is full (backpressure).

// Send a string
const bytesWritten = socket.write("Hello, world!\n");

// Send binary data
const buffer = new Uint8Array([0x01, 0x02, 0x03]);
socket.write(buffer);

// Send part of a buffer
const largeBuffer = new Uint8Array(1024);
// ... fill largeBuffer ...
socket.write(largeBuffer, 100, 50); // Write 50 bytes starting from index 100