diff --git a/README.md b/README.md index b7ba35323c..84567b758e 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,7 @@ bun upgrade --canary - [Hot reload an HTTP server](https://bun.sh/guides/http/hot) - [Proxy HTTP requests using fetch()](https://bun.sh/guides/http/proxy) - [Send an HTTP request using fetch](https://bun.sh/guides/http/fetch) + - [Start a cluster of HTTP servers](https://bun.sh/guides/http/cluster) - [Stream a file as an HTTP Response](https://bun.sh/guides/http/stream-file) - [Streaming HTTP Server with Async Iterators](https://bun.sh/guides/http/stream-iterator) - [Streaming HTTP Server with Node.js Streams](https://bun.sh/guides/http/stream-node-streams-in-bun) diff --git a/docs/guides/http/cluster.md b/docs/guides/http/cluster.md new file mode 100644 index 0000000000..0e2325afa4 --- /dev/null +++ b/docs/guides/http/cluster.md @@ -0,0 +1,66 @@ +--- +name: Start a cluster of HTTP servers +description: Run multiple concurrent HTTP servers via the "reusePort" option to share the same port across multiple processes +--- + +To run multiple concurrent HTTP servers, use the `reusePort` option in `Bun.serve()` to share the same port across multiple processes. + +This automatically load balances incoming requests across multiple instances of Bun. + +```ts#server.ts +import { serve } from "bun"; + +const id = = Math.random().toString(36).slice(2); + +serve({ + port: process.env.PORT || 8080, + development: false, + + // Share the same port across multiple processes + // This is the important part! + reusePort: true, + + async fetch(request) { + return new Response("Hello from Bun #" + id + "!\n"); + } +}); +``` + +--- + +{% callout %} +**Linux only** — Windows and macOS ignore the `reusePort` option. This is an operating system limitation with `SO_REUSEPORT`, unfortunately. +{% /callout %} + +After saving the file, start your servers on the same port. + +Under the hood, this uses the Linux `SO_REUSEPORT` and `SO_REUSEADDR` socket options to ensure fair load balancing across multiple processes. [Learn more about `SO_REUSEPORT` and `SO_REUSEADDR`](https://lwn.net/Articles/542629/) + +```ts#cluster.ts +import { spawn } from "bun"; + +const cpus = navigator.hardwareConcurrency; // Number of CPU cores +const buns = new Array(cpus); + +for (let i = 0; i < cpus; i++) { + buns[i] = spawn({ + cmd: ["bun", "./server.ts"], + stdout: "inherit", + stderr: "inherit", + stdin: "inherit", + }); +} + +function kill() { + for (const bun of buns) { + bun.kill(); + } +} + +process.on("SIGINT", kill); +process.on("exit", kill); +``` + +--- + +At the time of writing, Bun hasn't implemented the `node:cluster` module yet, but this is a faster, simple, and limited alternative. We will also implement `node:cluster` in the future.