# Add WebSockets to a Fiber App

Yes. An agent adds a /ws endpoint to your Fiber v3 app with the contrib websocket module, broadcasts new users to open connections, tests it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-websockets/fiber/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the app before it adds a socket to it. In an app laid out like gofiber/boilerplate, `go.mod` declares module `boilerplate` on `go 1.26.0` with `github.com/gofiber/fiber/v3 v3.6.1` and `gofiber/utils/v2`. `app.go` parses `-port` (default `:3000`) and `-prod`, which turns on prefork through `fiber.ListenConfig{EnablePrefork: *prod}`, installs `recover` and `logger`, mounts `GET /api/v1/users` and `POST /api/v1/users` on `handlers.UserList` and `handlers.UserCreate`, serves `./static/public` with the `static` middleware, and ends with `handlers.NotFound` sending `static/private/404.html`. `database/database.go` is a slice of `*models.User` behind a `sync.Mutex`; `models.User` has one field, `Name`. `handlers.UserCreate` copies `c.FormValue("user")` with `utils.CopyString` because fasthttp reuses its buffers. `static/public/js/app.js` fetches the user list on load and, after a successful POST, inserts the new `<li>` at the top itself. `.github/workflows/test.yml` runs `go test ./... -v -race` on Go 1.26.x and 1.27.x on Ubuntu and Windows runners, `lint.yml` runs golangci-lint v2.14.0 with `--tests=false`, and `.golangci.yml` enables `modernize`. There are no test files.

The socket comes from `github.com/gofiber/contrib/v3/websocket`, the contrib module built on `fasthttp/websocket` for Fiber v3 (its own `go.mod` requires `fiber/v3 v3.6.1`). The agent adds `handlers/ws.go` with a hub: a set of `*websocket.Conn` behind a mutex, `Register`, `Unregister` and `Broadcast`, with all writes going through the hub so no connection ever has two concurrent writers. The route follows the module's README: `app.Use("/ws", ...)` lets a request through only when `websocket.IsWebSocketUpgrade(c)` is true and answers `fiber.ErrUpgradeRequired` otherwise, and `app.Get("/ws", websocket.New(handler, websocket.Config{Origins: ...}))` upgrades it. The handler registers the connection, reads frames in a loop with `ReadMessage` until the client goes away, and unregisters on exit.

`handlers.UserCreate` keeps its JSON response and gains one line after `database.Insert`: a `Broadcast` of `{"type": "user.created", "user": {"name": ...}}` to every open connection. `app.js` opens `new WebSocket(...)` against `location.host` with `ws:` or `wss:` chosen from `location.protocol`, prepends an `<li>` for each `user.created` message, and no longer inserts the row itself after a POST, so the tab that added the user and every other tab render it exactly once. A small reconnect with backoff handles a dropped connection.

Two things the app's own flags force into the open. With `-prod`, prefork runs several processes and each has its own hub and its own in-memory `db`, so a broadcast reaches only the connections on the process that handled the POST; the agent writes this in the README and the pull request and names a shared pub/sub as the next step rather than hiding it. And `app.Test` cannot upgrade a connection, so the tests in `handlers/ws_test.go` start the app on a `net.Listener` bound to port 0, dial that listener with the `fasthttp/websocket` client from two goroutines, POST a user with `net/http`, and assert both clients receive the same frame; a third test sends a plain `GET /ws` and expects 426. `go test ./... -race` and `golangci-lint run` pass before the pull request opens.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add WebSocket support to this Fiber v3 app. Read go.mod, app.go, handlers/handlers.go, database/database.go, models/user.go, static/public/index.html, static/public/js/app.js, Makefile, Dockerfile, .golangci.yml and the workflows under .github first. Add github.com/gofiber/contrib/v3/websocket, create handlers/ws.go with a hub that registers connections, unregisters them when they close, and broadcasts with a single writer per connection. Guard /ws with websocket.IsWebSocketUpgrade and answer fiber.ErrUpgradeRequired otherwise. After database.Insert in UserCreate, broadcast a user.created event with the user, and change app.js so new users arrive over the socket instead of being inserted after the POST, with a reconnect on close. Write tests that start the app on a listener bound to port 0, connect two websocket clients, POST a user and assert both receive it, plus a test that a plain GET /ws returns 426. Document in the README that prefork gives each process its own hub. Run go test ./... -race and golangci-lint run, then open a pull request that quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `handlers/ws.go` and `handlers/ws_test.go`, changes `app.go` (the `/ws` guard and route), `handlers/handlers.go` (one broadcast after the insert), `static/public/js/app.js` (the socket, the reconnect, the removed local insert), `go.mod` and `go.sum` (the contrib module and `fasthttp/websocket`), and the README (the prefork note and the message shape). Its description quotes the `go test -race` output and the lint run, and shows the JSON a client receives.

