LotusGuild/cinny
3
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

[planning · sprint] Homeserver maintenance banner driven by the Uptime Kuma status page #124

New Issue
Closed
opened 2026-09-17 15:43:35 -04:00 by jared · 2 comments
jared commented 2026-09-17 15:43:35 -04:00
Owner
Copy Link
Copy Source

Jared: only for users of matrix.lotusguild.org; tie into Uptime Kuma at https://isitup.lotusguild.org/status/public tracking the homeserver and its sub-services. "Entire sprint, lots of planning, cannot get it wrong."

Facts to design around

  • Matrix has no scheduled-maintenance signal. Two standard-ish carriers exist: Server Notices (m.server_notice rooms, Synapse admin API — already rendered by Lotus) for the human-readable message, and nothing at all for a machine-readable countdown.
  • Uptime Kuma exposes a public JSON for a status page: GET /api/status-page/<slug> (monitor groups + maintenance windows with start/end/title/description) and GET /api/status-page/heartbeat/<slug> (current up/down per monitor). Scheduled maintenance is a first-class Kuma feature (Maintenance → schedule → attach to the status page). That gives us the countdown without inventing a Matrix event.

Proposed shape (to be planned, not built yet)

  • config.json: statusPages: { "matrix.lotusguild.org": "https://isitup.lotusguild.org/api/status-page/public" } — keyed by homeserver, so nothing is hardcoded and other homeservers simply have no banner.
  • Client polls the JSON (every 5 min, backoff on error, only when the tab is visible). Active/upcoming maintenance → a slim top strip: "Scheduled maintenance: Matrix restarts in 42 min (22:00–22:15)". Any core monitor down (Synapse / LiveKit / lk-jwt / media) → "Voice calls are currently down — we know" strip, so people stop DMing you.
  • Dismiss per maintenance id; never blocks the UI; degrades to nothing if Kuma is unreachable (Kuma being down must not look like Matrix being down).
  • Security/privacy: read-only public JSON, no auth, no cookies; CSP connect-src needs the isitup origin added (docker-nginx.conf + prod nginx). The client sends nothing.
  • Which monitors count as "core" is a Kuma group name (e.g. group "Matrix core") so you control it from Kuma, not from code.

Open questions for Jared (before any code)

  1. Which Kuma monitors/groups map to "Matrix is down" vs "just degraded"?
  2. Banner for upcoming maintenance: how far ahead (24 h? 1 h?)
  3. Should the desktop app also fire an OS notification 10 min before a window?
  4. Do you also want to keep sending a Server Notice for the message body, or let the Kuna description be the message?
