* Explains both push mechanisms
* Add graphics and update excalidraw
* Smaller changes and fixes

@@ -18,5 +18,10 @@
         "type": "file",
         "name": "oidc",
         "label": "Delegated authentication"
+    },

@@ -0,0 +55,4 @@
+## Correct output: {"unifiedpush":{"gateway":"matrix"}}
+```
+
+Continuwuity is working on a Web Push implementation following the works of [MSC4174]. This push method allows sending end-to-end-encrypted payloads directly towards the push provider, bypassing the need for a push gateway. Developments of this feature can be tracked in [#2122][pr-2122].

@@ -0,0 +62,4 @@
+
+## UnifiedPush
+
+[UnifiedPush][unifiedpush] is a common, open notifications system supported by many Matrix clients on Android. Using the same push gateway mechanism as other push services, it requires no additional support from the homeserver side. Below are notes for some known UnifiedPush distributors.

@@ -0,0 +65,4 @@
+[UnifiedPush][unifiedpush] is a common, open notifications system supported by many Matrix clients on Android. Using the same push gateway mechanism as other push services, it requires no additional support from the homeserver side. Below are notes for some known UnifiedPush distributors.
+
+:::info UP-Example
+The [UP-Example] app can be used to test and debug your UnifiedPush installation.

@@ -0,0 +130,4 @@
+
+This is likely an issue with one's _push rules_, which can be configured within the Matrix clients. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.
+
+Otherwise, if you find Continuwuity not sending push notifications according to the spec, feel free to discuss in the development room and open an issue.

@@ -0,0 +126,4 @@
+[NextPush Android]: https://codeberg.org/NextPush/nextpush-android
+
+## Troubleshooting
+

@@ -0,0 +130,4 @@
+### Push notifications not making sounds/not being sent
+
+This is likely an issue with one's _push rules_, which can be configured within the Matrix clients. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.
+

@@ -0,0 +143,4 @@
+WARN push{user_id="@user:example.com" pushkey="very-long-string-of-letters" events=1}:send_push_notice:send_notice:send_request: conduwuit_service::pusher: Could not send request to pusher https//push.example.com: error sending request for url (https://push.example.com/_matrix/push/v1/notify)
+```
+
+Then, your server is most likely sending push requests to too many invalid targets.

@@ -0,0 +1,191 @@
+import { Tab, Tabs } from '@rspress/core/theme';
+
+# Push notifications

@@ -0,0 +162,4 @@
+
+This is likely an issue with one's _push rules_, which determines what events are shown to users as notifications. Check your push rules in the clients' notifications settings and tweak accordingly. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.
+
+Another potential reason may be that background services for push are being frequently terminated by your operating system, a [well-known problem][dontkillmyapp] with many Android-based devices. To fix this, follow your operating system's instructions to allow your Push App (and sometimes, your Client App as well) to be exempt from background restrictions.

@@ -0,0 +5,4 @@
+Matrix clients receive notifications in the following ways:
+
+- **In-band notifications**, which are shown when the client actively syncs with the server.
+- **Push notifications**, which are posted by the server via an external push service to the client. This is commonly used for mobile devices to receive out-of-band notifications, and is the focal topic of this page.

@@ -0,0 +7,4 @@
+- **In-band notifications**, which are shown when the client actively syncs with the server.
+- **Push notifications**, which are posted by the server via an external push service to the client. This is commonly used for mobile devices to receive out-of-band notifications, and is the focal topic of this page.
+
+Generally, push notifications work out-of-the-box with your mobile device's preconfigured setup. The details below are useful for advanced use cases, such as when using an alternative push backend (e.g. UnifiedPush) or selfhosting your own.

@@ -0,0 +11,4 @@
+
+## Overview
+
+Continuwuity supports two push methods: using the legacy **Matrix Push Gateway** and the new **Web Push protocol**. The former method is currently supported by more clients, but the latter enables push notifications to be end-to-end-encrypted. They work as follows:

@@ -0,0 +16,4 @@
+<Tabs groupId="push-ops">
+<Tab label="Registration">
+<img src="./push-registration.webp"
+    alt="Diagram showing the push registration flow"

@@ -0,0 +22,4 @@
+
+A client registers a pusher with Continuwuity with the the following details supplied:
+
+- The _pushkey_, which is a unique target URL provided by the push backend that the client hooks up to.

