bun apis/tcp

13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Attaching contextual data to TCP sockets

Use generic type parameter to type socket data, and assign data to socket.data in the open handler. For example: type SocketData = { sessionId: string }; Bun.listen<SocketData>({...socket: { open(socket) { socket.data = {...}; } }});

Bun.listen() TLS configuration

Enable TLS by passing a tls object with key and cert fields. These fields accept string, BunFile, TypedArray, Buffer, or an array of these types. The values should be the contents of the TLS key and certificate files, not file paths.

TCPSocketListener interface methods

Bun.listen() returns a TCPSocketListener with two methods: stop(closeConnections: boolean) to stop listening and optionally close active connections, and unref() to allow the Bun process to exit even if the server is still listening.

Bun.connect() TCP client basic usage

Create a TCP client connection with Bun.connect() by providing hostname and port. It is an async function that returns a socket. The socket accepts handlers for data, open, close, drain, error, plus client-specific handlers: connectError, end, and timeout.

Bun.connect() client-specific handlers

TCP clients have three additional handlers beyond the standard socket handlers: connectError(socket, error) when connection fails, end(socket) when the server closes the connection, and timeout(socket) when the connection times out.

Bun.connect() TLS requirement

To require TLS for a client connection, pass tls: true in the connection options to Bun.connect().

TCP hot reloading clients

TCP client sockets support hot reloading with socket.reload(). Pass new handler functions to reload specific handlers for that client socket.

Bun TCP sockets do not buffer data

TCP sockets in Bun do not buffer write operations. Multiple small writes perform significantly worse than a single larger write. For performance-sensitive code, manually buffer writes before calling socket.write().

Buffering TCP writes with ArrayBufferSink

Use ArrayBufferSink with {stream: true} option to buffer multiple writes. Create a sink with sink.start({stream: true, highWaterMark: 1024}), write data to it with sink.write(), then flush and send with socket.write(sink.flush()). Check the return value of socket.write() to handle backpressure—if fewer bytes were written than requested, put the remaining data back in the sink.

Bun TCP backpressure management

When socket.write() returns fewer bytes than were passed, the socket buffer is full. Handle backpressure manually using the drain handler until corking support is added.

Bun.listen() TCP server basic usage

Create a TCP server with Bun.listen() by providing hostname, port, and a socket object with event handlers. The socket object can define handlers for: data (message received from client), open (socket opened), close (socket closed), drain (socket ready for more data), and error (error handler). The function returns a server object.

Bun.listen() socket handlers structure

The socket handlers object accepts five event handlers: data(socket, data) for incoming messages, open(socket) for socket connection, close(socket, error) when socket closes, drain(socket) when socket is ready for more data, and error(socket, error) for error conditions. All handlers receive the socket as the first parameter.

Bun.listen() performance: single handler per event

Bun allocates one handler function per event and shares it among all sockets, avoiding garbage collection pressure and memory overhead compared to assigning listeners to each socket individually as in Node.js EventEmitters.

Give your agent this brain