Build a Real-Time Chat App with WebSockets

What are WebSockets?

When you load a web page, your browser sends an HTTP request and the server sends a response. The connection closes. If you want new data, you have to ask again. This works fine for loading pages, but it's terrible for real-time features. Imagine a chat app where you have to refresh the page to see new messages.

The difference between HTTP and WebSocket:

HTTP (Request-Response):
  Client: "Any new messages?"     → Server: "No."
  Client: "Any new messages?"     → Server: "No."
  Client: "Any new messages?"     → Server: "Yes! Here's one."
  Client: "Any new messages?"     → Server: "No."
  (Wasteful: constant polling)

WebSocket (Persistent Connection):
  Client: "Open connection"       → Server: "Connected."
  ...
  Server: "New message from John!"  (pushed instantly)
  Server: "Jane is typing..."      (pushed instantly)
  Server: "New message from Jane!" (pushed instantly)
  (Efficient: data pushed only when it exists)

Real-world WebSocket use cases:

• • Chat applications: Slack, Discord, WhatsApp Web
• • Live notifications: GitHub, Twitter, Facebook
• • Collaborative editing: Google Docs, Figma, Notion
• • Real-time dashboards: stock prices, analytics, monitoring
• • Multiplayer games: real-time game state synchronization

The hub you already have

You do not install anything for this course. Every Grit project is scaffolded with a WebSocket hub in apps/api/internal/realtime, one endpoint atGET /api/ws, and a client in each frontend at lib/realtime.tswith hooks in hooks/use-realtime.ts. It is wired intoroutes.Setup before you write a line.

What the hub gives you:

• • One socket per app: the client opens it once and every component shares it
• • Authentication: the same JWT as the REST API, from the HttpOnly cookie in a browser
• • Channels: named groups with an authorizer you write, which is what a chat room is
• • Presence: a live member list per channel, kept in Redis so it survives a replica dying
• • Client events: browser to browser, which is how a typing indicator costs nothing
• • Reconnection: exponential backoff with jitter, and every subscription restored afterwards
• • More than one replica: a Redis backplane, on by default wherever the project has Redis

Channels are rooms

A chat room is a set of people who should see the same messages, which is exactly what a channel is. The client asks to join one by name, the server decides whether it may, and anything published on that channel reaches every connection that joined it, on every replica.

presence-rooms.general     a room, with a member list
presence-rooms.support     another room
private-users.u_42         one user's private feed, no member list
public-status              anything signed in may watch

// the pattern you register is the name without the prefix:
//   rooms.{id}  covers presence-rooms.general and private-rooms.general

Who is allowed in

An authorizer is a function that answers one question: may this user subscribe to this channel? It runs on every subscribe, including the ones after a reconnect, so a user removed from a room loses it the next time their connection drops. Register the patterns once, where the hub is built.

// after realtimeHub := realtime.NewHub(realtimeOptions...)

realtime.Channel("rooms.{id}", func(c realtime.ChannelContext) bool {
    room := c.Param("id")
    user, err := services.UserByID(db, c.UserID)
    if err != nil || !services.IsRoomMember(db, user.ID, room) {
        return false
    }
    // Travels with the member in the presence list. Only put in here what
    // every other member of the room is allowed to see.
    c.SetInfo(map[string]any{"name": user.Name, "avatar": user.AvatarURL})
    return true
})

Three things worth knowing about the authorizer:

• • It runs on the connection's own goroutine, so keep it to a query or two. A slow authorizer is a slow subscribe for that one client.
• • A panic inside it refuses the subscription instead of taking the API down.
• • c.SetInfo is the only way a member's name and avatar reach the other clients. Set it here, from the database, not from anything the client sent.

Subscribing from React

You do not write new WebSocket(...). The scaffolded client owns one connection for the whole app, reconnects on its own and resubscribes afterwards.useChannel joins a channel for as long as the component is mounted and hands each event to the handler named after it.

import { useChannel, useRealtimeStatus } from '@/hooks/use-realtime'
import { useQueryClient } from '@tanstack/react-query'

export function ChatRoom({ room }: { room: string }) {
  const queryClient = useQueryClient()
  const status = useRealtimeStatus()           // 'connecting' | 'open' | 'closed'
  const channel = 'presence-rooms.' + room

  useChannel(channel, {
    'messages.created': (message) => {
      queryClient.setQueryData(['messages', room], (old: Message[] = []) =>
        old.some((m) => m.id === message.id) ? old : [...old, message],
      )
    },
    subscription_error: (p) => console.warn('cannot join ' + room, p.message),
  })

  // ... render the message list and the input
}

Two details that save an afternoon each. Handlers are read through a ref, so an inline object literal does not tear the subscription down and rebuild it on every render. And passing null as the channel is allowed: use it while the room name is still loading, rather than mounting the component later.

Sending a message: in by REST, out by channel

A chat message is a row in the database. It is created the way every other row is created, by a POST to the REST API, where validation, authorization, rate limiting and the audit log already live. The socket is how everyone else hears about it, not how it is written.

