wordplus-realtime 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wordplus_realtime-1.0.0/.gitattributes +3 -0
- wordplus_realtime-1.0.0/.github/workflows/release.yml +40 -0
- wordplus_realtime-1.0.0/.gitignore +6 -0
- wordplus_realtime-1.0.0/LICENSE +21 -0
- wordplus_realtime-1.0.0/PKG-INFO +133 -0
- wordplus_realtime-1.0.0/README.md +97 -0
- wordplus_realtime-1.0.0/docs/django/calls.md +115 -0
- wordplus_realtime-1.0.0/docs/django/customizing.md +71 -0
- wordplus_realtime-1.0.0/docs/django/deploying.md +41 -0
- wordplus_realtime-1.0.0/docs/django/encryption.md +82 -0
- wordplus_realtime-1.0.0/docs/django/events.md +135 -0
- wordplus_realtime-1.0.0/docs/django/example.md +43 -0
- wordplus_realtime-1.0.0/docs/django/getting-started.md +141 -0
- wordplus_realtime-1.0.0/docs/django/presence.md +89 -0
- wordplus_realtime-1.0.0/docs/django/rooms.md +80 -0
- wordplus_realtime-1.0.0/docs/django/sending.md +103 -0
- wordplus_realtime-1.0.0/docs/django/streams.md +70 -0
- wordplus_realtime-1.0.0/docs/fastapi/calls.md +115 -0
- wordplus_realtime-1.0.0/docs/fastapi/customizing.md +71 -0
- wordplus_realtime-1.0.0/docs/fastapi/deploying.md +49 -0
- wordplus_realtime-1.0.0/docs/fastapi/encryption.md +84 -0
- wordplus_realtime-1.0.0/docs/fastapi/events.md +99 -0
- wordplus_realtime-1.0.0/docs/fastapi/example.md +37 -0
- wordplus_realtime-1.0.0/docs/fastapi/getting-started.md +126 -0
- wordplus_realtime-1.0.0/docs/fastapi/presence.md +89 -0
- wordplus_realtime-1.0.0/docs/fastapi/rooms.md +80 -0
- wordplus_realtime-1.0.0/docs/fastapi/sending.md +103 -0
- wordplus_realtime-1.0.0/docs/fastapi/streams.md +70 -0
- wordplus_realtime-1.0.0/docs/flask/calls.md +115 -0
- wordplus_realtime-1.0.0/docs/flask/customizing.md +71 -0
- wordplus_realtime-1.0.0/docs/flask/deploying.md +41 -0
- wordplus_realtime-1.0.0/docs/flask/encryption.md +84 -0
- wordplus_realtime-1.0.0/docs/flask/events.md +99 -0
- wordplus_realtime-1.0.0/docs/flask/example.md +37 -0
- wordplus_realtime-1.0.0/docs/flask/getting-started.md +114 -0
- wordplus_realtime-1.0.0/docs/flask/presence.md +89 -0
- wordplus_realtime-1.0.0/docs/flask/rooms.md +80 -0
- wordplus_realtime-1.0.0/docs/flask/sending.md +103 -0
- wordplus_realtime-1.0.0/docs/flask/streams.md +70 -0
- wordplus_realtime-1.0.0/docs/reference.md +107 -0
- wordplus_realtime-1.0.0/examples/django/.env.example +5 -0
- wordplus_realtime-1.0.0/examples/django/.gitignore +6 -0
- wordplus_realtime-1.0.0/examples/django/README.md +20 -0
- wordplus_realtime-1.0.0/examples/django/config/__init__.py +0 -0
- wordplus_realtime-1.0.0/examples/django/config/settings.py +67 -0
- wordplus_realtime-1.0.0/examples/django/config/urls.py +19 -0
- wordplus_realtime-1.0.0/examples/django/config/wsgi.py +6 -0
- wordplus_realtime-1.0.0/examples/django/demo.py +106 -0
- wordplus_realtime-1.0.0/examples/django/manage.py +10 -0
- wordplus_realtime-1.0.0/examples/django/requirements.txt +2 -0
- wordplus_realtime-1.0.0/examples/django/shop/avatars/ann.svg +1 -0
- wordplus_realtime-1.0.0/examples/django/shop/avatars/ben.svg +1 -0
- wordplus_realtime-1.0.0/examples/django/shop/avatars/cara.svg +1 -0
- wordplus_realtime-1.0.0/examples/django/shop/products/mugs.webp +0 -0
- wordplus_realtime-1.0.0/examples/django/shop/shop.css +719 -0
- wordplus_realtime-1.0.0/examples/django/shop/shop.js +572 -0
- wordplus_realtime-1.0.0/examples/django/store/__init__.py +0 -0
- wordplus_realtime-1.0.0/examples/django/store/apps.py +5 -0
- wordplus_realtime-1.0.0/examples/django/store/migrations/0001_initial.py +43 -0
- wordplus_realtime-1.0.0/examples/django/store/migrations/0002_shop_data.py +25 -0
- wordplus_realtime-1.0.0/examples/django/store/migrations/0003_kept_chat.py +29 -0
- wordplus_realtime-1.0.0/examples/django/store/migrations/__init__.py +0 -0
- wordplus_realtime-1.0.0/examples/django/store/models.py +50 -0
- wordplus_realtime-1.0.0/examples/django/store/realtime.py +152 -0
- wordplus_realtime-1.0.0/examples/django/store/shops.py +65 -0
- wordplus_realtime-1.0.0/examples/django/store/templates/store/login.html +21 -0
- wordplus_realtime-1.0.0/examples/django/store/templates/store/page.html +26 -0
- wordplus_realtime-1.0.0/examples/django/store/views.py +140 -0
- wordplus_realtime-1.0.0/examples/fastapi/.env.example +5 -0
- wordplus_realtime-1.0.0/examples/fastapi/.gitignore +4 -0
- wordplus_realtime-1.0.0/examples/fastapi/README.md +15 -0
- wordplus_realtime-1.0.0/examples/fastapi/app.py +367 -0
- wordplus_realtime-1.0.0/examples/fastapi/demo.py +106 -0
- wordplus_realtime-1.0.0/examples/fastapi/requirements.txt +6 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/ann.svg +1 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/ben.svg +1 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/cara.svg +1 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/products/mugs.webp +0 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/shop.css +719 -0
- wordplus_realtime-1.0.0/examples/fastapi/shop/shop.js +572 -0
- wordplus_realtime-1.0.0/examples/fastapi/templates/login.html +20 -0
- wordplus_realtime-1.0.0/examples/fastapi/templates/page.html +24 -0
- wordplus_realtime-1.0.0/examples/flask/.env.example +5 -0
- wordplus_realtime-1.0.0/examples/flask/.gitignore +4 -0
- wordplus_realtime-1.0.0/examples/flask/README.md +15 -0
- wordplus_realtime-1.0.0/examples/flask/app.py +359 -0
- wordplus_realtime-1.0.0/examples/flask/demo.py +106 -0
- wordplus_realtime-1.0.0/examples/flask/requirements.txt +2 -0
- wordplus_realtime-1.0.0/examples/flask/shop/avatars/ann.svg +1 -0
- wordplus_realtime-1.0.0/examples/flask/shop/avatars/ben.svg +1 -0
- wordplus_realtime-1.0.0/examples/flask/shop/avatars/cara.svg +1 -0
- wordplus_realtime-1.0.0/examples/flask/shop/products/mugs.webp +0 -0
- wordplus_realtime-1.0.0/examples/flask/shop/shop.css +719 -0
- wordplus_realtime-1.0.0/examples/flask/shop/shop.js +572 -0
- wordplus_realtime-1.0.0/examples/flask/templates/login.html +20 -0
- wordplus_realtime-1.0.0/examples/flask/templates/page.html +24 -0
- wordplus_realtime-1.0.0/pyproject.toml +47 -0
- wordplus_realtime-1.0.0/spec/stream-grants.json +110 -0
- wordplus_realtime-1.0.0/spec/vectors.json +106 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/__init__.py +40 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/django/__init__.py +185 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/django/apps.py +9 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/django/routes.py +6 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/django/templatetags/__init__.py +0 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/django/templatetags/wordplus_realtime.py +24 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/fastapi.py +84 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/THIRD-PARTY-NOTICES.txt +1116 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/files.json +11 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-rooms-e2ee.worker.js +3 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-rooms.min.js +3 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui-streams.min.js +3502 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui.THIRD-PARTY-NOTICES.txt +1072 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui.min.js +6053 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-worker.js +2 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime.js +5 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/flask.py +81 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/keys.py +234 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/patterns.py +76 -0
- wordplus_realtime-1.0.0/src/wordplus_realtime/realtime.py +1597 -0
- wordplus_realtime-1.0.0/tests/test_docs.py +32 -0
- wordplus_realtime-1.0.0/tests/test_frameworks.py +349 -0
- wordplus_realtime-1.0.0/tests/test_realtime.py +879 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# The release of wordplus-realtime: a tag vX.Y.Z, pushed by WordPlus's publish script with the release's files, is
|
|
2
|
+
# tested, built and published to PyPI through its trusted publishing (no token: PyPI trusts this repository's
|
|
3
|
+
# release.yml in the environment `release`), then made the GitHub release with the wheel and the sdist.
|
|
4
|
+
name: Release
|
|
5
|
+
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
tags: ['v*']
|
|
9
|
+
|
|
10
|
+
permissions:
|
|
11
|
+
contents: write
|
|
12
|
+
id-token: write
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
release:
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
environment: release
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
|
|
21
|
+
- uses: astral-sh/setup-uv@v6
|
|
22
|
+
|
|
23
|
+
- name: The tag is the package's version
|
|
24
|
+
run: test "v$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)" = "$GITHUB_REF_NAME"
|
|
25
|
+
|
|
26
|
+
- name: Tests
|
|
27
|
+
run: |
|
|
28
|
+
uv venv
|
|
29
|
+
uv pip install -e '.[test]'
|
|
30
|
+
.venv/bin/python -m pytest -q
|
|
31
|
+
|
|
32
|
+
- run: uv build
|
|
33
|
+
|
|
34
|
+
- name: PyPI
|
|
35
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
36
|
+
|
|
37
|
+
- name: The GitHub release
|
|
38
|
+
env:
|
|
39
|
+
GH_TOKEN: ${{ github.token }}
|
|
40
|
+
run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes "wordplus-realtime ${GITHUB_REF_NAME#v}"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 WordPlus
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wordplus-realtime
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: WordPlus Cloud's realtime SDK for Python outside WordPress: rooms with presence and history, online status, events to rooms and users, webhooks, calls between two people that ring in the browser, group calls, sealed end to end. Signs what the browser package (@wordplus/realtime) asks for and emits; Django, FastAPI and Flask included, and the browser files served from its own routes.
|
|
5
|
+
Project-URL: Homepage, https://docs.wordplus.cloud/django/getting-started/
|
|
6
|
+
Project-URL: Documentation, https://docs.wordplus.cloud/apps/python-reference/
|
|
7
|
+
Project-URL: Source, https://github.com/wordplus-cloud/realtime-python
|
|
8
|
+
Author: WordPlus
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: django,end-to-end encryption,fastapi,flask,presence,realtime,rooms,video calls,webrtc,websocket
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Framework :: FastAPI
|
|
15
|
+
Classifier: Framework :: Flask
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Topic :: Communications
|
|
19
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Requires-Dist: pynacl>=1.5
|
|
22
|
+
Provides-Extra: django
|
|
23
|
+
Requires-Dist: django>=4.2; extra == 'django'
|
|
24
|
+
Provides-Extra: fastapi
|
|
25
|
+
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
|
|
26
|
+
Provides-Extra: flask
|
|
27
|
+
Requires-Dist: flask>=3.0; extra == 'flask'
|
|
28
|
+
Provides-Extra: test
|
|
29
|
+
Requires-Dist: django>=4.2; extra == 'test'
|
|
30
|
+
Requires-Dist: fastapi>=0.100; extra == 'test'
|
|
31
|
+
Requires-Dist: flask-login>=0.6; extra == 'test'
|
|
32
|
+
Requires-Dist: flask>=3.0; extra == 'test'
|
|
33
|
+
Requires-Dist: httpx>=0.27; extra == 'test'
|
|
34
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# wordplus-realtime
|
|
38
|
+
|
|
39
|
+
WordPlus Cloud's realtime SDK for Python, outside WordPress: your server's part of rooms, presence, who is online, calls and group calls, sealed end to end. It declares your rooms and who may join, call and see what, signs it for the browser, and sends your events to rooms and to users. The browser part is the npm package [`@wordplus/realtime`](https://docs.wordplus.cloud/apps/browser/), with Better Messages' chat, list of who is online and call screen as ready-made parts.
|
|
40
|
+
|
|
41
|
+
**Docs:** a whole guide each for [Django](https://docs.wordplus.cloud/django/getting-started/), [FastAPI](https://docs.wordplus.cloud/fastapi/getting-started/) and [Flask](https://docs.wordplus.cloud/flask/getting-started/) (in this package: [docs/django](docs/django/getting-started.md), [docs/fastapi](docs/fastapi/getting-started.md), [docs/flask](docs/flask/getting-started.md)), and the [Python reference](docs/reference.md).
|
|
42
|
+
|
|
43
|
+
**Examples:** the same shop in [Django](examples/django), [FastAPI](examples/fastapi) and [Flask](examples/flask): sign in as Ann, Ben or Cara, and try live updates, a chat with typing, reactions and read ticks, who is online, calls and a group call.
|
|
44
|
+
|
|
45
|
+
It answers the browser exactly as WordPress's [`wordplus/realtime`](https://docs.wordplus.cloud/wordpress/getting-started/) does, and the Node and PHP packages: the same routes, tokens, keys and calls, checked against the same vectors (`spec/vectors.json`).
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
pip install 'wordplus-realtime[django]' # or [fastapi] or [flask], or none; uv add works the same
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
It carries the browser files too, the client as an ES module among them, and its routes serve them, so a Python app needs no Node: the page head it writes names `@wordplus/realtime` the client by an import map. With a bundler of your own, `npm install @wordplus/realtime`. It is also on WordPlus's own mirror, for a network that can't reach PyPI: add `--find-links https://packages.wordplus.cloud/pypi/index.html` to pip or uv.
|
|
52
|
+
|
|
53
|
+
```dotenv
|
|
54
|
+
WORDPLUS_SITE=s1500000007 # your app's key, from your WordPlus Cloud account (Apps)
|
|
55
|
+
WORDPLUS_SECRET=… # its secret, never in a page
|
|
56
|
+
WORDPLUS_LOCAL_KEY=… # your own: openssl rand -hex 32; it never leaves your servers
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from wordplus_realtime import Realtime
|
|
61
|
+
|
|
62
|
+
realtime = Realtime.from_environment(profile=lambda user: {"name": name_of(user)})
|
|
63
|
+
realtime.room("order:{id}", lambda user, p: owns_order(user, p["id"]), history=20)
|
|
64
|
+
realtime.room("chat:{a}:{b}", lambda user, p: str(user) in (p["a"], p["b"]), history=50, emit=["message", "typing"])
|
|
65
|
+
realtime.calls("support:{a}:{b}", lambda user, other, p: may_support(user, other))
|
|
66
|
+
|
|
67
|
+
realtime.to("order:42").emit("updated", {"status": "paid"})
|
|
68
|
+
realtime.to_user(42).emit("notice", {"text": "Your order shipped"})
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Django
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
# settings.py
|
|
75
|
+
INSTALLED_APPS = [..., "wordplus_realtime.django"]
|
|
76
|
+
|
|
77
|
+
# shop/realtime.py, imported by the app ready(): the Realtime made from the environment and WORDPLUS_REALTIME
|
|
78
|
+
from wordplus_realtime.django import realtime
|
|
79
|
+
realtime.room("order:{id}", lambda user, p: owns_order(user, p["id"]), history=20)
|
|
80
|
+
|
|
81
|
+
# urls.py: POST auth, calls, keys for the session user, the webhook, and GET the browser files
|
|
82
|
+
urlpatterns = [path("api/realtime/", include("wordplus_realtime.django.routes"))]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
{% load wordplus_realtime %}
|
|
87
|
+
<head>
|
|
88
|
+
{% wordplus_realtime %} {# the settings with the CSRF token, and the import map of the client #}
|
|
89
|
+
<script type="module">
|
|
90
|
+
import { connect } from '@wordplus/realtime';
|
|
91
|
+
const rt = await connect( window.wordplusRealtimeConfig );
|
|
92
|
+
rt.join( 'order:42' ).on( 'updated', ( data ) => refresh( data ) );
|
|
93
|
+
</script>
|
|
94
|
+
</head>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## FastAPI and Starlette
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import wordplus_realtime.fastapi as wr
|
|
101
|
+
|
|
102
|
+
app.include_router(wr.router(realtime, current_user), prefix="/api/realtime") # current_user(request) may be async
|
|
103
|
+
head = realtime.head(user) # for the page head, as it is
|
|
104
|
+
await realtime.to("order:42").aemit("updated", {"status": "paid"})
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Flask
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import wordplus_realtime.flask
|
|
111
|
+
|
|
112
|
+
wordplus_realtime.flask.init_app(app, realtime) # the routes, the webhook and the files, the Flask-Login user
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
```html
|
|
116
|
+
<head>{{ wordplus_realtime() }}</head>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## In this version
|
|
120
|
+
|
|
121
|
+
- **User ids** are yours, a number or text such as `user_2abc` or `auth0|5f7c`, up to 64 characters with no space, in rooms, presence, calls and the directory alike.
|
|
122
|
+
- **Python 3.9 or later**, with PyNaCl (libsodium) for the sealing.
|
|
123
|
+
|
|
124
|
+
## Licence
|
|
125
|
+
|
|
126
|
+
MIT.
|
|
127
|
+
|
|
128
|
+
## Developing
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
uv venv .venv && uv pip install --python .venv/bin/python -e '.[test]'
|
|
132
|
+
.venv/bin/python -m pytest # the vectors, the routes, tokens, keys, sealing, sending, Django and FastAPI
|
|
133
|
+
```
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# wordplus-realtime
|
|
2
|
+
|
|
3
|
+
WordPlus Cloud's realtime SDK for Python, outside WordPress: your server's part of rooms, presence, who is online, calls and group calls, sealed end to end. It declares your rooms and who may join, call and see what, signs it for the browser, and sends your events to rooms and to users. The browser part is the npm package [`@wordplus/realtime`](https://docs.wordplus.cloud/apps/browser/), with Better Messages' chat, list of who is online and call screen as ready-made parts.
|
|
4
|
+
|
|
5
|
+
**Docs:** a whole guide each for [Django](https://docs.wordplus.cloud/django/getting-started/), [FastAPI](https://docs.wordplus.cloud/fastapi/getting-started/) and [Flask](https://docs.wordplus.cloud/flask/getting-started/) (in this package: [docs/django](docs/django/getting-started.md), [docs/fastapi](docs/fastapi/getting-started.md), [docs/flask](docs/flask/getting-started.md)), and the [Python reference](docs/reference.md).
|
|
6
|
+
|
|
7
|
+
**Examples:** the same shop in [Django](examples/django), [FastAPI](examples/fastapi) and [Flask](examples/flask): sign in as Ann, Ben or Cara, and try live updates, a chat with typing, reactions and read ticks, who is online, calls and a group call.
|
|
8
|
+
|
|
9
|
+
It answers the browser exactly as WordPress's [`wordplus/realtime`](https://docs.wordplus.cloud/wordpress/getting-started/) does, and the Node and PHP packages: the same routes, tokens, keys and calls, checked against the same vectors (`spec/vectors.json`).
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pip install 'wordplus-realtime[django]' # or [fastapi] or [flask], or none; uv add works the same
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
It carries the browser files too, the client as an ES module among them, and its routes serve them, so a Python app needs no Node: the page head it writes names `@wordplus/realtime` the client by an import map. With a bundler of your own, `npm install @wordplus/realtime`. It is also on WordPlus's own mirror, for a network that can't reach PyPI: add `--find-links https://packages.wordplus.cloud/pypi/index.html` to pip or uv.
|
|
16
|
+
|
|
17
|
+
```dotenv
|
|
18
|
+
WORDPLUS_SITE=s1500000007 # your app's key, from your WordPlus Cloud account (Apps)
|
|
19
|
+
WORDPLUS_SECRET=… # its secret, never in a page
|
|
20
|
+
WORDPLUS_LOCAL_KEY=… # your own: openssl rand -hex 32; it never leaves your servers
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from wordplus_realtime import Realtime
|
|
25
|
+
|
|
26
|
+
realtime = Realtime.from_environment(profile=lambda user: {"name": name_of(user)})
|
|
27
|
+
realtime.room("order:{id}", lambda user, p: owns_order(user, p["id"]), history=20)
|
|
28
|
+
realtime.room("chat:{a}:{b}", lambda user, p: str(user) in (p["a"], p["b"]), history=50, emit=["message", "typing"])
|
|
29
|
+
realtime.calls("support:{a}:{b}", lambda user, other, p: may_support(user, other))
|
|
30
|
+
|
|
31
|
+
realtime.to("order:42").emit("updated", {"status": "paid"})
|
|
32
|
+
realtime.to_user(42).emit("notice", {"text": "Your order shipped"})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Django
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
# settings.py
|
|
39
|
+
INSTALLED_APPS = [..., "wordplus_realtime.django"]
|
|
40
|
+
|
|
41
|
+
# shop/realtime.py, imported by the app ready(): the Realtime made from the environment and WORDPLUS_REALTIME
|
|
42
|
+
from wordplus_realtime.django import realtime
|
|
43
|
+
realtime.room("order:{id}", lambda user, p: owns_order(user, p["id"]), history=20)
|
|
44
|
+
|
|
45
|
+
# urls.py: POST auth, calls, keys for the session user, the webhook, and GET the browser files
|
|
46
|
+
urlpatterns = [path("api/realtime/", include("wordplus_realtime.django.routes"))]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```html
|
|
50
|
+
{% load wordplus_realtime %}
|
|
51
|
+
<head>
|
|
52
|
+
{% wordplus_realtime %} {# the settings with the CSRF token, and the import map of the client #}
|
|
53
|
+
<script type="module">
|
|
54
|
+
import { connect } from '@wordplus/realtime';
|
|
55
|
+
const rt = await connect( window.wordplusRealtimeConfig );
|
|
56
|
+
rt.join( 'order:42' ).on( 'updated', ( data ) => refresh( data ) );
|
|
57
|
+
</script>
|
|
58
|
+
</head>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## FastAPI and Starlette
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
import wordplus_realtime.fastapi as wr
|
|
65
|
+
|
|
66
|
+
app.include_router(wr.router(realtime, current_user), prefix="/api/realtime") # current_user(request) may be async
|
|
67
|
+
head = realtime.head(user) # for the page head, as it is
|
|
68
|
+
await realtime.to("order:42").aemit("updated", {"status": "paid"})
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Flask
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
import wordplus_realtime.flask
|
|
75
|
+
|
|
76
|
+
wordplus_realtime.flask.init_app(app, realtime) # the routes, the webhook and the files, the Flask-Login user
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```html
|
|
80
|
+
<head>{{ wordplus_realtime() }}</head>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## In this version
|
|
84
|
+
|
|
85
|
+
- **User ids** are yours, a number or text such as `user_2abc` or `auth0|5f7c`, up to 64 characters with no space, in rooms, presence, calls and the directory alike.
|
|
86
|
+
- **Python 3.9 or later**, with PyNaCl (libsodium) for the sealing.
|
|
87
|
+
|
|
88
|
+
## Licence
|
|
89
|
+
|
|
90
|
+
MIT.
|
|
91
|
+
|
|
92
|
+
## Developing
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
uv venv .venv && uv pip install --python .venv/bin/python -e '.[test]'
|
|
96
|
+
.venv/bin/python -m pytest # the vectors, the routes, tokens, keys, sealing, sending, Django and FastAPI
|
|
97
|
+
```
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Calls in Django
|
|
2
|
+
|
|
3
|
+
Calls between two people that ring in every tab and device the callee has open, group calls on the WordPlus Cloud media servers, and the Better Messages call screen: the buttons, the ring and the call window, with no call code. The media of a call is encrypted end to end, with keys your server gives out.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## Who may call
|
|
8
|
+
|
|
9
|
+
Your server declares calls as it declares rooms, by pattern:
|
|
10
|
+
|
|
11
|
+
```python
|
|
12
|
+
# shop/realtime.py: calls between two people, support:34:42, the two it names, one of them staff.
|
|
13
|
+
def may_call(user, with_user, p):
|
|
14
|
+
pair = [p["a"], p["b"]] # the two ids in the name, as text
|
|
15
|
+
return str(user) in pair and str(with_user) in pair and (is_staff(user) or is_staff(with_user))
|
|
16
|
+
|
|
17
|
+
realtime.calls("support:{a}:{b}", may_call)
|
|
18
|
+
|
|
19
|
+
# Pro members call anyone, pro:42:7, and anyone answers: call and side, the fourth and fifth arguments, say which side asks.
|
|
20
|
+
def may_call_pro(user, with_user, p, call, side):
|
|
21
|
+
pair = [p["a"], p["b"]]
|
|
22
|
+
if str(user) not in pair or str(with_user) not in pair:
|
|
23
|
+
return False
|
|
24
|
+
return side["role"] == "callee" or is_pro(user)
|
|
25
|
+
|
|
26
|
+
realtime.calls("pro:{a}:{b}", may_call_pro)
|
|
27
|
+
|
|
28
|
+
# The daily meeting: a group call for everyone signed in.
|
|
29
|
+
realtime.group_calls("meeting:{id}", lambda user: user is not None)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- **`with_user`** is the other person: whom `user` calls, or who calls `user`. Your server is asked again when the callee answers, with the callee as `user`.
|
|
33
|
+
- **`call` and `side`**, the fourth and fifth arguments when the rule takes them, are the call name (`pro:42:7`) and which side asks: `side["role"]` is `caller` or `callee`. A rule that says yes to every callee and checks only callers lets people answer calls they may not place.
|
|
34
|
+
- **The answer:** `False`, `True`, or a dict: `info` (what the others see of `user`: your `profile` by default), and in a group call `publish`, `subscribe`, `admin` and `hidden`. `admin` makes them its host: the call screen gives them mute, let speak or make a listener, and remove on the tile of each of the others, which your calls route takes only from a host ([permissions](https://docs.wordplus.cloud/apps/permissions/#group-calls)).
|
|
35
|
+
- **The rooms of a group call** can be encrypted end to end too: `realtime.group_calls("meeting:{id}", rule, encrypt=True)`. The rooms that come from a call always are.
|
|
36
|
+
- **User ids** are yours: a number, or text such as `user_2abc` or `auth0|5f7c`, up to 64 characters with no space. A rule gets an id of digits as a number and any other as text, so compare them with the name as text. An id calls cannot take is refused with `no_user`.
|
|
37
|
+
|
|
38
|
+
The calls route (`/api/realtime/calls`) is already among `wr.urls()`.
|
|
39
|
+
|
|
40
|
+
## The call screen
|
|
41
|
+
|
|
42
|
+
Optional, as every ready-made part: [your own call interface](#your-own-call-interface) below places, answers and draws calls with no element, and [your own interface](https://docs.wordplus.cloud/apps/interface/#calls) has the whole of it.
|
|
43
|
+
|
|
44
|
+
Start it on every page where a call may ring, and put buttons where people call from:
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
await rt.callScreen(); // the ring and the call window, on this page
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```html
|
|
51
|
+
<call-button to="{{ agent.pk }}" call="support:{pair}" type="video" name="{{ agent.get_full_name }}">Call {{ agent.first_name }}</call-button>
|
|
52
|
+
<room-button room="meeting:daily" type="video" title="Daily meeting">Join the meeting</room-button>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- **`{pair}`** in `call` is filled in with the page user and the one called, in order, so whichever of the two calls names the same call: `support:34:42`.
|
|
56
|
+
- **A list with call buttons:** `<online-list room="shop" call="support:{pair}">` puts one on the row of every member ([presence](presence.md#ready-made-who-is-online)).
|
|
57
|
+
- **Its words** come in English, German, Spanish, French, Italian, Dutch, Polish, Croatian and Hebrew, by the page `<html lang="{{ LANGUAGE_CODE }}">`. `rt.callScreen( { strings: { … } } )` changes any of them.
|
|
58
|
+
- **Its look** is that of Better Messages, in a shadow root: your styles do not reach in, and its colours are CSS custom properties your page sets.
|
|
59
|
+
- **Group calls** load the room client and its encryption worker from the routes, which the page settings name: nothing to add.
|
|
60
|
+
|
|
61
|
+

|
|
62
|
+
|
|
63
|
+
## Adding people
|
|
64
|
+
|
|
65
|
+
Once a call is up, either side may ring someone else in, and it goes on as a group call. Say whom the call screen offers:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
# The staff not in the call, each still asked of may_call.
|
|
69
|
+
def staff_to_add(user, call):
|
|
70
|
+
return list(User.objects.filter(is_staff=True).exclude(pk__in=call.split(":")[1:]).values_list("pk", flat=True))
|
|
71
|
+
|
|
72
|
+
realtime.calls("support:{a}:{b}", may_call, people=staff_to_add)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The screen then shows an Add person button, listing them with the names and pictures from your `profile`.
|
|
76
|
+
|
|
77
|
+
## Your own call interface
|
|
78
|
+
|
|
79
|
+
The call screen is built on this, and nothing else:
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
const calls = await rt.calls();
|
|
83
|
+
|
|
84
|
+
const call = await calls.start( 'support:34:42', { to: 34, type: 'video' } );
|
|
85
|
+
call.on( 'state', ( state ) => show( state ) ); // ringing, connecting, connected, reconnecting, ended
|
|
86
|
+
call.on( 'remote', () => call.remote.camera?.attach( video ) );
|
|
87
|
+
|
|
88
|
+
calls.on( 'incoming', async ( incoming ) => {
|
|
89
|
+
const answered = await incoming.accept(); // the call, or the group call it rings into. Or incoming.decline( 'busy' )
|
|
90
|
+
} );
|
|
91
|
+
|
|
92
|
+
const meeting = await calls.group( 'meeting:daily', { type: 'video' } );
|
|
93
|
+
meeting.on( 'person', ( person ) => person.camera?.attach( tileFor( person ) ) );
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+

|
|
97
|
+
|
|
98
|
+
## From your server
|
|
99
|
+
|
|
100
|
+
Your server sees the group calls going on and runs them, with no page open:
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
realtime.list_calls() # [{"name", "people", "started_at"}]
|
|
104
|
+
call = realtime.call("meeting:daily")
|
|
105
|
+
call.get() # {"people", "started_at", "list": [{"user", "joined_at", "camera", "microphone", "screen"}]}
|
|
106
|
+
call.permit(43, publish=True) # a listener let speak, publish=False back to listening
|
|
107
|
+
call.mute(43, "microphone") # "camera" or "screen" too: they may turn it on again
|
|
108
|
+
call.remove(43) # out now, their tokens from before refused
|
|
109
|
+
call.end() # out, everyone
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
- **A host's buttons** are on the call screen already, for whom the rule answers `admin`: mute, let speak or make a listener, and remove. Buttons of your own call a route of yours that checks who asks, then these. A rule that answers `{"publish": False}` makes a listener, whom `permit()` lets speak while the call runs.
|
|
113
|
+
- **`get()`** with nobody in the call answers `people` 0, `started_at` None and an empty list. `started_at` is when this call began: one named again after everyone left begins again.
|
|
114
|
+
|
|
115
|
+
Every event, why a call ended, and what WordPlus Cloud sees: [calls in depth](https://docs.wordplus.cloud/apps/calls/).
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Customizing the screens in Django
|
|
2
|
+
|
|
3
|
+
The call screen, the chat and the list of who is online can be made part of the design of your app, or changed down to their code, with your AI coding agent or by hand. Each step goes further than the last: [making the screens your own](https://docs.wordplus.cloud/apps/customizing/) has every detail.
|
|
4
|
+
|
|
5
|
+
## 1. The look
|
|
6
|
+
|
|
7
|
+
The elements draw in a shadow root, and their colours are custom properties your page sets:
|
|
8
|
+
|
|
9
|
+
```css
|
|
10
|
+
/* static/shop.css */
|
|
11
|
+
call-screen, chat-room, online-list {
|
|
12
|
+
--bm-color-accent: 37, 99, 235; /* red, green, blue */
|
|
13
|
+
--bm-messenger-font: Inter, system-ui, sans-serif;
|
|
14
|
+
--bm-radius-card: 14px;
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 2. A piece of your own
|
|
19
|
+
|
|
20
|
+
Your stylesheet reaches each piece by its name, and a `<template slot>` draws one with your own markup:
|
|
21
|
+
|
|
22
|
+
```css
|
|
23
|
+
chat-room::part(message) { font-size: 15px; }
|
|
24
|
+
call-screen::part(call-controls) { bottom: 24px; }
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
{# shop/templates/shop/order.html #}
|
|
29
|
+
<chat-room room="order-chat:{{ order.pk }}" messages="{% url 'order-messages' order.pk %}">
|
|
30
|
+
<template slot="empty-conversation"><p>{% translate "Ask us anything about this order." %}</p></template>
|
|
31
|
+
</chat-room>
|
|
32
|
+
|
|
33
|
+
<call-screen>
|
|
34
|
+
<template slot="control" data-control="order" data-label="{% translate 'Show the order' %}" data-icon="edit"></template>
|
|
35
|
+
</call-screen>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
// order.js
|
|
40
|
+
document.addEventListener( 'realtime-control', ( e ) => { if ( e.detail.control === 'order' ) showOrder(); } );
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Every part, every template and what fills it: [on any page](https://docs.wordplus.cloud/apps/customizing/#on-any-page-the-elements).
|
|
44
|
+
|
|
45
|
+
The names are plain words, so your pages name no one but your app. To put your own before each, `screen: { prefix: 'shop' }` in `connect()` makes `<shop-chat-room>` and `<shop-call-screen>` ([your own names](https://docs.wordplus.cloud/apps/elements/#your-own-names)).
|
|
46
|
+
|
|
47
|
+
## 3. The code itself
|
|
48
|
+
|
|
49
|
+
Copy a view into your project. It is React, built once into your own elements script with Node:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm install @wordplus/realtime-ui
|
|
53
|
+
npm install -D react react-dom esbuild
|
|
54
|
+
npx @wordplus/realtime-ui add chat
|
|
55
|
+
node wordplus-ui.build.mjs # static/realtime-ui.js, with your copy
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
// order.js
|
|
60
|
+
const rt = await connect( { ...JSON.parse( document.getElementById( 'realtime' ).textContent ), ui: '/static/realtime-ui.js' } );
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The view is yours now: `components/wordplus/chat/`, and what runs the conversation stays in the package. Build again after each change, before `collectstatic`. Check it with its tests (`npx vitest run components/wordplus`) and every state in the preview (`npx @wordplus/realtime-ui preview`). When ours changes, `npx @wordplus/realtime-ui diff` shows what to merge.
|
|
64
|
+
|
|
65
|
+
## 4. Your own interface
|
|
66
|
+
|
|
67
|
+
The elements are the ready-made option, never a must. Draw who is online, the chat, the calls and the live stream with your own components, on the same API they are built on: your rules, encryption and connection stay the same. [Your own interface](https://docs.wordplus.cloud/apps/interface/) shows the API under each element.
|
|
68
|
+
|
|
69
|
+
## With your AI coding agent
|
|
70
|
+
|
|
71
|
+
The agent skill of the package teaches it all of this. Ask for what you want, such as "put the order status at the top of the chat", and it changes the screens at the step that does it, then runs the tests and looks at the preview.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Deploying a Django app
|
|
2
|
+
|
|
3
|
+
Under Gunicorn or uWSGI behind nginx, on a PaaS, or under an ASGI server: nothing realtime is kept on your servers, so any of them answers any request.
|
|
4
|
+
|
|
5
|
+
## Its settings
|
|
6
|
+
|
|
7
|
+
| | |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `WORDPLUS_SITE`, `WORDPLUS_SECRET` | from your app in WordPlus Cloud |
|
|
10
|
+
| `WORDPLUS_LOCAL_KEY` | yours: kept as long as the app |
|
|
11
|
+
|
|
12
|
+
Set them in the server environment, as you do `SECRET_KEY`. Keep the secret and the local key out of your repository and out of every page. The key reaches pages through `{% wordplus_realtime %}`, which is what it is for.
|
|
13
|
+
|
|
14
|
+
## Its addresses
|
|
15
|
+
|
|
16
|
+
Add every address your pages are served from to the app in WordPlus Cloud: scheme, host and port exactly (`https://shop.example.com`, `https://www.shop.example.com`). A page anywhere else is refused with `wrong_origin`. Up to 20 addresses an app. If your server hears [webhooks](sending.md#webhooks), set their address there too.
|
|
17
|
+
|
|
18
|
+
## Its files
|
|
19
|
+
|
|
20
|
+
`realtime.js`, `realtime-worker.js`, `realtime-rooms.min.js`, `realtime-rooms-e2ee.worker.js`, `realtime-ui.min.js` and `realtime-ui-streams.min.js` come with the package, and the app `wordplus_realtime.django`, through `include("wordplus_realtime.django.routes")`, serves them at `/api/realtime/files/{version}/{name}`, from the address of your pages, where a browser runs a worker. Each release serves the ones its package came with, nothing is copied, and each answer is kept for a year as immutable, so a CDN in front of your app keeps them too. They are not static files, so `collectstatic` and a CDN on another host for static files leave them alone.
|
|
21
|
+
|
|
22
|
+
## Workers and threads
|
|
23
|
+
|
|
24
|
+
The routes and the rules are plain functions, so every Gunicorn worker answers them. An emit is an HTTPS request to WordPlus Cloud, done in the view. For many emits, or ones you do not want a request to wait on, send them from Celery or a task queue.
|
|
25
|
+
|
|
26
|
+
## Behind a proxy
|
|
27
|
+
|
|
28
|
+
Set `SECURE_PROXY_SSL_HEADER` and `CSRF_TRUSTED_ORIGINS` as for any Django app behind TLS: the browser routes use the session and the Django CSRF check.
|
|
29
|
+
|
|
30
|
+
## Content Security Policy
|
|
31
|
+
|
|
32
|
+
If your pages send one, let them reach the WordPlus Cloud servers (the realtime servers, which may move a connection to another of them, and the media servers for group calls) and run the workers from your own address:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
connect-src 'self' https://*.wordplus.cloud wss://*.wordplus.cloud;
|
|
36
|
+
worker-src 'self';
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Clocks
|
|
40
|
+
|
|
41
|
+
Your server signs what it sends with the time. Keep its clock synced (NTP): one more than 5 minutes off has its emits refused with `stale_signature`.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Encryption and your users in Django
|
|
2
|
+
|
|
3
|
+
What your app sends through WordPlus Cloud is sealed on the way: the realtime servers carry it, and keep the history of a room, without being able to read or change it. You write no encryption code. Your server holds the keys and gives each user the ones they may have. The page opens everything before your listener sees it.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## What is sealed
|
|
8
|
+
|
|
9
|
+
| What | Sealed with | Who can open it |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| Events to a room, from your server or a page, and its kept history | the room key | whoever the room rule lets in |
|
|
12
|
+
| The `info` of a presence member | the room key | the same |
|
|
13
|
+
| Events your server sends a user (`to_user`) | the key of the user | the pages of that user |
|
|
14
|
+
| What the people in a call see of each other | the day key | everyone your app knows |
|
|
15
|
+
| Your users in the directory | the day key | everyone your app knows |
|
|
16
|
+
| The media of a call | a key for that call | its people |
|
|
17
|
+
|
|
18
|
+
A room declared `public=True` is not sealed, and neither is one with `seal=False`. The realtime servers see room names, event names, user ids, which key a value needs, and sealed values. They never hold a key.
|
|
19
|
+
|
|
20
|
+
## Your local key
|
|
21
|
+
|
|
22
|
+
`WORDPLUS_LOCAL_KEY` is the master every key is derived from. Keep it the same on every server of the app (Python, Node and PHP derive the same keys from it), as long as the app, and out of every page. Unlike `SECRET_KEY`, it is not for rotating: a new one means pages holding old keys cannot open what comes, until they reload, and the history kept before cannot be opened at all.
|
|
23
|
+
|
|
24
|
+
## When someone loses access
|
|
25
|
+
|
|
26
|
+
Move a key on, and what comes next is sealed from them. The key generations live somewhere every server sees: a cache that does not evict, such as Redis or the database cache, but not the local memory one.
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from django.core.cache import caches
|
|
30
|
+
|
|
31
|
+
class CacheGenerations:
|
|
32
|
+
def get(self, name):
|
|
33
|
+
return caches["default"].get("wordplus-realtime:" + name)
|
|
34
|
+
|
|
35
|
+
def set(self, name, generation):
|
|
36
|
+
caches["default"].set("wordplus-realtime:" + name, generation, timeout=None)
|
|
37
|
+
|
|
38
|
+
realtime = Realtime.from_environment(profile=wr.user_profile, generations=CacheGenerations())
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
realtime.in_room("chat:34:42").kick(43) # out of the room now, and its key moves on
|
|
43
|
+
realtime.rotate_room("order:1042") # the order moved to another customer
|
|
44
|
+
realtime.rotate_user(user.pk) # their own key moves on
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Those still let in get the new key from your server with the next event, and keep the old ones for the history before it.
|
|
48
|
+
|
|
49
|
+
## Your users
|
|
50
|
+
|
|
51
|
+
A directory of your users, each profile sealed with the day key, that every page of your app reads. `wr.user_profile` shows the full name of a user, or their username. For more, such as an avatar, write your own:
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
def profile(user_id):
|
|
55
|
+
user = User.objects.filter(pk=user_id).select_related("profile").first()
|
|
56
|
+
return {"name": user.get_full_name(), "avatar": user.profile.avatar_url, "url": f"/people/{user.pk}/"} if user else None
|
|
57
|
+
|
|
58
|
+
realtime = Realtime.from_environment(profile=profile)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
const users = await rt.users( [ 34, 42 ] ); // { 34: { user_id: 34, name: 'Ann', avatar: '…' }, 42: { … } }
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- **A user is in the directory** once they have connected: a page sends its user identity, signed by your server with their profile, and may then read those of others. Ask again when someone comes [online](presence.md#who-is-online-across-your-app) for a user not there yet.
|
|
66
|
+
- **The same profile** is what the ready-made parts and calls show of them, and the info of a presence member when the rule gives none.
|
|
67
|
+
|
|
68
|
+
## Your own sealed values
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
realtime.kind("note", lambda rest, user, label: user is not None and Note.objects.filter(pk=rest, readers=user).exists())
|
|
72
|
+
sealed = realtime.keys.seal_json(note_data, f"note:{note.pk}") # send it any way you like
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
import { keyring, labelOf } from '@wordplus/realtime';
|
|
77
|
+
|
|
78
|
+
await keyring().ensure( [ labelOf( sealed ) ] ); // asks your keys route for `note:…` if the page lacks it
|
|
79
|
+
const note = keyring().openJson( sealed ); // undefined when this user may not have it
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The key derivation, and every label: [encryption in depth](https://docs.wordplus.cloud/apps/encryption/).
|