Prosody IM Website


file doc/modules/mod_csi_simple.md in changeset 3fde10589ec3

View latest ↓ Download file

line wrap: on
line source

---
title: 'mod\_csi\_simple'
subtitle: Client State Indication
abstract: Battery friendly traffic optimizations for inactive clients
---

This module enables simple traffic optimisation for clients that have
reported themselves as inactive to [mod\_csi](/doc/modules/mod_csi).

This module automatically loads mod\_csi.

# How it works

The module works by buffering unimportant traffic to inactive devices,
such as contact status changes. The data is released when any important
data comes in (such as a message from a contact), or when the queue size
is reached.

Stanzas currently classified as important are:

-   `presence` stanzas other than status changes, i.e. subscription
    requests.
-   `message` stanza that...
    -   are outgoing [carbon-copied](/doc/modules/mod_carbons) messages
        sent by the user.
    -   includes a textual message.
    -   changes the subject / topic in group chats.
    -   are [explicitly marked as end-to-end
        encrypted](https://xmpp.org/extensions/xep-0380.html "XEP-0380: Explicit Message Encryption").
    -   contains any payload included in the `csi_important_payloads`
        setting
-   Any `iq` stanzas.

The decision can be further influenced by other modules.

# Configuration

  option                       type   default
  -------------------------- -------- ---------
  `csi_queue_size`            number  256
  `csi_important_payloads`     set    empty

`csi_queue_size` controls how many stanzas are buffered before sending
them all at once. Higher values lets clients conserve bandwidth and
power for longer periods, at the cost of memory usage for the server and
the risk that the clients connection times out.

`csi_important_payloads` (added in 0.12) allows specifying additional
message payloads to consider as indicators of an important stanza. This
lets you teach Prosody about new or custom protocols.

``` {.lua}
csi_important_payloads = {
    -- Anything in this namespace:
    "{urn:example:important-namespace}",
    -- Specific element name and namespace:
    "{urn:example:xmpp:priority}super-important",
}
```

# History

This module was first added in 0.11.x. It came from the community module
`mod_csi_pump`.

In trunk it will also flush the queue when incoming traffic from clients
is received, since its radio would be active already.