Use Bun's native TCP API to implement performance sensitive systems like database clients, game servers, or anything that needs to communicate over TCP (instead of HTTP). This is a low-level API intended for library authors and for advanced use cases. ## Start a server (`Bun.listen()`) To start a TCP server with `Bun.listen`: ```ts Bun.listen({ hostname: "localhost", port: 8080, socket: { data(socket, data) {}, // message received from client open(socket) {}, // socket opened close(socket) {}, // socket closed drain(socket) {}, // socket ready for more data error(socket, error) {}, // error handler }, }); ``` {% details summary="An API designed for speed" %} In Bun, a set of handlers are declared once per server instead of assigning callbacks to each socket, as with Node.js `EventEmitters` or the web-standard `WebSocket` API. ```ts Bun.listen({ hostname: "localhost", port: 8080, socket: { open(socket) {}, data(socket, data) {}, drain(socket) {}, close(socket) {}, error(socket, error) {}, }, }); ``` For performance-sensitive servers, assigning listeners to each socket can cause significant garbage collector pressure and increase memory usage. By contrast, Bun only allocates one handler function for each event and shares it among all sockets. This is a small optimization, but it adds up. {% /details %} Contextual data can be attached to a socket in the `open` handler. ```ts type SocketData = { sessionId: string }; Bun.listen({ hostname: "localhost", port: 8080, socket: { data(socket, data) { socket.write(`${socket.data.sessionId}: ack`); }, open(socket) { socket.data = { sessionId: "abcd" }; }, }, }); ``` To enable TLS, pass a `tls` object containing `key` and `cert` fields. ```ts Bun.listen({ hostname: "localhost", port: 8080, socket: { data(socket, data) {}, }, tls: { // can be string, BunFile, TypedArray, Buffer, or array thereof key: Bun.file("./key.pem"), cert: Bun.file("./cert.pem"), }, }); ``` The `key` and `cert` fields expect the _contents_ of your TLS key and certificate. This can be a string, `BunFile`, `TypedArray`, or `Buffer`. ```ts Bun.listen({ // ... tls: { // BunFile key: Bun.file("./key.pem"), // Buffer key: fs.readFileSync("./key.pem"), // string key: fs.readFileSync("./key.pem", "utf8"), // array of above key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")], }, }); ``` The result of `Bun.listen` is a server that conforms to the `TCPSocket` interface. ```ts const server = Bun.listen({ /* config*/ }); // stop listening // parameter determines whether active connections are closed server.stop(true); // let Bun process exit even if server is still listening server.unref(); ``` ## Create a connection (`Bun.connect()`) Use `Bun.connect` to connect to a TCP server. Specify the server to connect to with `hostname` and `port`. TCP clients can define the same set of handlers as `Bun.listen`, plus a couple client-specific handlers. ```ts // The client const socket = Bun.connect({ hostname: "localhost", port: 8080, socket: { data(socket, data) {}, open(socket) {}, close(socket) {}, drain(socket) {}, error(socket, error) {}, // client-specific handlers connectError(socket, error) {}, // connection failed end(socket) {}, // connection closed by server timeout(socket) {}, // connection timed out }, }); ``` To require TLS, specify `tls: true`. ```ts // The client const socket = Bun.connect({ // ... config tls: true, }); ``` ## Hot reloading Both TCP servers and sockets can be hot reloaded with new handlers. {% codetabs %} ```ts#Server const server = Bun.listen({ /* config */ }) // reloads handlers for all active server-side sockets server.reload({ socket: { data(){ // new 'data' handler } } }) ``` ```ts#Client const socket = Bun.connect({ /* config */ }) socket.reload({ data(){ // new 'data' handler } }) ``` {% /codetabs %} ## Buffering Currently, TCP sockets in Bun do not buffer data. For performance-sensitive code, it's important to consider buffering carefully. For example, this: ```ts socket.write("h"); socket.write("e"); socket.write("l"); socket.write("l"); socket.write("o"); ``` ...performs significantly worse than this: ```ts socket.write("hello"); ``` To simplify this for now, consider using Bun's `ArrayBufferSink` with the `{stream: true}` option: ```ts const sink = new ArrayBufferSink({ stream: true, highWaterMark: 1024 }); sink.write("h"); sink.write("e"); sink.write("l"); sink.write("l"); sink.write("o"); queueMicrotask(() => { var data = sink.flush(); if (!socket.write(data)) { // put it back in the sink if the socket is full sink.write(data); } }); ``` {% callout %} **Corking** — Support for corking is planned, but in the meantime backpressure must be managed manually with the `drain` handler. {% /callout %} e='feat/ecosystem'>feat/ecosystem Unnamed repository; edit this file 'description' to name the repository.
aboutsummaryrefslogtreecommitdiff
path: root/integration/snippets/code-simplification-neql-define.js (unfollow)
AgeCommit message (Expand)AuthorFilesLines
2022-01-20Fix segfaultGravatar Jarred Sumner 3-6/+12
2022-01-19Bun.Transpiler – API for scanning imports/exports of JSX/TSX/TS/JS filesGravatar Jarred Sumner 24-75/+1082
2022-01-19Update MakefileGravatar Jarred Sumner 1-7/+18
2022-01-19Update MakefileGravatar Jarred Sumner 1-2/+10
2022-01-19Update DockerfileGravatar Jarred Sumner 1-0/+20
2022-01-19Update MakefileGravatar Jarred Sumner 1-1/+0
2022-01-19Update libbacktraceGravatar Jarred Sumner 1-0/+0
2022-01-19Update Dockerfile.baseGravatar Jarred Sumner 1-1/+1
2022-01-19Update release.shGravatar Jarred Sumner 1-1/+1
2022-01-19small bugfixGravatar Jarred Sumner 1-6/+6
2022-01-19Update fs.test.jsGravatar Jarred Sumner 1-12/+6
2022-01-19O3Gravatar Jarred Sumner 1-1/+1
2022-01-19`fs.*Sync()`, `bun wiptest`, and More ™ (#106)Gravatar Jarred Sumner 186-2836/+17233
2022-01-05Fix bug preventing multiple framework overridesGravatar Jarred Sumner 1-2/+3
2022-01-05Reduce memory usageGravatar Jarred Sumner 1-2/+2
2022-01-05Fix crash that sometimes happens after 30 secondsGravatar Jarred Sumner 5-106/+185
2022-01-05[bun bun][bun dev] Fix crash affecting large projectsGravatar Jarred Sumner 1-26/+119
2022-01-05move some code aroundGravatar Jarred Sumner 2-281/+284
2022-01-05we want the opposite of thisGravatar Jarred Sumner 1-1/+0
2022-01-05[JS Parser] Reduce memory usage by ~8%Gravatar Jarred Sumner 6-7/+42
2022-01-05minimal integration tests for macrosGravatar Jarred Sumner 4-0/+47
2022-01-05Update resolver.zigGravatar Jarred Sumner 1-3/+0
2022-01-05Update options.zigGravatar Jarred Sumner 1-2/+25
2022-01-05Update http.zigGravatar Jarred Sumner 1-1/+1
2022-01-05Add module condition to the node platform (#104)Gravatar Mateusz Burzyński 1-1/+4
2022-01-05Drop redundant comments (#103)Gravatar Mateusz Burzyński 1-23/+0
2022-01-05Tweak default main fields for the bun platform to match other popular bundler...Gravatar Mateusz Burzyński 1-10/+7
2022-01-04:skull: dead codeGravatar Jarred Sumner 1-13/+0
2022-01-04[bun dev] Print error in status line textGravatar Jarred Sumner 1-3/+13
2022-01-04noramlize some errorsGravatar Jarred Sumner 3-3/+4
2022-01-04[Bun.js][bun dev] Support macros inside of Bun.jsGravatar Jarred Sumner 5-51/+103
2022-01-04[bun bun] Fix error when regenerating node_modules.bun after moving itGravatar Jarred Sumner 1-1/+17
2022-01-04Improve how we detect if terminal colors are supportedGravatar Jarred Sumner 3-11/+66
2022-01-04Improve error handling when out of file handlesGravatar Jarred Sumner 5-58/+248
2022-01-04Update build-idGravatar Jarred Sumner 1-1/+1
2022-01-04Downgrade mimalloc due to crashesGravatar Jarred Sumner 1-0/+0
2022-01-04Upload compressed `.dSYM` for every releaseGravatar Jarred Sumner 2-4/+34
2022-01-04Update .gitignoreGravatar Jarred Sumner 1-0/+3
2022-01-04[bun install] Fix more cases where bytes are printed instead of stringsGravatar Jarred Sumner 1-10/+38
2022-01-04minor perf optimization: remove this loop on macOSGravatar Jarred Sumner 2-4/+8
2022-01-03Update crash_reporter_linux.zigbun-v0.0.66Gravatar Jarred Sumner 1-1/+1
2022-01-03:confused:Gravatar Jarred Sumner 5-0/+1
2022-01-03:nail_care:Gravatar Jarred Sumner 3-1652/+1826
2022-01-03Update crash_reporter_linux.zigGravatar Jarred Sumner 1-1/+1
2022-01-03Update PLCrashReport.mGravatar Jarred Sumner 1-1/+1
2022-01-03Update PLCrashReport.mGravatar Jarred Sumner 1-2/+1
2022-01-03:lock:Gravatar Jarred Sumner 4-1/+1
2022-01-03dead codeGravatar Jarred Sumner 13-1881/+1660