Mercurial > libervia-backend
annotate doc/libervia-cli/notification.rst @ 4306:94e0968987cd
plugin XEP-0033: code modernisation, improve delivery, data validation:
- Code has been rewritten using Pydantic models and `async` coroutines for data validation
and cleaner element parsing/generation.
- Delivery has been completely rewritten. It now works even if server doesn't support
multicast, and send to local multicast service first. Delivering to local multicast
service first is due to bad support of XEP-0033 in server (notably Prosody which has an
incomplete implementation), and the current impossibility to detect if a sub-domain
service handles fully multicast or only for local domains. This is a workaround to have
a good balance between backward compatilibity and use of bandwith, and to make it work
with the incoming email gateway implementation (the gateway will only deliver to
entities of its own domain).
- disco feature checking now uses `async` corountines. `host` implementation still use
Deferred return values for compatibility with legacy code.
rel 450
author | Goffi <goffi@goffi.org> |
---|---|
date | Thu, 26 Sep 2024 16:12:01 +0200 |
parents | 646b328b3980 |
children |
rev | line source |
---|---|
4135
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
1 .. _libervia-cli_notification: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
2 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
3 ==================================== |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
4 notification: notifications handling |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
5 ==================================== |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
6 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
7 Notifications can be retrieved, expired or created with the ``notification`` commands. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
8 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
9 add |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
10 ==== |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
11 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
12 Add and broadcast a new notification. Only admin profiles can add a notification. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
13 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
14 It can be used for service announcement, such as planned maintenance. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
15 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
16 To make an announcement to all profiles, use the ``-g, --is-global``. Note that such |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
17 global notification aren't deleted when using :ref:`libervia-cli_notification_expire` |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
18 command: you have either to use ``-e EXPIRE_AT, --expire-at EXPIRE_AT`` to |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
19 set an expiration date, or to delete them manually with |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
20 :ref:`libervia-cli_notification_delete`. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
21 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
22 example |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
23 ------- |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
24 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
25 Add a global service announcement to indicate that the server will be shut down. The |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
26 expiration date is set so that the notification will be expired after expected end of |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
27 maintenance:: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
28 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
29 $ li notification add service "Server will be shut down for maintenance." -P HIGH -g -e "2023-10-22" |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
30 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
31 get |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
32 === |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
33 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
34 Retrieve notification for current profile. If ``-f, --follow`` argument is used, the CLI |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
35 will continue to run and show any new incoming notification. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
36 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
37 examples |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
38 -------- |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
39 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
40 Louise wishes to obtain her current notifications and display any new notifications as |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
41 they are issued:: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
42 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
43 $ li notification get -f |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
44 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
45 Louise wants to see all her chat notifications which are at least of high priority (this |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
46 includes urgent ones):: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
47 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
48 $ li notification get -t chat -P HIGH |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
49 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
50 .. _libervia-cli_notification_delete: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
51 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
52 delete |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
53 ====== |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
54 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
55 Delete a notification by its ID. The notification must belong to the profile doing the |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
56 request. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
57 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
58 If ``-g, --is-global`` is used, a global notification is to be deleted. Only admins can |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
59 delete a global notification. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
60 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
61 example |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
62 ------- |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
63 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
64 Louise (who is an admin) wants to delete a previous global service announcement with ID ``123``:: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
65 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
66 $ li notification delete -g 123 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
67 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
68 .. _libervia-cli_notification_expire: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
69 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
70 expire |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
71 ======= |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
72 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
73 Delete expired notification (the ones with an expiration date set). |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
74 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
75 If ``-l TIME_PATTERN, --limit TIME_PATTERN`` is used, also delete notification which have |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
76 been **created** before the given limit. Some notifications can't be deleted this way: if |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
77 they are global, or if they require a user action. Using ``now`` as time pattern will |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
78 clear all the notifications that can be deleted. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
79 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
80 By default, only notifications of requesting profile are deleted (except for expired ones |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
81 which are always deleted). If ``-a, --all`` is used, notification for all profiles can be |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
82 deleted. This option is notably useful to schedule automatic notification cleaning. |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
83 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
84 example |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
85 ------- |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
86 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
87 Louise want to expire notification for all profiles that are older than 7 days:: |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
88 |
646b328b3980
doc (cli): `notification` commands documentation.
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
89 $ li notification expire -a -l "7 days ago" |