mod_stream_management

Module Description

Enables XEP-0198: Stream Management. Implements logic regarding session resumption and acknowledgement as well as the management of the session tables and configuration.

Options

modules.mod_stream_management.backend

• Syntax: string: "mnesia" or "cets"
• Default: "mnesia"
• Example: backend = "mnesia"

Backend for in-memory session data stored by this module.

Warning

The corresponding internal database has to be enabled.

modules.mod_stream_management.buffer

• Syntax: boolean
• Default: true
• Example: buffer = false

Enables buffer for messages to be acknowledged.

modules.mod_stream_management.buffer_max

• Syntax: positive integer or string "infinity"
• Default: 100
• Example: buffer_max = 500

Buffer size for messages yet to be acknowledged.

modules.mod_stream_management.ack

• Syntax: boolean
• Default: true
• Example: ack = false

Enables ack requests to be sent from the server to the client.

modules.mod_stream_management.ack_freq

• Syntax: positive integer
• Default: 1
• Example: ack_freq = 3

Frequency of ack requests sent from the server to the client, e.g. 1 means a request after each stanza, 3 means a request after each 3 stanzas.

modules.mod_stream_management.resume_timeout

• Syntax: positive integer, value given in seconds
• Default: 600
• Example: resume_timeout = 600

Timeout for the session resumption. Sessions will be removed after the specified number of seconds.

Stale_h options

Enables keeping old server's <h> values after the resumption timed out. Disabled by default. When enabled, parameters for the garbage collection of these tables should be provided.

modules.mod_stream_management.stale_h.enabled

• Syntax: boolean
• Default: false
• Example: enabled = true

Enables stale_h configuration

modules.mod_stream_management.stale_h.repeat_after

• Syntax: positive integer, value given in seconds
• Default: 1800 (half an hour)
• Example: repeat_after = 1800

How often the garbage collection will run in the background to clean this table.

modules.mod_stream_management.stale_h.geriatric

• Syntax: positive integer, value given in seconds
• Default: 3600 (one hour)
• Example: geriatric = 3600

The maximum lifespan of a record in memory. After this, they will be chased for cleanup.

Example Configuration

[modules.mod_stream_management]
  buffer_max = 30
  ack_freq = 1
  resume_timeout = 600
  stale_h.enabled = true
  stale_h.repeat_after = 1800
  stale_h.geriatric = 3600

Implementation details

Stream management state data is stored under the mod_stream_management key in the #c2s_data.state_mod map. The state data record, sm_state, has the following fields:

• buffer - buffered stanzas not yet acked by the user
• buffer_size - number of stanzas buffered for the user
• counter_in - number of stanzas received by the server (server's <h>)
• counter_out - number of stanzas delivered to the user and acked by the user (user's <h>)
• buffer_max - server's capacity for buffering
• ack_freq - how often the server requests acks
• peer - in case of stream resumption, the ejabberd_sm:sid() identifiying the old session, or gen_statem:from() identifying the new session.

mod_stream_management introduces a new resume_session state to the C2S state machine, that is used by a session being closed to allow stream resumption.

This module also has a Mnesia backend keeping a table defined as follows:

-record(sm_session,
        {smid :: smid(),
         sid :: ejabberd_sm:sid()
        }).

where smid is a unique identifier — in this case a random binary, and sid is an opaque session identifier from ejabberd_sm, which is needed to find the previous session we want to resume from. This module implements hooks that run on connection removals and session cleanups, in order to clean records from a dying session; and it also implements registration callbacks, used when a session is registered for resumption.

XEP version 1.6 requires the server to attempt giving the user the value of the server's <h> when a session timed out and cannot be resumed anymore. To be compliant with it, there's a second optional table:

-record(stream_mgmt_stale_h,
        {smid :: smid(),
         h :: non_neg_integer(),
         stamp :: non_neg_integer()
        }).

This table is created, together with a gen_server responsible for cleaning up the tables, when stale_h is set to true with the proper garbage collection configuration. Then, when removing a record from the sm_session table (which happens when the state of the previous session is also dropped), a new record is added to this new table with the smid and h values of the dropped session, together with a timestamp. Next, when a new session attempting resumption queries mod_stream_management for the data behind a smid, mod_stream_management can answer with one of the following:

{sid, ejabberd_sm:sid()} | {stale_h, non_neg_integer()} | {error, smid_not_found}.

And mod_stream_management will pattern-match and act accordingly.