Run a chat room

By the end of this recipe two browsers share one room, a message typed in either shows up in both, and the invite that got them there sits in the page address, with every message sealed before it leaves the tab.

• Uses available, create and join from @fkn/lib/rooms, and on, send, grant, setDefault, leave and closed on the Room they resolve
• Needs nothing installed
• Proven by the two-browser journey in the fkn.app release gate, which runs this recipe on every promotion

A room is a realtime channel the platform relays between browsers. The invite is its uuid and its key joined by a dot, and the key never reaches the platform: your browser seals every message under it, and the broker, the connection your app holds into FKN through a hidden fkn.app frame, does the sealing and the reconnecting. The app is the media library from the other pages, growing a chat beside its catalog.

Every step is [Page], defined on recipes, because a room is window work: the broker frame holds the connection, so the page that mounts it is where the calls belong.

[Page] Check the realm

available answers rather than rejecting. It is false in Node and in a worker nobody relayed, and true in a page with a broker, so the first thing the page does is ask.

app.ts

import * as rooms from '@fkn/lib/rooms'

const log = document.querySelector<HTMLUListElement>('#log')!
const line = (text: string) => { const li = document.createElement('li'); li.textContent = text; log.append(li) }

if (!(await rooms.available())) line('rooms need a browser tab') // false in Node, and in a worker nobody relayed

The fallback line tells the person why nothing else will happen, and it costs one round trip to the broker. Everything after this step assumes the answer was true.

[Page] Open or join a room

The page address decides. A fragment holds an invite, so the tab joins, and no fragment means this tab is the first, so it creates. Either way open resolves the same Room.

app.ts

const open = (): Promise<rooms.Room> => {
  const invite = location.hash.slice(1)
  return invite ? rooms.join(invite) : rooms.create()
}

const room = await open().catch((error: unknown) => {
  const code = (error as rooms.RoomsError).code
  line(code === 'not-found' ? 'that room has ended' : code === 'bad-key' ? 'that link is wrong' : code === 'blocked' ? 'you cannot rejoin that room' : 'could not open the room')
  throw error
})

location.hash = room.invite // the invite is the whole page address to share
line('share this page address to invite people')

The catch branches on code, never on the message: not-found for a room that has ended, bad-key for an invite whose key is not that room’s, blocked for a member the owner turned away, and everything else as a plain failure. A code survives a library update and a reworded message, and a message match does not. On success the invite becomes the page address, so sharing the address is inviting.

[Page] Show every event

One listener receives every event the room produces, and one function renders them. Members have no names, so the page invents labels as ids appear: you for this tab, then guest 1, guest 2 and so on in order of arrival.

app.ts

const names = new Map<string, string>([[room.self.id, 'you']])
const nameFor = (id: string) => names.get(id) ?? (names.set(id, `guest ${names.size}`), names.get(id)!)

const render = (event: rooms.RoomEvent) => {
  if (event.type === 'message') line(`${nameFor(event.message.from)}: ${event.message.text}`) // the text, in this browser
  if (event.type === 'joined') line(`${nameFor(event.member.id)} joined`)
  if (event.type === 'left') line(`${nameFor(event.id)} ${event.reason}`) // left, removed or blocked
}

const off = await room.on(render) // hold the unsubscribe and await it in your cleanup

Hold the unsubscribe and await it in your cleanup. The ids are display values with no meaning outside this room, so the label map is the right place to keep whatever the person should see, and a message’s from is only ever looked up there.

[Page] Send what the form holds

The form hands its text to send, which resolves once the platform has taken the sealed message. It rejects rather than truncating: text over 4,096 bytes comes back as too-large with nothing sent.

app.ts

const form = document.querySelector<HTMLFormElement>('#say')!
const field = document.querySelector<HTMLInputElement>('#text')!

form.addEventListener('submit', async submit => {
  submit.preventDefault()
  const text = field.value.trim()
  field.value = ''
  if (!text) return
  await room.send(text).catch((error: unknown) =>
    line((error as rooms.RoomsError).code === 'rate-limited' ? 'slow down a moment' : 'not sent'))
})

A rate-limited refusal is a wait, not a failure. The member’s allowance refills at 10 messages a second, so the right response is a short pause and a retry, and the page says so instead of dropping the text. Ten refusals inside ten seconds close the connection, so a retry loop needs a delay in it.

[Page] End the room

closed settles once and never rejects, whatever ended the room. Await it after the listener is up, and the page has one place to say what happened.

app.ts

const end = await room.closed // settles once, and never rejects
await off()
line(end.reason === 'ended' ? 'the room ended' : `you left the room (${end.reason})`) // 'left', 'removed', 'blocked', 'ended' or 'unavailable'

Each reason means something different to the UI. left is your own leave, removed and blocked are the owner’s doing, and only after removed can a deliberate join on the same invite bring the person back, as a fresh member. ended is the room ending under you, and unavailable is a connection the broker could not restore within the hold. The unsubscribe is awaited before the message, so no event lands on a page that has already said goodbye.

Check it worked

Open the page in one browser and copy its address once the invite line appears. Open that address in a second browser, or a private window, and type in either: the line shows up in both, prefixed you on the sending side and guest 1 on the other, and the platform never saw the text. Close one tab and the other reports the departure once the hold runs out, about 20 seconds later.

1. The second browser reports that room has ended or that link is wrong: the first tab left, so the room was deleted with it, or the address was copied without its fragment. Copy the whole address while the first tab is still open (rooms: no such room, rooms: wrong room key)
2. A rejoin reports you cannot rejoin that room: the owner blocked that member, and the block holds for the room’s life (rooms: you are blocked from this room)
3. send rejects with denied: the room’s send default is off and this member was not granted, so check room.self.permissions.send before showing the composer (rooms: you cannot send here, permissions)
4. The page says slow down a moment: the per-member rate was passed, so wait and retry rather than resending in a loop (rooms: sending too fast, per member)
5. The page says not sent for a long message: the text is over the cap, whole and untrimmed, so shorten it (rooms: the message is too large, 4,096 bytes)
6. closed settles unavailable: the connection dropped and the broker could not restore it inside the hold, so call join again with the invite (rooms: rooms are unavailable, the hold)

Optional: Open a broadcast room

A broadcast room is one where only the owner speaks, and anyone the owner grants. Pass defaults: { send: false } at create, and every joiner starts silent.

app.ts

const room = await rooms.create({ defaults: { send: false } }) // the owner speaks, and nobody else until they are granted
await room.grant(id, 'send') // one member, while the default still holds for the rest
room.defaults() // { send: false, receive: true }

A grant is an override, so it survives a later change of the default, and revoking it puts that member back under the default. room.defaults() answers synchronously, so a composer can read it before it renders.

See also

• rooms
• account and quota
• connection and lifecycle
• every error
• limits and timeouts