Mercurial > prosody-modules

annotate mod_smacks/README.markdown @ 4646:072d078be095

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_storage_xmlarchive: Advertise capabilities (none atm) Both 'total' and 'quota' would be prohibitively expensive for the kind of archives this module targets as it would require counting items across the entire archive.
author Kim Alvefur <zash@zash.se>
date Fri, 13 Aug 2021 01:18:32 +0200
parents 0957ba6aeb99
children 0bcbff950f14
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
2154
ada71b81425a mod_smacks/README: Too buggy for a "Beta" label
Kim Alvefur <zash@zash.se>
parents: 2063
diff changeset
3 - 'Stage-Alpha'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 summary: 'XEP-0198: Reliability and fast reconnects for XMPP'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
5 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
10 By default XMPP is as reliable as your network is. Unfortunately in some
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
11 cases that is not very reliable - in some network conditions disconnects
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 can be frequent and message loss can occur.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
14 To overcome this, XMPP has an optional extension (XEP-0198: Stream
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 Management) which, when supported by both the client and server, can
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
16 allow a client to resume a disconnected session, and prevent message
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
17 loss.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
19 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 When using XEP-0198 both the client and the server keep a queue of the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 most recently sent stanzas - this is cleared when the other end
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 acknowledges they have received the stanzas. If the client disconnects,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
25 instead of marking the user offline the server pretends the client is
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
26 still online for a short (configurable) period of time. If the client
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
27 reconnects within this period, any stanzas in the queue that the client
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
28 did not receive are re-sent.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
30 If the client fails to reconnect before the timeout it will be marked as
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
31 offline like prosody does on disconnect without mod_smacks.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
32 If the client is the last one for this jid, all message stanzas are added to
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
33 the offline store and all other stanzas stanzas are returned with an
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
34 "recipient-unavailable" error. If the client is not the last one with an
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
35 open smacks session, *all* stanzas are returned with an "recipient-unavailable" error.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
36
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
37 If you deliberately disabled [mod_offline], all message stanzas of the last client
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
38 are also returned with an "recipient-unavailable" error, because the can not be
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
39 added to the offline storage.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
40 If you don't want this behaviour you can use [mod_nooffline_noerror] to suppress the error.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
41 This is generally only advisable, if you are sure that all your clients are using MAM!
2394
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
42
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
43 This module also provides some events used by [mod_cloud_notify].
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
44 These events are: "smacks-ack-delayed", "smacks-hibernation-start" and
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
45 "smacks-hibernation-end". See [mod_cloud_notify] for details on how this
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
46 events are used there.
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
47
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
48 Use prosody 0.10+ to have per user limits on allowed sessions in hibernation
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
49 state and allowed sessions for which the h-value is kept even after the
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
50 hibernation timed out.
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
51 These are settable using `smacks_max_hibernated_sessions` and `smacks_max_old_sessions`.
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
52
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
53 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
54 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
56 Option Default Description
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
57 ---------------------------------- ----------------- ------------------------------------------------------------------------------------------------------------------
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
58 `smacks_hibernation_time` 600 (10 minutes) The number of seconds a disconnected session should stay alive for (to allow reconnect)
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
59 `smacks_enabled_s2s` false Enable Stream Management on server connections? *Experimental*
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
60 `smacks_max_unacked_stanzas` 0 How many stanzas to send before requesting acknowledgement
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
61 `smacks_max_ack_delay` 30 (1/2 minute) The number of seconds an ack must be unanswered to trigger an "smacks-ack-delayed" event
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
62 `smacks_max_hibernated_sessions` 10 The number of allowed sessions in hibernated state (limited per user)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
63 `smacks_max_old_sessions` 10 The number of allowed sessions with timed out hibernation for which the h-value is still kept (limited per user)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
64
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
65 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
66 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
68 ----- -----------------------------------------------------------------------------
2394
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
69 0.10 Works
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
70 0.9 Works, no per user limit of hibernated sessions
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
71 0.8 Works, no per user limit of hibernated sessions, use version [7693724881b3]
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
72 ----- -----------------------------------------------------------------------------
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
73
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
75 Clients
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
76 =======
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
77
2503
7036a6e074d7 mod_smacks/README: Linkify the XEP
Kim Alvefur <zash@zash.se>
parents: 2394
diff changeset
78 Clients that support [XEP-0198]:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
80 - Gajim (Linux, Windows, OS X)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
81 - Conversations (Android)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
82 - ChatSecure (iOS)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
83 - Swift (but not resumption, as of version 2.0 and alphas of 3.0)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
84 - Psi (in an unreleased branch)
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
85 - Yaxim (Android)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
86 - Monal (iOS)
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
87
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
88 [7693724881b3]: //hg.prosody.im/prosody-modules/raw-file/7693724881b3/mod_smacks/mod_smacks.lua
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
89 [mod_offline]: //modules.prosody.im/mod_offline
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
90 [mod_nooffline_noerror]: //modules.prosody.im/mod_nooffline_noerror
2394
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
91 [mod_cloud_notify]: //modules.prosody.im/mod_cloud_notify