prosody-modules
5a65a632d5b9
mod_smacks/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_smacks/README.md @ 6002:5a65a632d5b9

mod_smacks: fix small copy error
author Menel <menel@snikket.de>
date Mon, 21 Oct 2024 22:09:46 +0200
parent 6001:0afd0adbe050
child 6025:a5fff4995862
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 ---
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
2 summary: 'XEP-0198: Reliability and fast reconnects for XMPP'
6002
5a65a632d5b9 mod_smacks: fix small copy error
Menel <menel@snikket.de>
parents: 6001
diff changeset
3 superseded_by: mod_smacks
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 labels:
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
5 - 'Stage-Obsolete'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
6 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
8 Since Prosody 0.12, this module is [included in Prosody](https://prosody.im/doc/modules/mod_smacks).
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
9
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
10 #Introduction
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 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
13 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
14 can be frequent and message loss can occur.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
16 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
17 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
18 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
19 loss.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
21 #Details
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 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
24 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
25 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
26 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
27 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
28 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
29 did not receive are re-sent.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
31 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
32 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
33 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
34 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
35 "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
36 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
37
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
38 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
39 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
40 added to the offline storage.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
41 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
42 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
43
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 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
45 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
46 "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
47 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
48
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
49 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
50 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
51 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
52 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
53
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
54 #Configuration
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)
4678
0bcbff950f14 mod_smacks: Update README
Martin Dosch <martin@mdosch.de>
parents: 3967
diff changeset
59 `smacks_enabled_s2s` true Enable Stream Management on server connections? *Experimental*
4721
2db804a1c9f0 mod_smacks: Add smacks_s2s_resend to configuration listing
Kim Alvefur <zash@zash.se>
parents: 4678
diff changeset
60 `smacks_s2s_resend` false Attempt to re-send unacked messages on s2s disconnect *Experimental*
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
61 `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
62 `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
63 `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
64 `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
65
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
66 #Compatibility
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67
4722
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
68 ------- -------
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
69 trunk Works
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
70 0.11 Works
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
71 ------- -------
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
72
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
6001
0afd0adbe050 Update mod_smacks status to obsolete - included in prosody
Menel <menel@snikket.de>
parents: 4722
diff changeset
74 #Clients
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
75
2503
7036a6e074d7 mod_smacks/README: Linkify the XEP
Kim Alvefur <zash@zash.se>
parents: 2394
diff changeset
76 Clients that support [XEP-0198]:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77
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
78 - 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
79 - 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
80 - ChatSecure (iOS)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
81 - 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
82 - 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
83 - 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
84 - Monal (iOS)
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
85
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
86 [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
87 [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
88 [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
89 [mod_cloud_notify]: //modules.prosody.im/mod_cloud_notify