` ([React](react.md)).
## Why a call ended
| `call.endReason` | |
|---|---|
| `hangup` | a side hung up |
| `cancelled` | the caller hung up before an answer |
| `rejected`, `busy` | the callee declined, or said they were busy |
| `no_answer` | nobody answered within 45 seconds |
| `page_closed` | a side closed its page |
| `peer_lost` | a side's connection didn't come back within 45 seconds |
| `room_lost` | the room it moved to gave up |
| `not_included`, `forbidden`, `bad_token`, `expired` | the server refused to start it ([errors](errors.md#calls)) |
| `no_call`, `call_ended` | answered after the caller had given up |
| `signaling_unavailable` | the page's connection was down when it started |
## What WordPlus Cloud sees
- **Your server decides** every call: WordPlus Cloud takes only tokens it signed, for the people and the call it named.
- **The two browsers' negotiation is sealed** with a key your server derives from its local key, which WordPlus Cloud never sees.
- **The media** is encrypted end to end by WebRTC on a direct or relayed path. In a room, the media server forwards it.
---
Source: https://docs.wordplus.cloud/apps/encryption/
# Encryption and your users
What your app sends through WordPlus Cloud is sealed on the way: the realtime servers carry it without being able to read or change it. You write no encryption code. Your server holds the keys, gives each user the ones they may have, and the browser opens everything before your listener sees it.
## What is sealed
| What | Sealed with | Who can open it |
|---|---|---|
| Events your server publishes to a private or presence channel | the channel's key | whoever the channel's owner lets in |
| Client events between browsers on those channels | the channel's key | the same |
| A presence member's `info` | the channel's key | the same |
| What a call's and a room's people see of each other | the day's key | everyone your app knows |
| Your users in the directory (name, avatar …) | the day's key | everyone your app knows |
Public channels are not sealed: anyone with your app's key may listen. The realtime servers see user ids, which key a value needs, and sealed values; they never hold a key.
## Your local key
`WORDPLUS_LOCAL_KEY`, 64 hex characters you make (`openssl rand -hex 32`), is the master every key is derived from: `HMAC-SHA256(local key, "wordplus-realtime key v1|" + label)`. Keep it:
- **the same on every server** of the app, and in every language: the Node, PHP and Python packages derive the same keys from it;
- **as long as the app:** a new one means pages holding old keys can't open what comes, until they reload;
- **out of every page and app,** as the secret.
It also makes each call's signal key, so WordPlus Cloud can't read a call's negotiation.
## Who gets which key
| Key | Label | Given to |
|---|---|---|
| The day's | `d:{day}` | every user your server knows, yesterday's to tomorrow's |
| A user's own | `u:{id}:{generation}` | that user |
| A channel's | `ch:{channel}:{generation}` | whoever the channel's owner lets in, with the channel's token |
| Your own kind | `{kind}:{…}` | whoever your `kind()` callback says |
The browser takes keys from your server only (the page's settings, a channel's grant, or your keys route), never from the realtime servers. `hasKeys: ( user ) => false` cuts a user off.
## When someone loses access
**Node**
```ts
await realtime.rotateChannel( 'private-orders-42' ); // what the channel carries from now on is sealed from them
await realtime.rotateUser( userId ); // their own key moves on
```
**PHP**
```php
$realtime->rotateChannel( 'private-orders-42' ); // what the channel carries from now on is sealed from them
$realtime->rotateUser( $userId ); // their own key moves on
```
**Python**
```python
realtime.rotate_channel("private-orders-42") # what the channel carries from now on is sealed from them
realtime.rotate_user(user_id) # their own key moves on
```
Rotating needs somewhere to keep the keys' generations, shared by your servers, and kept for good:
**Node**
```ts
createRealtime( { …, generations: {
get: async ( name ) => Number( await redis.get( 'rt-gen:' + name ) ) || null,
set: async ( name, n ) => void ( await redis.set( 'rt-gen:' + name, n ) ),
} } );
```
**PHP**
```php
// Laravel: WORDPLUS_REALTIME_GENERATIONS=redis (or database), a cache store that doesn't evict.
final class RedisGenerations implements WordPlus\Realtime\GenerationStore
{
public function __construct( private Redis $redis ) {}
public function get( string $name ): ?int { $n = $this->redis->get( 'rt-gen:' . $name ); return false === $n ? null : (int) $n; }
public function set( string $name, int $generation ): void { $this->redis->set( 'rt-gen:' . $name, $generation ); }
}
$realtime = Realtime::fromEnvironment( [ 'generations' => new RedisGenerations( $redis ), … ] );
```
**Python**
```python
class RedisGenerations:
def get(self, name):
n = redis.get("rt-gen:" + name)
return int(n) if n is not None else None
def set(self, name, generation):
redis.set("rt-gen:" + name, generation)
realtime = Realtime.from_environment(generations=RedisGenerations(), …)
```
Those still let in get the new key from your server when its first event comes.
## Your own sealed values
**Node**
```ts
realtime.kind( 'note', async ( rest, user ) => user !== null && ( await mayRead( user, rest ) ) );
const sealed = await realtime.keys.seal( JSON.stringify( note ), 'note:' + note.id ); // send it any way you like
```
**PHP**
```php
$realtime->kind( 'note', fn ( $rest, $user ) => null !== $user && may_read( $user, $rest ) );
$sealed = $realtime->keys()->sealJson( $note, 'note:' . $note['id'] ); // send it any way you like
```
**Python**
```python
realtime.kind("note", lambda rest, user, label: user is not None and may_read(user, rest))
sealed = realtime.keys.seal_json(note, "note:" + str(note["id"])) # send it any way you like
```
In the browser:
```ts
import { keyring, labelOf } from '@wordplus/realtime';
await keyring().ensure( [ labelOf( sealed ) ] ); // asks your keys route for `note:…` if the page lacks it
const note = keyring().openJson( sealed ); // undefined when this user may not have it
```
## Your users
A directory of your users on WordPlus Cloud, each one's profile sealed with the day's key, shared by every page of your app:
```ts
const users = await rt.users( [ 7, 12 ] ); // { 7: { user_id: 7, name: 'Ann', avatar: '…' }, 12: { … } }
```
A page sends its user's identity, signed by your server with their profile, when it connects; it may then read others'. In this version the directory takes integer user ids, as calls do.
---
Source: https://docs.wordplus.cloud/apps/react/
# React, React Native and Capacitor
## React
```tsx
import { RealtimeProvider, useChannel, usePresence, useCalls, CallScreen, CallButton, RoomButton } from '@wordplus/realtime/react';
export default function App() {
return (
);
}
function Order( { id } ) {
const [ status, setStatus ] = useState( 'open' );
const channel = useChannel( `private-orders-${ id }`, { updated: ( data ) => setStatus( data.status ) } );
const agents = usePresence( 'presence-agents' );
return (
<>
{ status } { channel.state === 'failed' && channel.error }
{ agents.map( ( a ) => Call { a.info?.name } ) }
);
}
```
| | |
|---|---|
| `` | connects once for everything inside, and closes when it goes; `options` are `connect()`'s or your server's `config()` |
| `useRealtime()` | the connection (`Realtime`), or `null` until it's up |
| `useChannel( name, handlers )` | listens while the component is on the page; gives `{ state, error, trigger( event, data ) }`; `null` listens to nothing |
| `usePresence( name )` | the members, `[ { id, info } ]`, kept up to date |
| `useCalls()` | `{ calls, incoming }`: the page's calls once loaded, and those ringing |
| `` | starts the call screen ([calls](calls.md#the-call-screen)) |
| ``, `` | its buttons |
Several components may listen to one channel: it is left when the last of them goes.
**Next.js:** the React entry is a client module (`'use client'`). Render the user's settings on the server to skip a request: `const config = await realtime.config( userId )` in a server component, then ``.
## React Native
```ts
import 'react-native-get-random-values'; // first: sealing needs crypto.getRandomValues
import { connect } from '@wordplus/realtime/native';
const rt = await connect( {
site: 's1500000007',
endpoint: 'https://app.example.com/api/realtime', // in full
headers: { Authorization: 'Bearer ' + session.token }, // how your server knows the user
} );
```
- Channels, presence, client events, publishing and the directory, sealed as in a browser.
- No worker and no address: a native app connects by itself and sends no Origin, which WordPlus Cloud lets in.
- Your server's `user( request )` reads the user from the `Authorization` header, or whatever your app sends.
- **Calls in React Native come later** (they need a WebRTC module).
## Capacitor and Ionic
An app in Capacitor or Ionic is a page: use `@wordplus/realtime` as in a browser, and add its address to your app in WordPlus Cloud: `capacitor://localhost` on iOS, `https://localhost` (or `http://localhost`) on Android, `ionic://localhost` for Ionic's. Calls work there as in the browser. Your routes need their full address (`endpoint: 'https://app.example.com/api/realtime'`), and your server must answer the app's address with CORS.
---
Source: https://docs.wordplus.cloud/apps/laravel/
# Laravel
Laravel finds the package by itself, through package discovery. It brings:
- **A `wordplus` broadcasting driver.** `broadcast( new OrderPaid( $order ) )` publishes to the event's channels, sealed, and `routes/channels.php` decides who may listen, written as for any broadcaster.
- **The browser's routes:** `POST /wordplus/realtime/auth`, `/calls` and `/keys`, on the `web` middleware, for the session's user.
- **`@wordplusRealtime`:** the page's settings, with the signed-in user's keys and the CSRF token.
- **The `Realtime` facade:** calls, channels of your own, keys and publishing.
The browser listens with `@wordplus/realtime`, not Laravel Echo.
## Setting up
```bash
composer require wordplus/realtime-php
npm install @wordplus/realtime
npx wordplus-realtime copy public/ # realtime-worker.js and realtime-rooms.min.js
```
```dotenv
WORDPLUS_SITE=s1500000007
WORDPLUS_SECRET=…
WORDPLUS_LOCAL_KEY=… # openssl rand -hex 32
BROADCAST_CONNECTION=wordplus
```
```php
// config/broadcasting.php
'connections' => [
'wordplus' => [ 'driver' => 'wordplus' ],
// …
],
```
Laravel 11 and later leave out `config/broadcasting.php` and `routes/channels.php` until `php artisan install:broadcasting` adds them. You need neither Reverb nor Laravel Echo, so skip installing them.
## Channels: `routes/channels.php`
```php
Broadcast::channel( 'orders.{id}', fn ( User $user, string $id ) => $user->id === Order::find( $id )?->user_id );
// Presence: what the others see of the user, or false.
Broadcast::channel( 'room.{id}', fn ( User $user, string $id ) => $user->canEnter( $id ) ? [ 'name' => $user->name ] : false );
```
In the browser, a channel's name carries its kind, as it does in Pusher's:
| In Laravel | In the browser |
|---|---|
| `new PrivateChannel( 'orders.42' )` | `private-orders.42` |
| `new PresenceChannel( 'room.7' )` | `presence-room.7` |
| `new Channel( 'news' )` | `news`: public, for anyone with the app's key, never sealed |
Nobody signed in gets a private or presence channel, as with Laravel's own broadcasters. A presence callback that answers `true` shows the user's [profile](#profiles) name.
## Events
```php
class OrderPaid implements ShouldBroadcast
{
use Dispatchable, InteractsWithSockets, SerializesModels;
public function __construct( public Order $order ) {}
public function broadcastOn(): array
{
return [ new PrivateChannel( 'orders.' . $this->order->id ) ];
}
public function broadcastAs(): string
{
return 'order.paid';
}
public function broadcastWith(): array
{
return [ 'status' => $this->order->status ];
}
}
```
```php
broadcast( new OrderPaid( $order ) );
```
- **The event's name** is `broadcastAs()`'s, or else its class (`App\Events\OrderPaid`).
- **Its data** is `broadcastWith()`'s, or else its public properties. It can be up to 10 KB of JSON, sealed with the channel's key.
- **Timing:** `ShouldBroadcast` goes through your queue, and `ShouldBroadcastNow` goes at once.
- **Failures:** a refusal from WordPlus Cloud throws Laravel's `BroadcastException`, with the [code](errors.md#publishing) in its message.
**`->toOthers()`** skips the tab whose request caused the event, when the page sends its tab as `X-Socket-ID` with its requests:
```js
axios.defaults.headers.common[ 'X-Socket-ID' ] = rt.tab; // or on your own fetch() calls
```
## The page
```blade
@wordplusRealtime
@vite( 'resources/js/app.js' )
```
```js
// resources/js/app.js
import { connect } from '@wordplus/realtime';
const rt = await connect( window.wordplusRealtimeConfig );
rt.subscribe( 'private-orders.42' ).on( 'order.paid', ( data ) => refresh( data ) );
const room = rt.subscribe( 'presence-room.7' );
room.on( 'realtime:subscribed', () => draw( room.members() ) ); // [ { id, info: { name } } ]
```
`@wordplusRealtime` writes `window.wordplusRealtimeConfig`: where to connect, the routes with the CSRF token, and the signed-in user's keys, so the page connects with no request first.
## Calls, and channels of your own
In a service provider's `boot()`:
```php
use WordPlus\Realtime\Laravel\Facades\Realtime;
// Calls with support: a customer with an agent, and the agents' own room.
Realtime::calls( 'support-', function ( $user, $call, $with ) {
$agent = fn ( $id ) => (bool) User::find( $id )?->is_agent;
return null === $with ? $agent( $user ) : $agent( $user ) || $agent( $with );
} );
// A channel beside routes/channels.php, by the start of its name.
Realtime::channel( 'private-staff-', fn ( $user ) => (bool) User::find( $user )?->is_staff );
```
- **`$user` and `$with` are ids** here, not models.
- **`$with` is the other person** of a call between two, or `null` for a room.
- **Which decides:** a channel that a `Realtime::channel()` prefix owns is decided there. `routes/channels.php` decides the rest.
- **More:** what a call's answer may hold, and the call screen, are in [calls](calls.md).
To publish without an event class:
```php
Realtime::publish( 'private-orders.42', 'updated', [ 'status' => 'paid' ] );
```
## Profiles
What others see of a user, in presence, calls and the directory, is their `name`. It includes their `avatar` too, or Jetstream's `profile_photo_url`, when they have one. To say otherwise, in a service provider's `boot()`:
```php
use WordPlus\Realtime\Laravel\RealtimeServiceProvider;
RealtimeServiceProvider::profileUsing( function ( $id ) {
$user = User::find( $id );
return $user ? [ 'name' => $user->display_name, 'avatar' => $user->avatar_url ] : null;
} );
```
A profile is sealed with the day's key. Pages read others' with `rt.users( [ … ] )` ([your users](encryption.md#your-users)).
## Rotating keys
When someone loses access to a channel, or to everything, move the key on, so what comes next is sealed from them:
```php
Realtime::rotateChannel( 'private-orders.42' );
Realtime::rotateUser( $user->id );
```
The keys' generations live in one of your cache stores, one that doesn't evict:
```dotenv
WORDPLUS_REALTIME_GENERATIONS=redis # or database
```
## The config
`php artisan vendor:publish --tag=wordplus-realtime` copies it to `config/wordplus-realtime.php`.
| Key | Default | |
|---|---|---|
| `site`, `secret`, `local_key` | `WORDPLUS_SITE`, `WORDPLUS_SECRET`, `WORDPLUS_LOCAL_KEY` | |
| `routes.prefix` | `wordplus/realtime` | where the browser's routes are |
| `routes.middleware` | `['web']` | how the routes know the user |
| `routes.enabled` | `true` | `false` to register `RealtimeController` yourself |
| `worker`, `rooms` | `/realtime-worker.js`, `/realtime-rooms.min.js` | where your app serves the two files |
| `generations` | `WORDPLUS_REALTIME_GENERATIONS` | the cache store for rotating keys |
| `seal` | `true` | `false` sends everything plain |
| `broadcasting` | `wordplus` | the connection whose `routes/channels.php` decides |
| `server`, `api` | WordPlus Cloud | `WORDPLUS_REALTIME_SERVER`, `WORDPLUS_REALTIME_API` |
The facade is the `WordPlus\Realtime\Realtime` singleton. Everything in the [PHP reference](php-reference.md) is on it.
---
Source: https://docs.wordplus.cloud/apps/django/
# Django
`wordplus_realtime.django` gives Django the browser's routes for the session's user, the page's settings with the CSRF token, and a user's profile from Django's user model.
```bash
pip install 'wordplus-realtime[django]'
npm install @wordplus/realtime
```
## Your server
```python
# shop/realtime.py
from wordplus_realtime import Realtime
import wordplus_realtime.django as wr
realtime = Realtime.from_environment(
profile=wr.user_profile, # the user's full name, or their username
worker="/static/realtime-worker.js",
rooms="/static/realtime-rooms.min.js",
)
realtime.channel(
"private-orders-",
lambda user, channel: Order.objects.filter(pk=channel[15:], user_id=user).exists(),
)
```
```python
# urls.py: POST /api/realtime/auth, /calls and /keys
from shop.realtime import realtime
urlpatterns = [
path("api/realtime/", include(wr.urls(realtime))),
]
```
The routes take the session's user (`request.user`), and Django's CSRF check stays on. For another way to know the user, pass it in: `wr.urls(realtime, user=lambda request: …)`.
`npx wordplus-realtime copy static/` puts the two files in a folder of your `STATICFILES_DIRS`, and `collectstatic` takes them from there.
## The page
```python
def order(request, pk):
return render(request, "order.html", {"realtime": wr.config_for(realtime, request), "order": …})
```
```html
{{ realtime|json_script:"realtime" }}
```
`config_for()` gives the page its settings for the request's user: the routes with the CSRF token as `X-CSRFToken`, and the user's keys, so the page connects with no request first.
## Publishing
```python
realtime.publish(f"private-orders-{order.pk}", "updated", {"status": order.status})
```
Publish after your own work is saved, `transaction.on_commit()` for one. A failed publish raises `RealtimeError`, and its result is a missed live update, not a lost change. In an async view, use `await realtime.apublish(…)`.
## Profiles
`wr.user_profile` shows a user's full name, or their username when they have none. For more, such as an avatar, write your own:
```python
def profile(user_id):
user = User.objects.filter(pk=user_id).select_related("profile").first()
return {"name": user.get_full_name(), "avatar": user.profile.avatar_url} if user else None
realtime = Realtime.from_environment(profile=profile)
```
## Rotating keys
`realtime.rotate_channel(name)` and `realtime.rotate_user(user_id)` need somewhere every server sees to keep the keys' generations. A cache that doesn't evict works, such as Redis or the database cache, but not the local memory one:
```python
from django.core.cache import caches
class CacheGenerations:
def get(self, name):
return caches["default"].get("wordplus-realtime:" + name)
def set(self, name, generation):
caches["default"].set("wordplus-realtime:" + name, generation, timeout=None)
realtime = Realtime.from_environment(profile=wr.user_profile, generations=CacheGenerations())
```
---
Source: https://docs.wordplus.cloud/apps/fastapi/
# FastAPI and Starlette
`wordplus_realtime.fastapi` gives FastAPI the browser's routes as a router, for the user your app finds.
```bash
pip install 'wordplus-realtime[fastapi]'
npm install @wordplus/realtime
```
## Your server
```python
from fastapi import FastAPI, Request
from fastapi.staticfiles import StaticFiles
from wordplus_realtime import Realtime
import wordplus_realtime.fastapi as wr
realtime = Realtime.from_environment(
profile=lambda user: {"name": name_of(user)},
worker="/static/realtime-worker.js",
rooms="/static/realtime-rooms.min.js",
)
realtime.channel("private-orders-", lambda user, channel: user is not None and owner_of(channel[15:]) == user)
async def current_user(request: Request):
session = await session_of(request)
return session.user_id if session else None
app = FastAPI()
app.include_router(wr.router(realtime, current_user), prefix="/api/realtime") # POST /auth, /calls, /keys
app.mount("/static", StaticFiles(directory="static"), name="static") # npx wordplus-realtime copy static/
```
- **`current_user(request)`** gives the request's user's id, or `None`. It may be `async`.
- **The owners** (`channel()`, `calls()`, `kind()`, `profile`) are plain functions. The router runs them on a worker thread, so a blocking database query in one doesn't hold up the event loop.
- **The routes take JSON POSTs only.** A page on another site can't send JSON without asking first, and it is never allowed to. A session cookie therefore needs no CSRF token here.
## The page
Render the settings into the page:
```python
@app.get("/orders/{pk}")
async def order_page(request: Request, pk: int):
config = realtime.config(await current_user(request))
return templates.TemplateResponse(request, "order.html", {"realtime": config, "pk": pk})
```
```html
```
```js
import { connect } from '@wordplus/realtime';
const rt = await connect( window.wordplusRealtimeConfig );
rt.subscribe( `private-orders-${ pk }` ).on( 'updated', ( data ) => refresh( data ) );
```
A single-page app can skip that, and connect with `connect( { site: 's1500000007', worker: '/static/realtime-worker.js' } )`, which asks `/api/realtime/keys` first. An app on another address, such as one in Capacitor, uses `endpoint: 'https://api.example.com/api/realtime'`, and your server answers the app's address with CORS.
## Publishing
```python
@app.post("/orders/{pk}/pay")
async def pay(pk: int):
order = await mark_paid(pk)
await realtime.apublish(f"private-orders-{pk}", "updated", {"status": order.status})
return order
```
`apublish()` runs the request on a worker thread. It raises `RealtimeError` when WordPlus Cloud refuses, with its `code` and `status`.
---
Source: https://docs.wordplus.cloud/apps/server/
# Server reference: `@wordplus/realtime/server`
Node 20 or later, and every edge runtime: it runs on Web Crypto and `fetch`. For PHP and Laravel, see the [PHP reference](php-reference.md); for Python, the [Python reference](python-reference.md). All three take the same options and answer the browser the same way.
## `createRealtime( options )` → `Realtime`
| Option | |
|---|---|
| `site`, `secret` | your app's key and secret (`WORDPLUS_SITE`, `WORDPLUS_SECRET`) |
| `localKey` | 64 hex characters of your own (`WORDPLUS_LOCAL_KEY`) ([encryption](encryption.md#your-local-key)) |
| `user( request )` | the request's user's id, or `null`: what `route` asks |
| `profile( user )` | `{ name, avatar?, url?, … }` or `null`: their directory entry, their presence info and call info by default |
| `hasKeys( user )` | `false` cuts a user off every key |
| `generations` | `{ get( name ), set( name, n ) }`, for `rotateChannel()` and `rotateUser()` |
| `seal` | `false` sends everything plain |
| `base` | where your routes are, `/api/realtime` by default, for `config()` |
| `headers` | headers the browser sends to your routes, such as a CSRF token, for `config()` |
| `worker`, `rooms` | where your app serves the two files, for `config()` |
| `tokenTtl`, `callTokenTtl` | seconds: 6 hours by default; a channels token at most a day, a calls token at most 6 hours |
| `server`, `api` | WordPlus Cloud by default |
| `fetch` | your own, for publishing |
## Owners
| Method | |
|---|---|
| `channel( prefix, ( user, channel ) => answer )` | private and presence channels by the start of their names; `false`, `true`, or `{ id, info }` ([channels](channels.md), [presence](presence.md)) |
| `calls( prefix, ( user, call, withUser ) => answer )` | calls and rooms; `false`, `true`, or `{ info, publish, subscribe, admin, hidden }` ([calls](calls.md)) |
| `kind( kind, ( rest, user, label ) => boolean, newest? )` | keys of your own kind ([encryption](encryption.md#your-own-sealed-values)) |
Callbacks may be async. The longest prefix that fits decides.
## Routes
| | |
|---|---|
| `route` | `( request: Request ) => Promise`: POST `…/auth`, `…/calls`, `…/keys`, the action from the path's last part; Next.js `export const POST = realtime.route` |
| `node( ( req ) => user )` | `( req, res )` for Node's own servers and Express; a body `express.json()` parsed is taken as it is |
| `handle( action, body, user )` | → `{ status, body }`: one route, for a framework of your own |
They take JSON POSTs only (`415` otherwise): a page on another site can't send one without asking first, which it is never allowed. A refusal is an answer (`denied`), not an HTTP error.
| Method | What it answers |
|---|---|
| `authorize( channels, user )` | `{ token, exp, keys, denied }` |
| `authorizeCall( request, user )` | `{ token, exp, key }` or `{ denied }` |
| `keysAnswer( labels, user )` | `{ keys, identity? }` |
| `identity( user )` | `{ token, exp }` or `null` |
| `token( channels, { user, info, ttl } )` | a channels token, signed as the auth route signs |
| `config( user )` | the browser's settings, with a signed-in user's keys and identity |
## Publishing
| Method | |
|---|---|
| `publish( channels, event, data, { except, seal } )` | ([publishing](publishing.md)) |
| `publishBatch( [ { channels, event, data, except, seal } ] )` | 10 events a request |
| `channelInfo( channel )` | `{ subscriptions, members? }` |
| `rotateChannel( channel )`, `rotateUser( user )` | moves a key on |
| `keys` | the `Keys`: `seal( text, label )`, `sealJson`, `open`, `entry( label )`, `dayLabel()`, `channelLabel( channel )` |
All throw `RealtimeError` (`code`, `status`) for the server's refusal ([errors](errors.md#publishing)).
---
Source: https://docs.wordplus.cloud/apps/php-reference/
# PHP reference: `wordplus/realtime-php`
The package needs PHP 8.1 or later, with sodium, and curl or PHP's streams. It takes the same options as the Node and Python packages, and answers the browser the same way. In Laravel, the `Realtime` facade and `app( Realtime::class )` are one instance, made from `config/wordplus-realtime.php` ([Laravel](laravel.md)).
## `new Realtime( $options )`
`Realtime::fromEnvironment( $options )` is the same, with `site`, `secret` and `local_key` taken from `WORDPLUS_SITE`, `WORDPLUS_SECRET` and `WORDPLUS_LOCAL_KEY`.
| Option | |
|---|---|
| `site`, `secret` | your app's key and secret |
| `local_key` | 64 hex characters of your own ([encryption](encryption.md#your-local-key)) |
| `profile` | `fn ( $user ) => [ 'name' => …, 'avatar' => …, 'url' => … ]` or `null`: the user's directory entry, and by default their presence info and call info |
| `has_keys` | `fn ( $user ) => false` cuts a user off every key |
| `generations` | a `GenerationStore`, for `rotateChannel()` and `rotateUser()` |
| `seal` | `false` sends everything plain |
| `base` | where your routes are, `/api/realtime` by default, for `config()` |
| `headers` | headers the browser sends to your routes, such as a CSRF token, for `config()` |
| `worker`, `rooms` | where your app serves the two files, for `config()` |
| `token_ttl`, `call_token_ttl` | seconds: 6 hours by default; a channels token lasts at most a day, a calls token at most 6 hours |
| `server`, `api` | WordPlus Cloud by default |
| `http` | `fn ( $method, $url, $headers, $body ) => [ 'status' => …, 'body' => … ]`, your own client for publishing |
A user is the id your app gives, an integer or a string, or `null` for nobody. In this version, calls and the directory take integer ids only.
## Owners
| Method | |
|---|---|
| `channel( $prefix, fn ( $user, $channel ) => $answer )` | private and presence channels, by the start of their names; answers `false`, `true`, or `[ 'id' => …, 'info' => … ]` ([channels](channels.md), [presence](presence.md)) |
| `calls( $prefix, fn ( $user, $call, $with ) => $answer )` | calls and rooms; answers `false`, `true`, or `[ 'info', 'publish', 'subscribe', 'admin', 'hidden' ]` ([calls](calls.md)) |
| `kind( $kind, fn ( $rest, $user, $label ) => bool, $newest = null )` | keys of your own kind ([encryption](encryption.md#your-own-sealed-values)) |
| `fallback( fn ( $user, $channel ) => $answer )` | the channels no prefix owns; in Laravel, `routes/channels.php` |
The longest prefix that fits decides. Each method returns the instance, so calls chain.
## Routes
| Method | |
|---|---|
| `respond( $action, $user )` | answers the current request in plain PHP: `auth`, `calls` or `keys`, with its status, headers and JSON |
| `answerRequest( $method, $contentType, $action, $body, $user )` | → `[ 'status', 'body' ]`, for a framework of your own |
| `handle( $action, $body, $user )` | → `[ 'status', 'body' ]`, for a body already decoded |
The routes take JSON POSTs only, and answer anything else with `415`. A page on another site can't send JSON without asking first, and it is never allowed to. A refusal is part of the answer (`denied`), not an HTTP error.
| Method | What it answers |
|---|---|
| `authorize( $channels, $user )` | `[ 'token', 'exp', 'keys', 'denied' ]` |
| `authorizeCall( $request, $user )` | `[ 'token', 'exp', 'key' ]` or `[ 'denied' => … ]` |
| `keysAnswer( $labels, $user )` | `[ 'keys', 'identity'? ]` |
| `identity( $user )` | `[ 'token', 'exp' ]` or `null` |
| `token( $channels, $user = null, $info = null, $ttl = null )` | a channels token, signed as the auth route signs |
| `config( $user = null, $headers = [] )` | the browser's settings for `connect()`, with a signed-in user's keys and identity |
| `mayJoin( $channel, $user )`, `mayHave( $label, $user )` | what the routes decide, for your own checks |
## Publishing
| Method | |
|---|---|
| `publish( $channels, $event, $data = null, [ 'except' => $tab, 'seal' => false ] )` | one channel, or up to 100; data up to 10 KB of JSON ([publishing](publishing.md)) |
| `publishBatch( [ [ 'channels', 'event', 'data', 'except', 'seal' ], … ] )` | 10 events a request |
| `channelInfo( $channel )` | `[ 'subscriptions', 'members'? ]` |
| `rotateChannel( $channel )`, `rotateUser( $user )` | moves a key on; needs `generations` |
They throw `RealtimeError` when WordPlus Cloud refuses: `$e->errorCode` holds the [code](errors.md#publishing), and `$e->status` the HTTP status.
## Keys
`$realtime->keys()` is the app's `Keys`:
| Method | |
|---|---|
| `seal( $text, $label )`, `sealJson( $data, $label )` | a sealed value, `{label}:1.{…}` |
| `open( $value )` | the text, or `null` |
| `entry( $label )` | a key as the browser takes it |
| `dayLabel()`, `channelLabel( $channel )`, `userLabel( $user )` | the labels the SDK uses |
## Generations
```php
interface GenerationStore
{
public function get( string $name ): ?int;
public function set( string $name, int $generation ): void;
}
```
Keep them where all your servers see them, and for good: a database row, or a cache that doesn't evict. In Laravel, `WordPlus\Realtime\Laravel\CacheGenerations` keeps them in a cache store.
## Helpers
`Realtime::channelKind( $channel )` gives `public`, `private` or `presence`. `Realtime::validChannel( $channel )` says whether WordPlus Cloud takes the name.
---
Source: https://docs.wordplus.cloud/apps/python-reference/
# Python reference: `wordplus-realtime`
The package needs Python 3.9 or later, with PyNaCl. It takes the same options as the Node and PHP packages, and answers the browser the same way.
## `Realtime( site, secret, local_key, **options )`
`Realtime.from_environment( **options )` is the same, with `site`, `secret` and `local_key` taken from `WORDPLUS_SITE`, `WORDPLUS_SECRET` and `WORDPLUS_LOCAL_KEY`.
| Option | |
|---|---|
| `site`, `secret` | your app's key and secret |
| `local_key` | 64 hex characters of your own ([encryption](encryption.md#your-local-key)) |
| `profile` | `lambda user: {"name": …, "avatar": …, "url": …}` or `None`: the user's directory entry, and by default their presence info and call info |
| `has_keys` | `lambda user: False` cuts a user off every key |
| `generations` | a `GenerationStore`, for `rotate_channel()` and `rotate_user()` |
| `seal` | `False` sends everything plain |
| `base` | where your routes are, `/api/realtime` by default, for `config()` |
| `headers` | headers the browser sends to your routes, such as a CSRF token, for `config()` |
| `worker`, `rooms` | where your app serves the two files, for `config()` |
| `token_ttl`, `call_token_ttl` | seconds: 6 hours by default; a channels token lasts at most a day, a calls token at most 6 hours |
| `server`, `api` | WordPlus Cloud by default |
| `http` | `(method, url, headers, body) -> (status, body)`, your own client for publishing |
A user is the id your app gives, an integer or a string, or `None` for nobody. In this version, calls and the directory take integer ids only.
## Owners
| Method | |
|---|---|
| `channel(prefix, lambda user, channel: answer)` | private and presence channels, by the start of their names; answers `False`, `True`, or `{"id": …, "info": …}` ([channels](channels.md), [presence](presence.md)) |
| `calls(prefix, lambda user, call, with_user: answer)` | calls and rooms; answers `False`, `True`, or `{"info", "publish", "subscribe", "admin", "hidden"}` ([calls](calls.md)) |
| `kind(kind, lambda rest, user, label: bool, newest=None)` | keys of your own kind ([encryption](encryption.md#your-own-sealed-values)) |
The longest prefix that fits decides. The callbacks are plain functions, not `async`. Each method returns the instance, so calls chain.
## Routes
| Method | |
|---|---|
| `answer_request(method, content_type, action, body, user)` | → `(status, body)`: one route, `auth`, `calls` or `keys`, for a request's raw body |
| `handle(action, body, user)` | → `(status, body)`, for a body already decoded |
| `wordplus_realtime.django.urls(realtime, user=…)` | the routes in Django ([Django](django.md)) |
| `wordplus_realtime.fastapi.router(realtime, user)` | the routes in FastAPI and Starlette ([FastAPI](fastapi.md)) |
The routes take JSON POSTs only, and answer anything else with `415`. A refusal is part of the answer (`denied`), not an HTTP error.
| Method | What it answers |
|---|---|
| `authorize(channels, user)` | `{"token", "exp", "keys", "denied"}` |
| `authorize_call(request, user)` | `{"token", "exp", "key"}` or `{"denied": …}` |
| `keys_answer(labels, user)` | `{"keys", "identity"?}` |
| `identity(user)` | `{"token", "exp"}` or `None` |
| `token(channels, user=None, info=None, ttl=None)` | a channels token, signed as the auth route signs |
| `config(user=None, headers=None)` | the browser's settings for `connect()`, with a signed-in user's keys and identity |
| `may_join(channel, user)`, `may_have(label, user)` | what the routes decide, for your own checks |
## Publishing
| Method | |
|---|---|
| `publish(channels, event, data=None, *, except_tab=None, seal=True)` | one channel, or up to 100; data up to 10 KB of JSON ([publishing](publishing.md)) |
| `await apublish(…)` | the same from async code, on a worker thread |
| `publish_batch([{"channels", "event", "data", "except", "seal"}, …])` | 10 events a request |
| `channel_info(channel)` | `{"subscriptions", "members"?}` |
| `rotate_channel(channel)`, `rotate_user(user)` | moves a key on; needs `generations` |
They raise `RealtimeError` when WordPlus Cloud refuses: `e.code` holds the [code](errors.md#publishing), and `e.status` the HTTP status.
## Keys
`realtime.keys` is the app's `Keys`: `seal(text, label)`, `seal_json(data, label)`, `open(value)`, `entry(label)`, `day_label()`, `channel_label(channel)`, `user_label(user)`.
## Generations
```python
class GenerationStore(Protocol):
def get(self, name: str) -> Optional[int]: ...
def set(self, name: str, generation: int) -> None: ...
```
Keep them where all your servers see them, and for good: a database row, or a cache that doesn't evict.
## Helpers
`channel_kind(channel)` gives `public`, `private` or `presence`. `valid_channel(channel)` says whether WordPlus Cloud takes the name. `label_of(value)` names the key a sealed value needs. All three come from `wordplus_realtime`.
---
Source: https://docs.wordplus.cloud/apps/browser/
# Browser reference: `@wordplus/realtime`
## `connect( options )` → `Promise`
| Option | |
|---|---|
| `site` | your app's key |
| `endpoint` | your routes, `/api/realtime` by default; in full in an app |
| `headers` | sent with every request to your routes, such as a CSRF token |
| `worker` | your app's `realtime-worker.js`: every tab shares one connection |
| `rooms` | your app's `realtime-rooms.min.js`, for group calls |
| `keys` | `{ entries, identity }` from your server's `config()`: no request before connecting |
| `ring` | `false`: this page holds no line, so calls don't ring here |
| `server`, `path`, `api` | WordPlus Cloud by default |
Or your server's `config()` as it is: `connect( config )`. `connectNow()` connects without asking your keys route first.
## `Realtime`
| Member | |
|---|---|
| `subscribe( name )` | → `Subscription`, the same one for the same name |
| `channel( name )`, `unsubscribe( name )` | |
| `users( ids )` | → `Promise<{ [id]: profile }>`: your users from the directory, opened ([encryption](encryption.md#your-users)) |
| `calls()` | → `Promise`, loading the call engine the first time ([calls](calls.md)) |
| `callScreen( { strings } )` | → `Promise`: starts the call screen |
| `tab` | this tab's name, for a publish's `except` |
| `connected` | |
| `on( event, fn )`, `off( event, fn? )` | `connected`, `disconnected`, `moved`, `error` (`{ code }`: the connection refused) |
| `close()` | |
| `channels` | the underlying `Channels` |
## `Subscription`
| Member | |
|---|---|
| `name`, `kind` | the channel; `public`, `private` or `presence` |
| `state`, `error` | `pending`, `subscribed`, `failed`, `ended`; why it failed |
| `on( event, fn )`, `once`, `off` | a channel's event, `fn( data, { user_id } )`, opened; or `realtime:subscribed`, `realtime:error`, `realtime:member_added`, `realtime:member_removed`, `realtime:unopened` |
| `trigger( event, data )` | → `Promise`: a `client-…` event to the others |
| `members()`, `memberCount` | a presence channel's |
| `unsubscribe()` | |
## `Calls`
| Member | |
|---|---|
| `start( name, { to, type } )` | → `Promise` |
| `room( name, { type } )` | → `Promise` |
| `incoming()` | the calls ringing now |
| `stopRinging()` | the page holds the line no more |
| `on( 'incoming' \| 'error', fn )` | |
`Incoming`: `id`, `call`, `from`, `info`, `type`, `state`, `accept()`, `decline( 'declined' | 'busy' )`, `on( 'over', fn )`.
`Call`: `state` (`ringing`, `connecting`, `connected`, `reconnecting`, `ended`), `path` (`direct`, `relay`, `room`), `peer` (`{ user, info }`), `remote` (`{ camera, microphone, screen, screenAudio, quality }`), `endReason`, `setTrack( source, track )`, `end()`, and `on()` for `state`, `path`, `remote`, `waiting`, `ended`.
`Room`: `state`, `people()` (`{ user, info, camera, microphone, screen, screenAudio, speaking }`), `setTrack( source, track )`, `leave()`, `livekit`, and `on()` for `state`, `waiting`, `person`, `person_left`, `speakers`, `ended`.
A remote track has `attach( element )`, `detach( element? )` and `mediaStreamTrack`.
## Keys
`keyring()` is the page's: `open( value )`, `openJson( value )`, `seal( text, label )`, `ensure( labels )`, `has( label )`. `labelOf( value )` names the key a sealed value needs ([encryption](encryption.md)).
---
Source: https://docs.wordplus.cloud/apps/errors/
# Errors
Every refusal has a short code. In the browser, it is `e.code` of a rejected promise, `{ code }` of an `error` or `realtime:error` event, or a call's `endReason`. On your server, it is a `RealtimeError`'s `code` in Node and Python, and its `errorCode` in PHP. Laravel's broadcasting wraps it in a `BroadcastException`.
## The connection
`rt.on( 'error', ( e ) => … )`, or `connect()` rejecting:
| Code | Why | What to do |
|---|---|---|
| `not_licensed` | WordPlus Cloud doesn't know the app's key | the key is wrong, or the app was deleted |
| `not_included` | the app's grant doesn't include realtime | |
| `wrong_origin` | the page isn't on one of the app's addresses | add the address to the app (scheme, host and port exactly: `http://localhost:3000`, `capacitor://localhost`) |
| `over_capacity` | your apps hold all the connections your account may have at once | serve the worker, so a browser's tabs share one; ask for more |
| `try_later` | a server still starting | the page tries again by itself |
| `bad_request` | the handshake was malformed | |
## Channels
`realtime:error` on a subscription:
| Code | Why |
|---|---|
| `forbidden` | your server said no, or nothing owns the channel |
| `expired`, `bad_token` | the token ran out, or wasn't signed with your app's secret (a secret rotated more than a day ago, say) |
| `bad_channel` | not a channel name the server takes |
| `too_many` | the connection holds 1,000 channels |
| `full` | a presence channel has its 1,000 members |
| `auth_failed` | your auth route didn't answer, or answered an HTTP error |
| `no_auth` | the page has no auth route |
| `timeout`, `server` | the server didn't answer, or failed |
`trigger()` also rejects with `rate_limited`, `bad_event` (not `client-…`), `too_large` or `forbidden`. `realtime:unopened` (`{ event, label }`) is an event the page had no key for, even after asking your keys route.
## Publishing
`RealtimeError` from `publish()`, `publishBatch()` and `channelInfo()`:
| Code | Why |
|---|---|
| `missing_signature`, `stale_signature`, `unknown_site`, `bad_signature` | the signature wasn't taken: a server clock off by more than 5 minutes is `stale_signature`, a wrong secret `bad_signature` |
| `not_included` | the grant doesn't include realtime |
| `bad_request` | no channels, or an event named `realtime:…` |
| `too_many`, `too_large` | over 100 channels or 10 events, or data over 10 KB |
| `unreachable`, `http_` | the server couldn't be reached |
## Calls
From `calls.start()`, `incoming.accept()` and `calls.room()`, from your calls route (`denied`), and as a call's `endReason`:
| Code | Why |
|---|---|
| `forbidden` | your `calls()` callback said no, or nothing owns the call |
| `no_user` | nobody signed in, or a user id that isn't an integer (this version) |
| `not_included` | the grant doesn't include calls |
| `bad_request` | a name the server doesn't take, or calling yourself |
| `bad_token`, `expired` | the token wasn't your app's, or ran out |
| `no_call`, `call_ended`, `answered_elsewhere` | answered too late, or on another device |
| `auth_failed`, `no_auth` | your calls route didn't answer, or the page has none |
| `no_rooms_script`, `rooms_script_failed`, `rooms_script_broken` | the room client isn't served, or didn't load |
| `signaling_unavailable` | the page's connection was down |
---
Source: https://docs.wordplus.cloud/apps/limits/
# Limits
## Your account
| | |
|---|---|
| Apps | as your account's grant says (Apps in your WordPlus Cloud account) |
| Connections at once | as your grant says, all your apps together, across WordPlus Cloud. A browser's tabs share one connection when your app serves the worker |
| An app's addresses | 20 |
## Channels
| | |
|---|---|
| A channel's name | up to 200 characters of `A-Z a-z 0-9 _ - = @ , . ;` |
| Channels a connection holds | 1,000 |
| An event's data | 10 KB of JSON |
| Channels one publish goes to | 100 |
| Events in one batch | 10 |
| A presence channel's members | 1,000, the first 100 listed when subscribing |
| A member's `info` | 1 KB |
| Client events | 10 a second a browser, 10 KB each |
| A channels token's life | 6 hours by default, at most a day; renewed by the page |
| A signed request's clock | within 5 minutes of the server's |
## Calls
| | |
|---|---|
| People in a call | two; a room for more |
| Ringing | 45 seconds, then `no_answer` |
| A side's connection away during a call | 45 seconds to come back |
| A calls token's life | 6 hours at most; renewed by the page |
| A room | 32 people with video, 50 audio only |
| User ids | integers, in this version |