func (h *MessageHandler) Create(c *gin.Context) {
    var req CreateMessageRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        respond.ValidationError(c, err)
        return
    }
    message, err := h.Service.Create(c.Request.Context(), actor(c), req)
    if err != nil {
        respond.Error(c, err)
        return
    }

    // Everyone in the room, on every replica. Never the whole hub.
    h.Hub.Publish("presence-rooms."+message.Room, realtime.Event{
        Type:    "messages.created",
        Payload: message,
    })
    respond.Created(c, message)
}

Building the chat UI

A chat UI has four parts: a scrollable message list, an input, a connection indicator and, once you add presence, a member list. React Query holds the messages, the channel updates the same cache, and nothing polls.

ChatRoom({ room })

  useQuery(['messages', room])        history, one REST call on open
  useChannel('presence-rooms.'+room)  new messages into the same cache
  usePresence('presence-rooms.'+room) who is here
  useRealtimeStatus()                 the dot in the header

  <header>   room name, member avatars, status dot
  <ul>       messages, ref on the container, scroll to bottom on change
  <form>     input, POST /api/messages, clear on success

• • Auto-scroll: keep a ref on the list and scroll to scrollHeight in an effect on the message array, not in the socket handler
• • Optimistic send: add the message to the cache before the POST returns, and dedupe by id when the channel echoes it back
• • Status: closed means the user is looking at stale data. Say so, do not hide it
• • Escape everything: a message is user input, and so is every whisper below

Presence: who is in the room

Subscribing to a presence- channel gets you apresence.members snapshot, and everyone already there getspresence.joined. Closing the last socket a user holds on the channel sendspresence.left. One hook does all of it.

import { usePresence } from '@/hooks/use-realtime'

type Member = { name: string; avatar?: string }

export function RoomMembers({ room }: { room: string }) {
  const members = usePresence<Member>('presence-rooms.' + room)
  return (
    <div>
      <p>{members.length} here</p>
      <ul>
        {members.map((m) => (
          <li key={m.user_id}>{m.info?.name ?? m.user_id}</li>
        ))}
      </ul>
    </div>
  )
}

A user appears once however many tabs they have open, and only leaves when the last one closes. The list lives in Redis with a TTL the heartbeat refreshes, so a replica that is killed takes its members out within about a minute instead of leaving ghosts in the room forever. While the connection is down the list is empty, and it refills from a fresh snapshot when it is back, so nobody is shown who has since gone.

Typing indicators, with nothing stored

"Ada is typing" is worth telling the room right now and worth nothing a second later. It should not be a REST call, it should not be a row, and it should not go through the database at all. That is what a client event is: one browser to the others in the channel, through the hub, with the server storing nothing.

import { useChannel, useWhisper } from '@/hooks/use-realtime'

const channel = 'presence-rooms.' + room
const say = useWhisper(channel)
const [typing, setTyping] = useState<Record<string, number>>({})

useChannel(channel, {
  'client-event:typing': (p) =>
    setTyping((t) => ({ ...t, [p.user_id]: Date.now() })),
})

// Once when they start, then at most every 2s while they keep going.
const onChange = useThrottled(() => say('typing', { typing: true }), 2000)

// Nobody sends "stopped": drop anyone whose last ping is over 3s old.
const active = Object.entries(typing).filter(([, at]) => Date.now() - at < 3000)

Note what is missing: there is no stop_typing event. A browser that is closed mid-word never sends one, which is how typing indicators get stuck. Expiring on the receiver is both simpler and correct.

Throttle the send. Ten a second per connection is the server's limit, and past it your whispers are dropped and the socket gets one client_event_error with codeRATE_LIMITED per second. A refusal for any other reason arrives the same way, with PUBLIC_CHANNEL, NOT_SUBSCRIBED,INVALID_EVENT or PAYLOAD_TOO_LARGE.

Two replicas, and what to watch

One hub is an in-process registry, so a user on replica A would never hear a message published on replica B. The scaffolded routes.Setup already joins them through Redis wherever the project has it, which is the same Redis the cache and the job queue use, so this costs no new infrastructure.

var realtimeOptions []realtime.Option
if cfg.Modules.Realtime {
    realtimeOptions = append(realtimeOptions, realtime.WithRedis(cfg.RedisURL, ""))
}
realtimeHub := realtime.NewHub(realtimeOptions...)

Channel publishes, presence and client events all cross the backplane. Local clients are served first and unconditionally, so a Redis outage degrades chat to one replica instead of breaking it. Delivery between replicas is best effort on purpose: the database is the record, and a client that misses an event resyncs on its next REST call.

GET /api/health carries a realtime object, and the admin's System Health page shows it as a card. Three numbers are worth watching in a chat app:

• • messages_dropped climbing means clients cannot drain their 32 message buffer, so somebody is looking at a stale room
• • backplane_publish_errors above zero means chat works for the people on one replica and not the others
• • client_events_rate_limited rising usually means a typing indicator that fires on every keystroke

Summary

You have built a chat app on the hub your project already had:

• WebSocket protocol: a persistent, two-way connection instead of polling
• The scaffolded hub: one socket per app, authenticated with the same JWT as the REST API
• Channels: rooms, with an authorizer that runs on every subscribe
• REST in, channel out: the database is the record, the socket is the hint
• Presence: a member list that survives a tab, a browser and a replica dying
• Client events: typing indicators that never touch the database
• Replicas and health: the Redis backplane, and the numbers that say it is working