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.
Files changed (122) hide show
  1. wordplus_realtime-1.0.0/.gitattributes +3 -0
  2. wordplus_realtime-1.0.0/.github/workflows/release.yml +40 -0
  3. wordplus_realtime-1.0.0/.gitignore +6 -0
  4. wordplus_realtime-1.0.0/LICENSE +21 -0
  5. wordplus_realtime-1.0.0/PKG-INFO +133 -0
  6. wordplus_realtime-1.0.0/README.md +97 -0
  7. wordplus_realtime-1.0.0/docs/django/calls.md +115 -0
  8. wordplus_realtime-1.0.0/docs/django/customizing.md +71 -0
  9. wordplus_realtime-1.0.0/docs/django/deploying.md +41 -0
  10. wordplus_realtime-1.0.0/docs/django/encryption.md +82 -0
  11. wordplus_realtime-1.0.0/docs/django/events.md +135 -0
  12. wordplus_realtime-1.0.0/docs/django/example.md +43 -0
  13. wordplus_realtime-1.0.0/docs/django/getting-started.md +141 -0
  14. wordplus_realtime-1.0.0/docs/django/presence.md +89 -0
  15. wordplus_realtime-1.0.0/docs/django/rooms.md +80 -0
  16. wordplus_realtime-1.0.0/docs/django/sending.md +103 -0
  17. wordplus_realtime-1.0.0/docs/django/streams.md +70 -0
  18. wordplus_realtime-1.0.0/docs/fastapi/calls.md +115 -0
  19. wordplus_realtime-1.0.0/docs/fastapi/customizing.md +71 -0
  20. wordplus_realtime-1.0.0/docs/fastapi/deploying.md +49 -0
  21. wordplus_realtime-1.0.0/docs/fastapi/encryption.md +84 -0
  22. wordplus_realtime-1.0.0/docs/fastapi/events.md +99 -0
  23. wordplus_realtime-1.0.0/docs/fastapi/example.md +37 -0
  24. wordplus_realtime-1.0.0/docs/fastapi/getting-started.md +126 -0
  25. wordplus_realtime-1.0.0/docs/fastapi/presence.md +89 -0
  26. wordplus_realtime-1.0.0/docs/fastapi/rooms.md +80 -0
  27. wordplus_realtime-1.0.0/docs/fastapi/sending.md +103 -0
  28. wordplus_realtime-1.0.0/docs/fastapi/streams.md +70 -0
  29. wordplus_realtime-1.0.0/docs/flask/calls.md +115 -0
  30. wordplus_realtime-1.0.0/docs/flask/customizing.md +71 -0
  31. wordplus_realtime-1.0.0/docs/flask/deploying.md +41 -0
  32. wordplus_realtime-1.0.0/docs/flask/encryption.md +84 -0
  33. wordplus_realtime-1.0.0/docs/flask/events.md +99 -0
  34. wordplus_realtime-1.0.0/docs/flask/example.md +37 -0
  35. wordplus_realtime-1.0.0/docs/flask/getting-started.md +114 -0
  36. wordplus_realtime-1.0.0/docs/flask/presence.md +89 -0
  37. wordplus_realtime-1.0.0/docs/flask/rooms.md +80 -0
  38. wordplus_realtime-1.0.0/docs/flask/sending.md +103 -0
  39. wordplus_realtime-1.0.0/docs/flask/streams.md +70 -0
  40. wordplus_realtime-1.0.0/docs/reference.md +107 -0
  41. wordplus_realtime-1.0.0/examples/django/.env.example +5 -0
  42. wordplus_realtime-1.0.0/examples/django/.gitignore +6 -0
  43. wordplus_realtime-1.0.0/examples/django/README.md +20 -0
  44. wordplus_realtime-1.0.0/examples/django/config/__init__.py +0 -0
  45. wordplus_realtime-1.0.0/examples/django/config/settings.py +67 -0
  46. wordplus_realtime-1.0.0/examples/django/config/urls.py +19 -0
  47. wordplus_realtime-1.0.0/examples/django/config/wsgi.py +6 -0
  48. wordplus_realtime-1.0.0/examples/django/demo.py +106 -0
  49. wordplus_realtime-1.0.0/examples/django/manage.py +10 -0
  50. wordplus_realtime-1.0.0/examples/django/requirements.txt +2 -0
  51. wordplus_realtime-1.0.0/examples/django/shop/avatars/ann.svg +1 -0
  52. wordplus_realtime-1.0.0/examples/django/shop/avatars/ben.svg +1 -0
  53. wordplus_realtime-1.0.0/examples/django/shop/avatars/cara.svg +1 -0
  54. wordplus_realtime-1.0.0/examples/django/shop/products/mugs.webp +0 -0
  55. wordplus_realtime-1.0.0/examples/django/shop/shop.css +719 -0
  56. wordplus_realtime-1.0.0/examples/django/shop/shop.js +572 -0
  57. wordplus_realtime-1.0.0/examples/django/store/__init__.py +0 -0
  58. wordplus_realtime-1.0.0/examples/django/store/apps.py +5 -0
  59. wordplus_realtime-1.0.0/examples/django/store/migrations/0001_initial.py +43 -0
  60. wordplus_realtime-1.0.0/examples/django/store/migrations/0002_shop_data.py +25 -0
  61. wordplus_realtime-1.0.0/examples/django/store/migrations/0003_kept_chat.py +29 -0
  62. wordplus_realtime-1.0.0/examples/django/store/migrations/__init__.py +0 -0
  63. wordplus_realtime-1.0.0/examples/django/store/models.py +50 -0
  64. wordplus_realtime-1.0.0/examples/django/store/realtime.py +152 -0
  65. wordplus_realtime-1.0.0/examples/django/store/shops.py +65 -0
  66. wordplus_realtime-1.0.0/examples/django/store/templates/store/login.html +21 -0
  67. wordplus_realtime-1.0.0/examples/django/store/templates/store/page.html +26 -0
  68. wordplus_realtime-1.0.0/examples/django/store/views.py +140 -0
  69. wordplus_realtime-1.0.0/examples/fastapi/.env.example +5 -0
  70. wordplus_realtime-1.0.0/examples/fastapi/.gitignore +4 -0
  71. wordplus_realtime-1.0.0/examples/fastapi/README.md +15 -0
  72. wordplus_realtime-1.0.0/examples/fastapi/app.py +367 -0
  73. wordplus_realtime-1.0.0/examples/fastapi/demo.py +106 -0
  74. wordplus_realtime-1.0.0/examples/fastapi/requirements.txt +6 -0
  75. wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/ann.svg +1 -0
  76. wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/ben.svg +1 -0
  77. wordplus_realtime-1.0.0/examples/fastapi/shop/avatars/cara.svg +1 -0
  78. wordplus_realtime-1.0.0/examples/fastapi/shop/products/mugs.webp +0 -0
  79. wordplus_realtime-1.0.0/examples/fastapi/shop/shop.css +719 -0
  80. wordplus_realtime-1.0.0/examples/fastapi/shop/shop.js +572 -0
  81. wordplus_realtime-1.0.0/examples/fastapi/templates/login.html +20 -0
  82. wordplus_realtime-1.0.0/examples/fastapi/templates/page.html +24 -0
  83. wordplus_realtime-1.0.0/examples/flask/.env.example +5 -0
  84. wordplus_realtime-1.0.0/examples/flask/.gitignore +4 -0
  85. wordplus_realtime-1.0.0/examples/flask/README.md +15 -0
  86. wordplus_realtime-1.0.0/examples/flask/app.py +359 -0
  87. wordplus_realtime-1.0.0/examples/flask/demo.py +106 -0
  88. wordplus_realtime-1.0.0/examples/flask/requirements.txt +2 -0
  89. wordplus_realtime-1.0.0/examples/flask/shop/avatars/ann.svg +1 -0
  90. wordplus_realtime-1.0.0/examples/flask/shop/avatars/ben.svg +1 -0
  91. wordplus_realtime-1.0.0/examples/flask/shop/avatars/cara.svg +1 -0
  92. wordplus_realtime-1.0.0/examples/flask/shop/products/mugs.webp +0 -0
  93. wordplus_realtime-1.0.0/examples/flask/shop/shop.css +719 -0
  94. wordplus_realtime-1.0.0/examples/flask/shop/shop.js +572 -0
  95. wordplus_realtime-1.0.0/examples/flask/templates/login.html +20 -0
  96. wordplus_realtime-1.0.0/examples/flask/templates/page.html +24 -0
  97. wordplus_realtime-1.0.0/pyproject.toml +47 -0
  98. wordplus_realtime-1.0.0/spec/stream-grants.json +110 -0
  99. wordplus_realtime-1.0.0/spec/vectors.json +106 -0
  100. wordplus_realtime-1.0.0/src/wordplus_realtime/__init__.py +40 -0
  101. wordplus_realtime-1.0.0/src/wordplus_realtime/django/__init__.py +185 -0
  102. wordplus_realtime-1.0.0/src/wordplus_realtime/django/apps.py +9 -0
  103. wordplus_realtime-1.0.0/src/wordplus_realtime/django/routes.py +6 -0
  104. wordplus_realtime-1.0.0/src/wordplus_realtime/django/templatetags/__init__.py +0 -0
  105. wordplus_realtime-1.0.0/src/wordplus_realtime/django/templatetags/wordplus_realtime.py +24 -0
  106. wordplus_realtime-1.0.0/src/wordplus_realtime/fastapi.py +84 -0
  107. wordplus_realtime-1.0.0/src/wordplus_realtime/files/THIRD-PARTY-NOTICES.txt +1116 -0
  108. wordplus_realtime-1.0.0/src/wordplus_realtime/files/files.json +11 -0
  109. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-rooms-e2ee.worker.js +3 -0
  110. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-rooms.min.js +3 -0
  111. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui-streams.min.js +3502 -0
  112. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui.THIRD-PARTY-NOTICES.txt +1072 -0
  113. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-ui.min.js +6053 -0
  114. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime-worker.js +2 -0
  115. wordplus_realtime-1.0.0/src/wordplus_realtime/files/realtime.js +5 -0
  116. wordplus_realtime-1.0.0/src/wordplus_realtime/flask.py +81 -0
  117. wordplus_realtime-1.0.0/src/wordplus_realtime/keys.py +234 -0
  118. wordplus_realtime-1.0.0/src/wordplus_realtime/patterns.py +76 -0
  119. wordplus_realtime-1.0.0/src/wordplus_realtime/realtime.py +1597 -0
  120. wordplus_realtime-1.0.0/tests/test_docs.py +32 -0
  121. wordplus_realtime-1.0.0/tests/test_frameworks.py +349 -0
  122. wordplus_realtime-1.0.0/tests/test_realtime.py +879 -0
@@ -0,0 +1,3 @@
1
+ # The release's own files, kept out of its zips.
2
+ /.github export-ignore
3
+ /.gitattributes export-ignore
@@ -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,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ dist/
6
+ *.egg-info/
@@ -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
+ ![Ben has pressed a video call button: his browser shows the call window calling Ann, over his own camera, and the browser of Ann rings, with buttons to answer and decline](https://docs.wordplus.cloud/img/apps/calls-ringing.webp)
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
+ ![Ann has answered: each browser shows the other person camera, their own in a corner, and the call controls. The cameras are illustrations](https://docs.wordplus.cloud/img/apps/calls-connected.webp)
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
+ ![Ann, Ben and Cara in one group call from three browsers, with the call screen grid: each sees the other two and their own camera, then the call controls. The cameras are illustrations](https://docs.wordplus.cloud/img/apps/rooms-meeting.webp)
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
+ ![On the left, what WordPlus Cloud carried of the update of an order, as the page of Ann shows it: the room and the event name in plain text, its data a sealed string, then what her page opened. On the right, the browser of Ben, which opened it too, showing his order as delivered](https://docs.wordplus.cloud/img/apps/encryption-sealed.webp)
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/).