Jared: only for users of `matrix.lotusguild.org`; tie into Uptime Kuma at https://isitup.lotusguild.org/status/public tracking the homeserver and its sub-services. "Entire sprint, lots of planning, cannot get it wrong." ### Facts to design around - Matrix has no scheduled-maintenance signal. Two standard-ish carriers exist: **Server Notices** (`m.server_notice` rooms, Synapse admin API — already rendered by Lotus) for the human-readable message, and nothing at all for a machine-readable countdown. - Uptime Kuma exposes a **public JSON** for a status page: `GET /api/status-page/<slug>` (monitor groups + *maintenance* windows with `start`/`end`/`title`/`description`) and `GET /api/status-page/heartbeat/<slug>` (current up/down per monitor). Scheduled maintenance is a first-class Kuma feature (Maintenance → schedule → attach to the status page). That gives us the countdown **without inventing a Matrix event**. ### Proposed shape (to be planned, not built yet) - `config.json`: `statusPages: { "matrix.lotusguild.org": "https://isitup.lotusguild.org/api/status-page/public" }` — keyed by homeserver, so nothing is hardcoded and other homeservers simply have no banner. - Client polls the JSON (every 5 min, backoff on error, only when the tab is visible). Active/upcoming **maintenance** → a slim top strip: "Scheduled maintenance: Matrix restarts in 42 min (22:00–22:15)". Any core monitor **down** (Synapse / LiveKit / lk-jwt / media) → "Voice calls are currently down — we know" strip, so people stop DMing you. - Dismiss per maintenance id; never blocks the UI; degrades to nothing if Kuma is unreachable (Kuma being down must not look like Matrix being down). - Security/privacy: read-only public JSON, no auth, no cookies; CSP `connect-src` needs the isitup origin added (docker-nginx.conf + prod nginx). The client sends nothing. - Which monitors count as "core" is a Kuma **group** name (e.g. group "Matrix core") so you control it from Kuma, not from code. ### Open questions for Jared (before any code) 1. Which Kuma monitors/groups map to "Matrix is down" vs "just degraded"? 2. Banner for *upcoming* maintenance: how far ahead (24 h? 1 h?) 3. Should the desktop app also fire an OS notification 10 min before a window? 4. Do you also want to keep sending a Server Notice for the message body, or let the Kuna description be the message?
real-server-down.png
218 KiB
real-server-problems.png
218 KiB
real-maintenance.png
229 KiB
real-calls-down.png
102 KiB
real-announcement.png
221 KiB
real-login-down.png
97 KiB
real-maintenance-dark.png
218 KiB
real-calls-down-dark.png
101 KiB
real-maintenance-mobile.png
147 KiB
real-server-down.png real-server-problems.png real-maintenance.png real-calls-down.png real-announcement.png real-login-down.png real-maintenance-dark.png real-calls-down-dark.png real-maintenance-mobile.png
jared added this to the Features 2026-Q4 milestone 2026-09-17 15:43:35 -04:00
jared self-assigned this 2026-09-17 15:43:35 -04:00
jared commented 2026-09-29 11:08:31 -04:00
Author
Owner
Copy Link
Copy Source

Design review: screenshots of the real client

These are screenshots of the actual Lotus Chat client: the current lotus code plus a prototype of the banner, on a local branch (server-status-banner) that isn't pushed or deployed. The app ran logged in to a local test homeserver.

  • Kuma was simulated: its two status-page URLs were answered with fake data for each state.
  • Server down: this client's sync connection was also cut.
  • Leaves: the falling leaves are the app's live autumn theme.

Only one strip shows at a time, in the same slot as the existing "Connecting…" and clock banners. When several apply, the one listed first here wins.

1 · Server down

The connection is lost and Kuma says the Homeserver group is down. Red, can't be dismissed. It replaces today's "Connection Lost!".
server down

2 · Server having problems

Kuma says the Homeserver group is down, but this client is still connected. Amber, can't be dismissed.
server problems

3 · Maintenance in progress

The title and end time come from the Kuma maintenance window, shown in the viewer's timezone. Details shows the Kuma description.
maintenance

4 · Voice calls down

Kuma's Voice calls group is down. Dismissable until it recovers. There's also a note above Join.
calls down

5 · Announcement

An incident posted on the Kuma status page. The colour follows the incident style (info, warning or danger). Dismissable; it comes back if you edit it.
announcement

6 · Sign-in problems (login screen only)

sign-in problems

Dark theme and phone

maintenance dark
calls down dark
phone

Behaviour

  • Scope: only for matrix.lotusguild.org. The config is keyed by homeserver, so users of other servers never contact Kuma.
  • What counts as down: a group is down when any of its monitors fails 2 checks in a row. For example, if the call token service is down, calls are down even while LiveKit is up.
  • Polling: every 5 min while the app is visible; every 60 s while a problem strip is showing; and at once when the connection drops.
  • Kuma unreachable: if Kuma can't be reached or returns something unexpected, no strip.