@@ -0,0 +23,4 @@
+A client registers a pusher with Continuwuity with the the following details supplied:
+
+- The _pushkey_, which is a unique target URL provided by the push backend that the client hooks up to.
+- (For Push Gateway method only) The _push gateway_ URL, which is [provided by the client](#push-gateways).

@@ -0,0 +34,4 @@
+    style={{"max-height":300,display:"flex",margin:"1rem auto","border-radius":"5px"}}
+/>
+
+Continuwuity pushes messages to the push gateway, which then converts it into a suitable format and forwards it to the push provider server and then the push app. This push app then wakes up the client to fetch new message(s) from Continuwuity.

@@ -0,0 +36,4 @@
+
+Continuwuity pushes messages to the push gateway, which then converts it into a suitable format and forwards it to the push provider server and then the push app. This push app then wakes up the client to fetch new message(s) from Continuwuity.
+
+Finally, the client calculates, against a set of _push rules_, to determine whether the fetched message(s) should be notified to users or not.

@@ -0,0 +46,4 @@
+    style={{"max-height":300,display:"flex",margin:"1rem auto","border-radius":"5px"}}
+/>
+
+Continuwuity pushes encrypted messages to the push provider, which then forwards it to the push app and then the client. The client then wakes up to decrypt this push content, and if needed, fetches the full message from the server.

@@ -0,0 +54,4 @@
+
+</Tabs>
+
+_([excalidraw file of the diagrams](/guides/push-notifications.excalidraw))_

@@ -0,0 +60,4 @@
+
+### Push Gateways
+
+The push gateway URL is usually pre-configured by the app. However, some clients (such as Element X) implements [Gateway Discovery], and attempts to detect a push gateway _on the same domain as the push provider_, before falling back to a hardcoded one.

@@ -0,0 +66,4 @@
+
+```txt
+curl https://push.example.com/_matrix/push/v1/notify
+{"unifiedpush":{"gateway":"matrix"}}

@@ -0,0 +93,4 @@
+
+### ntfy
+
+[ntfy][ntfy] is an easy-to-install push application, and has plenty of publicly available instances. Its server can also be selfhosted and includes an embedded Matrix push gateway.

@@ -0,0 +95,4 @@
+
+[ntfy][ntfy] is an easy-to-install push application, and has plenty of publicly available instances. Its server can also be selfhosted and includes an embedded Matrix push gateway.
+
+Some tutorials on selfhosting ntfy can be found below:

@@ -0,0 +62,4 @@
+
+The push gateway URL is usually pre-configured by the app. However, some clients (such as Element X) implements [Gateway Discovery], and attempts to detect a push gateway _on the same domain as the push provider_, before falling back to a hardcoded one.
+
+As per the [spec][spec-push-gateway-api], these push gateways must be available on the `/_matrix/push/v1/notify` path of said domain. To test that a push gateway is accessible by the homeserver, make a request for it from the homeserver's IP:

@@ -0,0 +73,4 @@
+
+### Web Push
+
+Continuwuity implements Web Push according to [MSC4174], which generally works out of the box with most push providers. Note that this mechanism does not require a push gateway component.

@@ -0,0 +120,4 @@
+    - Push gateway: [common-proxies]
+    - Push server: [autopush-rs]
+    - Push app: [Sunup][sunup]
+- [Matrix notifications on Android, powered by XMPP][stratself-xmpp], by stratself.

@@ -0,0 +114,4 @@
+
+[unifiedpush-distributors]: https://unifiedpush.org/users/distributors/
+
+Community tutorials for selfhosting some of these stacks can be found below. Unless stated otherwise, they are all tested against Element X Android and the push gateway mechanism (but should be fine with Web Push as well).

@@ -0,0 +187,4 @@
+
+Active Matrix clients periodically renew their pushkeys as the old ones expire, and consequently register them against Continuwuity. As these pushers build up over time, the homeserver will keep sending more requests to an increasing number of "dead" push endpoints. This results in the errors seen above, and can heavily impact performance if not mitigated.
+
+To work around this issue, the following actions can be made:

@@ -0,0 +158,4 @@
+
+To fix this, configure `ip_range_denylist` to exclude your push gateway or push server's address from the array, and restart Continuwuity to apply the changes.
+
+### Push notifications not making sounds/not being seen

@@ -0,0 +146,4 @@
+
+## Troubleshooting
+
+Issues with push can arise due to other components of the system that is not your homeserver (for example, the connection fails between the push gateway and the push server). Make sure you check the logs of these components for debugging as well.

@@ -0,0 +189,4 @@
+
+To work around this issue, the following actions can be made:
+
+- Delete all pushers of a user with the [`!admin query pusher delete-all-user`](../reference/admin/query##admin-query-pusher-delete-all-user) command. This command is generally not very disruptive, as active clients will re-register new pushers the next time they log on.

@@ -0,0 +160,4 @@
+
+### Push notifications not making sounds/not being seen
+
+This is likely an issue with one's _push rules_, which determines what events are shown to users as notifications. Check your push rules in the clients' notifications settings and tweak accordingly. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.

@@ -0,0 +156,4 @@
+WARN conduwuit_service::pusher: Pusher URL is a forbidden remote address url=https://push.example.com/_matrix/push/v1/notify
+```
+
+To fix this, configure `ip_range_denylist` to exclude your push gateway or push server's address from the array, and restart Continuwuity to apply the changes.

@@ -0,0 +162,4 @@
+
+This is likely an issue with one's _push rules_, which determines what events are shown to users as notifications. Check your push rules in the clients' notifications settings and tweak accordingly. Continuwuity also provides an [`!admin users reset-push-rules`](../reference/admin/users#admin-users-reset-push-rules) command, which restores the rules to the default of notifying for every message.
+
+Another potential reason may be that background services for push are being frequently terminated by your operating system, a [well-known problem][dontkillmyapp] with many Android-based devices. To fix this, follow your operating system's instructions to allow your Push App to be exempt from background restrictions.

@@ -0,0 +181,4 @@
+
+#### Connection issues between the server and the push gateway
+
+Verify that connection to the push gateway is working correctly, which may include checking firewall rules, DNS, and that the push gateway is online. The section on [locally-hosted gateways/push providers](#locally-hosted-push-gateways--push-providers) may also apply to you.