message_retention_policies.md

Message retention policies

Synapse admins can enable support for message retention policies on their homeserver. Message retention policies exist at a room level, follow the semantics described in MSC1763, and allow server and room admins to configure how long messages should be kept in a homeserver's database before being purged from it. Please note that, as this feature isn't part of the Matrix specification yet, this implementation is to be considered as experimental.

A message retention policy is mainly defined by its max_lifetime parameter, which defines how long a message can be kept around after it was sent to the room. If a room doesn't have a message retention policy, and there's no default one for a given server, then no message sent in that room is ever purged on that server.

MSC1763 also specifies semantics for a min_lifetime parameter which defines the amount of time after which an event can get purged (after it was sent to the room), but Synapse doesn't currently support it beyond registering it.

Both max_lifetime and min_lifetime are optional parameters.

Note that message retention policies don't apply to state events.

Once an event reaches its expiry date (defined as the time it was sent plus the value for max_lifetime in the room), two things happen:

• Synapse stops serving the event to clients via any endpoint.
• The message gets picked up by the next purge job (see the "Purge jobs" section) and is removed from Synapse's database.

Since purge jobs don't run continuously, this means that an event might stay in a server's database for longer than the value for max_lifetime in the room would allow, though hidden from clients.

Similarly, if a server (with support for message retention policies enabled) receives from another server an event that should have been purged according to its room's policy, then the receiving server will process and store that event until it's picked up by the next purge job, though it will always hide it from clients.

Synapse requires at least one message in each room, so it will never delete the last message in a room. It will, however, hide it from clients.

Server configuration

Support for this feature can be enabled and configured in the retention section of the Synapse configuration file (see the sample file).

To enable support for message retention policies, set the setting enabled in this section to true.

Default policy

A default message retention policy is a policy defined in Synapse's configuration that is used by Synapse for every room that doesn't have a message retention policy configured in its state. This allows server admins to ensure that messages are never kept indefinitely in a server's database.

A default policy can be defined as such, in the retention section of the configuration file:

  default_policy:
    min_lifetime: 1d
    max_lifetime: 1y

Here, min_lifetime and max_lifetime have the same meaning and level of support as previously described. They can be expressed either as a duration (using the units s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years)) or as a number of milliseconds.

Purge jobs