Your call

  1. Wording of each strip.
  2. Should 2 (server having problems) show at all?
  3. Do you want a short green "Back to normal" strip after an outage ends? (Not built yet.)
  4. Kuma setup: a status page with slug matrix and groups Homeserver, Voice calls and Login. Kuma is LXC 101 on monitor-02. Either you create them in the Kuma UI, or you give me a temporary admin login and I do it through Kuma's API.
## Design review: screenshots of the real client These are **screenshots of the actual Lotus Chat client**: the current `lotus` code plus a prototype of the banner, on a local branch (`server-status-banner`) that isn't pushed or deployed. The app ran logged in to a local test homeserver. - **Kuma was simulated:** its two status-page URLs were answered with fake data for each state. - **Server down:** this client's sync connection was also cut. - **Leaves:** the falling leaves are the app's live autumn theme. Only **one strip shows at a time**, in the same slot as the existing "Connecting…" and clock banners. When several apply, the one listed first here wins. ### 1 · Server down The connection is lost **and** Kuma says the Homeserver group is down. Red, can't be dismissed. It replaces today's "Connection Lost!". ![server down](https://code.lotusguild.org/attachments/96cbde25-3653-4330-8e1e-4fe1669182d4) ### 2 · Server having problems Kuma says the Homeserver group is down, but this client is still connected. Amber, can't be dismissed. ![server problems](https://code.lotusguild.org/attachments/782bfe51-7b0c-4548-a16d-66da19822e4f) ### 3 · Maintenance in progress The title and end time come from the Kuma maintenance window, shown in the viewer's timezone. **Details** shows the Kuma description. ![maintenance](https://code.lotusguild.org/attachments/b20a1699-6968-4260-b909-70941055834d) ### 4 · Voice calls down Kuma's Voice calls group is down. Dismissable until it recovers. There's also a note above **Join**. ![calls down](https://code.lotusguild.org/attachments/0e6c0d45-f1dc-4c04-94cc-f8cc467fba71) ### 5 · Announcement An incident posted on the Kuma status page. The colour follows the incident style (info, warning or danger). Dismissable; it comes back if you edit it. ![announcement](https://code.lotusguild.org/attachments/2f07f0b6-a148-4864-8030-b564fbdb5b05) ### 6 · Sign-in problems (login screen only) ![sign-in problems](https://code.lotusguild.org/attachments/7eadce03-f1d2-49d8-aacb-ec95d4c17810) ### Dark theme and phone ![maintenance dark](https://code.lotusguild.org/attachments/cf57e476-1f42-46a5-9169-56ae2b75f9a8) ![calls down dark](https://code.lotusguild.org/attachments/536f083b-61dc-40dc-a2c2-c98e911959a0) ![phone](https://code.lotusguild.org/attachments/b8da7d69-ef4b-4f94-8456-3a304850ea62) ### Behaviour - **Scope:** only for `matrix.lotusguild.org`. The config is keyed by homeserver, so users of other servers never contact Kuma. - **What counts as down:** a group is down when **any** of its monitors fails **2 checks in a row**. For example, if the call token service is down, calls are down even while LiveKit is up. - **Polling:** every 5 min while the app is visible; every 60 s while a problem strip is showing; and at once when the connection drops. - **Kuma unreachable:** if Kuma can't be reached or returns something unexpected, **no strip**. ### Your call 1. Wording of each strip. 2. Should **2** (server having problems) show at all? 3. Do you want a short green "Back to normal" strip after an outage ends? (Not built yet.) 4. Kuma setup: a status page with slug `matrix` and groups **Homeserver**, **Voice calls** and **Login**. Kuma is LXC 101 on monitor-02. Either you create them in the Kuma UI, or you give me a temporary admin login and I do it through Kuma's API.
jared commented 2026-09-30 10:07:22 -04:00
Author
Owner
Copy Link
Copy Source

