annotate mod_smacks/README.markdown @ 2953:0092bcceda0a

mod_component_http: Update README to include config snippet example
author Matthew Wild <mwild1@gmail.com>
date Mon, 26 Mar 2018 14:01:00 +0100
parents ffb6646b4253
children 0957ba6aeb99
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
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
30 If the client fails to reconnect before the timeout then it is marked
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
31 offline as normal, and any stanzas in the queue are returned to the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
32 sender as a "recipient-unavailable" error.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33
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
34 If you don't want this behaviour on timeout you can use [mod_smacks_offline]
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
35 or [mod_smacks_noerror] to customize the behaviour further.
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
36
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
37 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
38 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
39 "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
40 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
41
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
42 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
43 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
44 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
45 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
46
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
47 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
48 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49
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
50 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
51 ---------------------------------- ----------------- ------------------------------------------------------------------------------------------------------------------
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 `smacks_hibernation_time` 300 (5 minutes) The number of seconds a disconnected session should stay alive for (to allow reconnect)
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 `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
54 `smacks_max_unacked_stanzas` 0 How many stanzas to send before requesting acknowledgement
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
55 `smacks_max_ack_delay` 60 (1 minute) The number of seconds an ack must be unanswered to trigger an "smacks-ack-delayed" event
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 `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
57 `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
58
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
59 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
60 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61
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 ----- -----------------------------------------------------------------------------
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
63 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
64 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
65 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
66 ----- -----------------------------------------------------------------------------
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
67
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
69 Clients
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
70 =======
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
71
2503
7036a6e074d7 mod_smacks/README: Linkify the XEP
Kim Alvefur <zash@zash.se>
parents: 2394
diff changeset
72 Clients that support [XEP-0198]:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
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
74 - 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
75 - 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
76 - ChatSecure (iOS)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
77 - 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
78 - 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
79 - 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
80 - Monal (iOS)
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
81
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
82 [7693724881b3]: //hg.prosody.im/prosody-modules/raw-file/7693724881b3/mod_smacks/mod_smacks.lua
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
83 [mod_smacks_offline]: //modules.prosody.im/mod_smacks_offline
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
84 [mod_smacks_noerror]: //modules.prosody.im/mod_smacks_noerror
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
85 [mod_cloud_notify]: //modules.prosody.im/mod_cloud_notify