prosody-modules
1a6cd0bbb7ab
mod_cloud_notify/README.md

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

Software / code / prosody-modules

File

mod_cloud_notify/README.md @ 6110:1a6cd0bbb7ab

mod_compliance_2023: Add 2023 Version of the compliance module, basis is the 2021 Version. diff --git a/mod_compliance_2023/README.md b/mod_compliance_2023/README.md new file mode 100644 --- /dev/null +++ b/mod_compliance_2023/README.md @@ -0,0 +1,22 @@ +--- +summary: XMPP Compliance Suites 2023 self-test +labels: +- Stage-Beta +rockspec: + dependencies: + - mod_cloud_notify + +... + +Compare the list of enabled modules with +[XEP-0479: XMPP Compliance Suites 2023] and produce basic report to the +Prosody log file. + +If installed with the Prosody plugin installer then all modules needed for a green checkmark should be included. (With prosody 0.12 only [mod_cloud_notify] is not included with prosody and we need the community module) + +# Compatibility + + Prosody-Version Status + --------------- ---------------------- + trunk Works as of 2024-12-21 + 0.12 Works diff --git a/mod_compliance_2023/mod_compliance_2023.lua b/mod_compliance_2023/mod_compliance_2023.lua new file mode 100644 --- /dev/null +++ b/mod_compliance_2023/mod_compliance_2023.lua @@ -0,0 +1,79 @@ +-- Copyright (c) 2021 Kim Alvefur +-- +-- This module is MIT licensed. + +local hostmanager = require "core.hostmanager"; + +local array = require "util.array"; +local set = require "util.set"; + +local modules_enabled = module:get_option_inherited_set("modules_enabled"); + +for host in pairs(hostmanager.get_children(module.host)) do + local component = module:context(host):get_option_string("component_module"); + if component then + modules_enabled:add(component); + modules_enabled:include(module:context(host):get_option_set("modules_enabled", {})); + end +end + +local function check(suggested, alternate, ...) + if set.intersection(modules_enabled, set.new({suggested; alternate; ...})):empty() then return suggested; end + return false; +end + +local compliance = { + array {"Server"; check("tls"); check("disco")}; + + array {"Advanced Server"; check("pep", "pep_simple")}; + + array {"Web"; check("bosh"); check("websocket")}; + + -- No Server requirements for Advanced Web + + array {"IM"; check("vcard_legacy", "vcard"); check("carbons"); check("http_file_share", "http_upload")}; + + array { + "Advanced IM"; + check("vcard_legacy", "vcard"); + check("blocklist"); + check("muc"); + check("private"); + check("smacks"); + check("mam"); + check("bookmarks"); + }; + + array {"Mobile"; check("smacks"); check("csi_simple", "csi_battery_saver")}; + + array {"Advanced Mobile"; check("cloud_notify")}; + + array {"A/V Calling"; check("turn_external", "external_services", "turncredentials", "extdisco")}; + +}; + +function check_compliance() + local compliant = true; + for _, suite in ipairs(compliance) do + local section = suite:pop(1); + if module:get_option_boolean("compliance_" .. section:lower():gsub("%A", "_"), true) then + local missing = set.new(suite:filter(function(m) return type(m) == "string" end):map(function(m) return "mod_" .. m end)); + if suite[1] then + if compliant then + compliant = false; + module:log("warn", "Missing some modules for XMPP Compliance 2023"); + end + module:log("info", "%s Compliance: %s", section, missing); + end + end + end + + if compliant then module:log("info", "XMPP Compliance 2023: Compliant ✔️"); end +end + +if prosody.start_time then + check_compliance() +else + module:hook_global("server-started", check_compliance); +end +
author Menel <menel@snikket.de>
date Sun, 22 Dec 2024 16:06:28 +0100
parent 6003:fe081789f7b5
line wrap: on
line source

---
labels:
- 'Stage-Beta'
summary: 'XEP-0357: Cloud push notifications'
---