Live (2026-09-29)

  • Kuma: status page https://isitup.lotusguild.org/status/matrix:
    • Homeserver: Synapse (30).
    • Voice calls: three new public checks: LiveKit /rtc/validate (37), call tokens /sfu/get (38), call page (39).
    • Login: Authelia (15).
  • cinny #255: the banner code, merged and deployed.
  • matrix #16: CSP connect-src now allows https://isitup.lotusguild.org. Installed on LXC 106 with a backup and nginx -t.
  • matrix #17: statusPages in production's config.json. This was the missing piece; the live config comes from the matrix repo.
  • cinny-desktop #29: the same entry for the desktop app, which picks it up in the next nightly build.

Verified on chat.lotusguild.org:

  • Kuma requests: the app fetches both Kuma endpoints (200), with no CSP, CORS or page errors.
  • No banner while everything is green.
  • Desktop: checked on a Linux release build, both the banner and the real Kuma fetch.

Managing it from Kuma:

  • Announcements: post a pinned incident on the matrix page (for example planned maintenance tonight). Info, warning and danger map to the strip's colour.
  • Maintenance: attach a maintenance window to the matrix page. The strip shows while it's under way, with the end time.
## Live (2026-09-29) - **Kuma:** status page https://isitup.lotusguild.org/status/matrix: - **Homeserver:** Synapse (30). - **Voice calls:** three new public checks: LiveKit `/rtc/validate` (37), call tokens `/sfu/get` (38), call page (39). - **Login:** Authelia (15). - **cinny #255:** the banner code, merged and deployed. - **matrix #16:** CSP `connect-src` now allows `https://isitup.lotusguild.org`. Installed on LXC 106 with a backup and `nginx -t`. - **matrix #17:** `statusPages` in production's `config.json`. This was the missing piece; the live config comes from the matrix repo. - **cinny-desktop #29:** the same entry for the desktop app, which picks it up in the next nightly build. **Verified on chat.lotusguild.org:** - **Kuma requests:** the app fetches both Kuma endpoints (**200**), with no CSP, CORS or page errors. - **No banner** while everything is green. - **Desktop:** checked on a Linux release build, both the banner and the real Kuma fetch. **Managing it from Kuma:** - **Announcements:** post a pinned incident on the `matrix` page (for example planned maintenance tonight). Info, warning and danger map to the strip's colour. - **Maintenance:** attach a maintenance window to the `matrix` page. The strip shows while it's under way, with the end time.
jared closed this issue 2026-09-30 10:07:22 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
a11y
Accessibility: keyboard, screen reader, contrast, motion
 area: appearance
Client area: appearance
 area: auth-session
Client area: auth-session
 area: build-ci
Client area: build-ci
 area: calls
Client area: calls
 area: desktop
Client area: desktop
 area: media
Client area: media
 area: messaging
Client area: messaging
 area: mobile
Client area: mobile
 area: moderation
Client area: moderation
 area: navigation
Client area: navigation
 area: notifications
Client area: notifications
 area: settings
Client area: settings
 area: threads
Client area: threads
 bug
Something is not working
 dependencies
Third-party package versions and advisories
 docs
README / LOTUS_* docs wrong or missing
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 needs-human-review
performance
Re-render storms, leaks, heavy work on hot paths
 planning
priority: critical
Data loss, security hole, or crash on a main path
 priority: high
Broken feature or serious usability problem
 priority: low
Minor issue or polish
 priority: medium
Wrong behaviour in an edge case or notable degradation
 qa
Manual QA: shipped, needs a human in a real environment
 question
More information is needed
 research
security
XSS, unsafe URLs, data leaks, auth/session
 tech-debt
Code health, dead code, fragile patterns
 ux
Usability or visual inconsistency
 wontfix
This won't be fixed
No labels area: notifications enhancement needs-human-review planning priority: medium
Milestone
No items
No Milestone Features 2026-Q4
Projects
Clear projects
No projects
Assignees
Clear assignees
cole (Cole Keller) jared (Jared Vititoe) nathan (Nathan Vititoe)
No Assignees jared
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: LotusGuild/cinny#124