A reviewer opens two browser tabs on the branch, adds a user in one and watches it appear in the other, then reads the hub for the two things that go wrong in socket code: a write from a goroutine that does not own the connection, and a connection left in the set after its read loop returned. They decide whether `Origins` should be set now or when the app has a real domain, and whether the user list should be sent on connect so a late tab catches up.

The prefork limitation is stated, not solved, which is the honest shape of this change for an app whose storage is a slice.

## Run it on every Linear issue labelled realtime

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `realtime` starts one run per feature that needs a push channel. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to read the event name and payload from the issue and to reuse the hub in `handlers/ws.go` once it exists, rather than opening a second socket per feature.

A team with several Fiber services sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` with a `request_id` that is a UUID v5 of the repository name, so a retried call returns the run it already started. Each run reads its own handlers and decides what the first broadcast should carry.

## Why run it on Rush?

WebSocket code is easy to write and hard to prove: the bugs are concurrent writes, leaked connections and a broadcast that works on one process and not on four. The agent runs the real server in its own sandbox, drives it with two clients, runs the suite under the race detector, and keeps the output with the pull request, so the first evidence a reviewer sees is a passing test rather than a screenshot.

The reviewer reads a hub, a route and a test instead of a tutorial. A team with several Go services starts the same request across all of them at once, and each pull request is specific to the handlers it found.

## Frequently asked questions

### Which websocket package does it use for Fiber v3?

`github.com/gofiber/contrib/v3/websocket`, the contrib module whose README says it is compatible with Fiber v3 and whose `go.mod` requires `fiber/v3`. It wraps `fasthttp/websocket` and exposes `Locals`, `Params`, `Query` and `Cookies` on the connection.

### Does it work with prefork?

The endpoint works, the broadcast does not cross processes: with `-prod` each forked process has its own hub and its own in-memory user slice. The pull request says so and points at a shared pub/sub (Redis or NATS) as the way to fan out across processes when the app gets a real database.

### How are the tests run without a browser?

The tests bind a `net.Listener` to port 0, hand it to the app, and connect with the `fasthttp/websocket` client. `app.Test` serves requests in memory and cannot complete an upgrade, which is why the agent uses a real listener for these tests only.

### Will the REST endpoints change?

`GET` and `POST /api/v1/users` keep their responses. The only change in `handlers.go` is a broadcast after the insert, so a client that never opens the socket behaves as before.

### What about origins?

The config's `Origins` list is empty by default, which allows every origin. The agent leaves it configurable from a flag or environment variable and notes in the review that a public deployment should set it to the site's own origin.

## More Fiber jobs

- [Review Pull Requests on a Fiber v3 App](https://getrush.ai/run/review-pull-requests/fiber/)
- [Write Handler Tests for a Fiber Auth API](https://getrush.ai/run/write-handler-tests/fiber/)
- [Write Unit Tests for a Fiber v3 App](https://getrush.ai/run/write-unit-tests/fiber/)

## The same job on other stacks

- [Add WebSockets to a Leptos App](https://getrush.ai/run/add-websockets/leptos/)
- [Add WebSockets to a Litestar App](https://getrush.ai/run/add-websockets/litestar/)
- [Add a WebSocket Endpoint to a Vapor App from a Linear Issue](https://getrush.ai/run/add-websockets/vapor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
