Rooms

A room is a name pages and apps join to get its events. Your server declares your rooms once, by pattern, with what each keeps and allows, and answers for each user who asks to join. It sends to them, and pages send to them too, as a room allows.

Names and patterns

• Room names: up to 200 characters of A-Z a-z 0-9 _ - = @ , . ; :. A room lives within your app: order:42 of another app is another room.
• A pattern names the parts of the name of a room: order:{id} matches order:42, and the rule gets { id: '42' }. {name} matches one or more characters other than : and ., as few as the rest of the pattern allows.
• The most specific rule wins: the pattern with the most fixed characters, and on a tie the one declared first. A room no pattern matches is refused (no_rule).
• : or .: order:42 and order.42, as the Laravel broadcasting writes it, both work.

Declaring rooms

Node

realtime.room( 'order:{id}', { history: 20 }, async ( user, { id } ) => {
    const order = await findOrder( id );
    return order !== null && order.userId === user;
} );

realtime.room( 'chat:{a}:{b}', { presence: true, history: 50, emit: [ 'message', 'typing', 'read' ], webhook: [ 'message' ] },
    ( user, { a, b } ) => [ a, b ].includes( String( user ) ) );

realtime.room( 'product:{id}', { public: true, count: true } );   // anyone, signed in or not, and a live count

PHP

$realtime->room( 'order:{id}', function ( $user, array $p ) {
    $order = find_order( $p['id'] );
    return null !== $order && $order->user_id === $user;
}, [ 'history' => 20 ] );

$realtime->room( 'product:{id}', null, [ 'public' => true, 'count' => true ] );

// Laravel: routes/channels.php, with the options of the room as a third argument. PrivateChannel( 'orders.42' ) is orders.42.
Broadcast::channel( 'orders.{id}', fn ( User $user, string $id ) => $user->id === Order::find( $id )?->user_id, [ 'history' => 20 ] );

Python

def may_follow_order(user, p):
    order = find_order(p["id"])
    return order is not None and order.user_id == user

realtime.room("order:{id}", may_follow_order, history=20)
realtime.room("product:{id}", public=True, count=True)

• user is the asking user id, a number or a string, or null (None) for nobody.
• The answer: false (or null) for no, true for yes, or { info } for yes with what the others see of them in a presence room.
• For one user, the answer may narrow the room: { emit: [ 'typing' ] } lets them send only that, { readOnly: true } nothing.
• In Node the rule may be async. In PHP and Python it is a plain function, which may query your database the usual way.
• When it runs: the browser asks for every room it joins in the same moment in one request, and keeps each token until 10 minutes before it expires, across reconnects and moves: your rule runs when a page first joins and when its token is renewed (6 hours by default).

What a room keeps and allows

Option	Default
presence	off	Its members are listed with their info. join and leave tell the others (presence)
count	off	A live count of who is in it, at any size, without a list. Presence counts too
history	none	Events kept for pages that reconnect: a number, up to 1,000, for 30 minutes. Or { last, days } for less (0.01 of a day is about 15 minutes)
emit	none	Events pages may send to the room: names, or '*' for any (events from the page)
webhook	none	Which of the page events your server gets too (webhooks)
public	off	Anyone may join, signed in or not. Its grant names no user, so it may sit in a page a CDN caches. Not sealed
seal	on	Its events, its member info and its history are sealed with the room key (encryption)

The options travel in the room token, signed by your server with the room name, so WordPlus Cloud enforces them and nothing is set in two places.

Joining

const order = rt.join( 'order:42' );
order.on( 'updated', ( data, meta ) => refresh( data ) );   // meta: { from, id, at, replayed? }
order.on( 'joined', () => console.log( 'in' ) );
order.on( 'error', ( e ) => console.warn( e.code ) );      // forbidden, no_rule, full, expired …

order.state;   // joining, joined, failed, left
rt.leave( 'order:42' );

• join() gives the same room for the same name. The tabs of a user ride one connection, each with its own rooms.
• Events reach a listener opened: you never handle sealed values.
• meta.from is the user who sent it from a page, as your server vouched for them, or nothing for your server. meta.id and meta.at are the kept event id and time.
• The events of the room itself are joined, join, leave, count and error, and connect and disconnect on rt. Nobody can send them.

History, and nothing lost on a reconnect

A room keeps its events for 30 minutes at most, for recovery. Your app keeps its own records, such as the messages of a chat, from the webhook.

• Kept per room, as its rule says: every kept event has an id, rising within the room, and the time it was sent. Events over 64 KB are sent but not kept. volatile ones are never kept.
• A reconnect gets what it missed: a connection back within the history span gets the missed events first, in order, with meta.replayed, then the new ones, also when the connection comes back on another of the WordPlus Cloud servers.
• Paging back: at most 100 a page.

const { events, more } = await order.history( { limit: 50 } );                 // the newest 50, oldest first
const older = await order.history( { before: events[ 0 ].id, limit: 50 } );

• Your server reads and erases it the same way: realtime.in( room ).history() and .forget( id ) (sending).
• Sealed: events are kept as they were sent, sealed, so WordPlus Cloud keeps what it cannot read. A member reads them with the room keys your keys route gives them. After a kick, newer events are under a key the kicked user never gets.

Several servers, several packages

Node, PHP and Python declare rooms the same way and sign the same tokens, from the same keys: a page served by one and a route answered by another work together. The server reference, the PHP reference and the Python reference have every option.