Introduction
============

This module enables support for sending "push notifications" to clients that
need it, typically those running on certain mobile devices.

As well as this module, your client must support push notifications (the apps
that need it generally do, of course) and the app developer's push gateway
must be reachable from your Prosody server (this happens over a normal XMPP
server-to-server 's2s' connection).

Details
=======

Some platforms, notably Apple's iOS and many versions of Android, impose
limits that prevent applications from running or accessing the network in the
background. This makes it difficult or impossible for an XMPP application to
remain reliably connected to a server to receive messages.

In order for messaging and other apps to receive notifications, the OS vendors
run proprietary servers that their OS maintains a permanent connection to in
the background. Then they provide APIs to application developers that allow
sending notifications to specific devices via those servers.

When you connect to your server with an app that requires push notifications,
it will use this module to set up a "push registration". When you receive
a message but your device is not connected to the server, this module will
generate a notification and send it to the push gateway operated by your
application's developers). Their gateway will then connect to your device's
OS vendor and ask them to forward the notification to your device. When your
device receives the notification, it will display it or wake up the app so it
can connect to XMPP and receive any pending messages.

This protocol is described for developers in [XEP-0357: Push Notifications].

For this module to work reliably, you must have [mod_smacks], [mod_mam] and
[mod_carbons] also enabled on your server.

Some clients, notably Siskin and Snikket iOS need some additional extensions
that are not currently defined in a standard XEP. To support these clients,
see [mod_cloud_notify_extensions].

Configuration
=============

  Option                               Default           Description
  ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
  `push_notification_important_body`   `New Message!`    The body text to use when the stanza is important (see above), no message body is sent if this is empty
  `push_max_errors`                    `16`              How much persistent push errors are tolerated before notifications for the identifier in question are disabled
  `push_max_devices`                   `5`               The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
  `push_max_hibernation_timeout`       `259200` (72h)    Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours)
  `push_notification_with_body` (\*)   `false`           Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended.
  `push_notification_with_sender` (\*) `false`           Whether or not to send the real message sender to remote pubsub node.  Enabling this may expose your contacts to your client developers and OS vendor. Not recommended.

(\*) There are privacy implications for enabling these options.

Internal design notes
=====================

App servers are notified about offline messages, messages stored by [mod_mam]
or messages waiting in the smacks queue.
The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2].

To cooperate with [mod_smacks] this module consumes some events:
`smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`.
These events allow this module to send out notifications for messages received
while the session is hibernated by [mod_smacks] or even when smacks
acknowledgements for messages are delayed by a certain amount of seconds
configurable with the [mod_smacks] setting `smacks_max_ack_delay`.

The `smacks_max_ack_delay` setting allows to send out notifications to clients
which aren't already in smacks hibernation state (because the read timeout or
connection close didn't already happen) but also aren't responding to acknowledgement
request in a timely manner. This setting thus allows conversations to be smoother
under such circumstances.

The new event `cloud-notify-ping` can be used by any module to send out a cloud
notification to either all registered endpoints for the given user or only the endpoints
given in the event data.

The config setting `push_notification_important_body` can be used to specify an alternative
body text to send to the remote pubsub node if the stanza is encrypted or has a body.
This way the real contents of the message aren't revealed to the push appserver but it
can still see that the push is important.
This is used by Chatsecure on iOS to send out high priority pushes in those cases for example.

Compatibility
=============

**Note:** This module should be used with Lua 5.2 and higher. Using it with
Lua 5.1 may cause push notifications to not be sent to some clients.

------ -----------------------------------------------------------------------------
  trunk  Works
  0.12   Works
  0.11   Works
  0.10   Works
  0.9    Support dropped, use last supported version [675726ab06d3](//hg.prosody.im/prosody-modules/raw-file/675726ab06d3/mod_cloud_notify/mod_cloud_notify.lua)
------ -----------------------------------------------------------------------------


[^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service
[^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown)