When the network drops
You are building a live dashboard or a chat client. The user steps away, the laptop sleeps, and the Wi-Fi drops. When they return, the screen is frozen. The WebSocket connection is dead. A page refresh wipes local state and frustrates the user. The connection needs to heal itself without any manual intervention.
A naive retry loop fires connection attempts as fast as the CPU allows. If the server is down, you hammer it with thousands of requests per second. This wastes bandwidth, floods logs, and triggers rate limits. The fix is exponential backoff combined with jitter. You wait a short time, then a bit longer, then longer still. You also sprinkle in a random delay so multiple clients do not all retry at the exact same millisecond and crash the server the moment it recovers.
Think of it like knocking on a door. You knock once. No answer. You wait a second and knock again. Still nothing. You wait two seconds, then four. If you also add a random pause between one and three seconds, you avoid standing in a hallway with fifty other people all pounding on the door at the exact same time. The door eventually opens, and the person inside can actually let you in.
Reconnection is a state machine with two states: connected and retrying. The client tries to dial. If it succeeds, it enters the connected state and starts reading messages. If it fails, it enters the retrying state, waits, and tries again. The wait time grows with each failure. This gives the server time to recover and prevents the client from burning resources on a hopeless connection.
Backoff curves are aggressive enough to reconnect quickly after a blip but gentle enough to back off during a prolonged outage. You cap the maximum delay to avoid waiting hours. You also cap the total number of retries. Infinite retries are a trap. If the server is gone, you should eventually give up and let the user decide what to do.
Build the retry loop first. Everything else depends on it.
The retry loop pattern
The growth is exponential. A base delay of one second becomes two seconds, then four, then eight. This curve balances speed and restraint. You calculate the delay using bit shifting. 1<<uint(i) produces powers of two: 1, 2, 4, 8, and so on. This is a fast way to compute exponential growth without floating point math.
Jitter solves the thundering herd problem. The thundering herd happens when many clients retry at the same time. Imagine a server restarts. All connected clients drop their connections. If they all retry instantly, the server receives a massive spike of new connections. The server might crash again. This is a retry storm.
Jitter randomizes the retry time. Each client adds a random delay to its backoff. The delays are distributed over a window. Instead of a spike, you get a smooth ramp of retries. The server can handle the load. The clients reconnect successfully.
The amount of jitter depends on your tolerance for latency. If you need instant reconnection, use small jitter. If you need to protect the server, use larger jitter. A common pattern is to add jitter equal to a fraction of the backoff delay. For example, add a random value between 0 and 50% of the delay. This keeps the retry time bounded while still spreading the load.
The worst reconnection bug is the one that hammers the server into a second outage. Always add jitter.
Minimal reconnection logic
Here is the core retry function. It attempts to dial a WebSocket with exponential backoff and jitter, respects context cancellation, and stops after a fixed number of attempts.
// ConnectWithRetry attempts to dial a WebSocket with exponential backoff.
// It respects context cancellation and stops after maxRetries.
func ConnectWithRetry(ctx context.Context, url string, maxRetries int) error {
var lastErr error
for i := 0; i < maxRetries; i++ {
// Attempt the dial; context passes cancellation signals down
conn, _, err := websocket.DialContext(ctx, url, nil)
if err == nil {
// Connection established; caller takes ownership of conn
return nil
}
lastErr = err
// Base delay doubles each attempt: 1s, 2s, 4s, 8s...
delay := time.Duration(1<<uint(i)) * time.Second
// Add random jitter to prevent thundering herd on recovery
jitter := time.Duration(rand.Intn(1000)) * time.Millisecond
select {
case <-time.After(delay + jitter):
case <-ctx.Done():
return ctx.Err()
}
}
return fmt.Errorf("failed after %d attempts: %w", maxRetries, lastErr)
}
Walk through the mechanics
The loop runs up to maxRetries times. Each iteration calls websocket.DialContext. If the dial succeeds, the function returns immediately. The caller receives the connection and starts using it. If the dial fails, the error is saved in lastErr. The delay calculation uses bit shifting. 1<<uint(i) produces powers of two: 1, 2, 4, 8, and so on. This is a fast way to compute exponential growth without floating point math.
The select statement waits for two channels. The first is a timer created by time.After. It fires after the delay plus jitter. The second is ctx.Done(). This is the cancellation signal. If the context is cancelled, the select picks that case and returns ctx.Err(). This allows the loop to break instantly. Without this, the loop would wait for the full backoff delay even if the application is shutting down.
The rand.Intn(1000) call adds up to one second of random noise. This jitter desynchronizes clients. If ten thousand clients all fail at the same time, they will all retry at slightly different times. This spreads the load and gives the server a chance to recover. Go's math/rand package is automatically seeded in modern versions. You do not need to call rand.Seed manually.
Context cancellation is the backbone of graceful shutdowns in Go. When you pass a context to a blocking call, you are handing the caller a remote control. Pull the trigger, and the blocking call returns immediately. This pattern keeps your application responsive and predictable.
Never ignore the context. Let it drive the lifecycle.
Managing the connection lifecycle
A retry function is useless if you do not integrate it into your application loop. You need a structure that reconnects and keeps reading messages. The tricky part is cleaning up resources when the connection drops. If you use defer inside a loop, you accumulate defers. Each iteration adds a new defer to the stack. When the function finally returns, all defers run. This causes memory leaks and unexpected behavior.
Here is a safe pattern. The outer loop handles reconnection. The inner closure handles the message loop and cleanup. The closure ensures that conn.Close runs when the handler exits, not when the outer function exits.
// RunClient manages a persistent WebSocket connection with automatic reconnection.
// It restarts the message loop whenever the connection drops.
func RunClient(ctx context.Context, url string) {
for {
conn, err := ConnectWithRetry(ctx, url, 10)
if err != nil {
// Retry exhausted or context cancelled; give up
return
}
// Run handler in a closure to scope the defer correctly
func() {
defer conn.Close(websocket.StatusNormalClosure, "")
handleMessageLoop(ctx, conn)
}()
// Loop continues to reconnect
}
}
The closure creates a new scope for each connection. When handleMessageLoop returns, the defer fires and closes the connection. The outer loop then restarts and calls ConnectWithRetry again. This pattern keeps resources clean. It also respects the context. If ctx is cancelled, ConnectWithRetry returns an error, and the function exits.
Go functions that take a context should always put it as the first argument, named ctx. This convention lets tools and readers spot the cancellation path immediately. Functions that accept a context must respect cancellation and deadlines. If you ignore the context, you break the contract.
Receiver names follow a similar convention. Keep them short and matching the type. (c *Client) Read() is standard. (this *Client) or (self *Client) breaks community expectations and makes code reviews slower.
Scope your defers tightly. Let each connection clean up after itself.
Pitfalls and compiler errors
Goroutine leaks are the most common bug in reconnection logic. If you spawn a goroutine to read messages but do not stop it when reconnecting, you leak goroutines. The old goroutine waits on a closed channel or a dead connection. It never exits. Over time, your application consumes memory and CPU. Always have a cancellation path. Pass the context to the reader goroutine. Close the channel when the connection drops.
Compiler errors catch type mistakes early. If you try to wrap the WebSocket connection incorrectly, the compiler rejects the program with cannot use conn (type *websocket.Conn) as type io.Reader in argument. This happens when you pass the connection to a function that expects a generic reader. WebSockets are not simple streams. They have frames and headers. You must use the library's API.
If you forget to import a package, you get undefined: pkg from the compiler. If you import a package but do not use it, you get imported and not used. Go enforces clean imports. Remove unused imports to keep the code tidy.
The if err != nil pattern is verbose by design. The community accepts the boilerplate because it makes the unhappy path visible. Do not hide errors. Check them immediately. Return them or wrap them with fmt.Errorf. This keeps error handling explicit and traceable.
Trust gofmt. Argue logic, not formatting. The code blocks follow standard formatting. Most editors run gofmt on save. Let the tool decide indentation and spacing. Focus on the algorithm.
The worst goroutine bug is the one that never logs. Always trace your lifecycles.
Decision: reconnection strategies
Use exponential backoff with jitter when the server might be overloaded or recovering, to spread retry load over time. Use a fixed retry interval when you need predictable latency and the failure is transient, like a momentary packet loss. Use immediate retry with a circuit breaker when the failure is likely local, such as a DNS glitch, and you want to fail fast on persistent outages. Use a manual reconnect button when the user should control recovery, such as in a secure session that requires re-authentication.