Maintenance mode: layout override + scheduled windows + PubSub

[mdon]

Summary

Refactors maintenance mode from a redirect-based approach to a layout override — when maintenance turns on, a user's LiveView keeps running and their form state is preserved,
but the rendered layout is dynamically swapped to the maintenance page. URL never changes. When it ends, PubSub pushes the update and the layout swaps back, revealing the user's
page exactly as they left it.

Adds scheduled maintenance windows (UTC start/end with full validation), a scheduled auto-shutoff timer so users sitting on a blocked page get unblocked at the scheduled
end, and a live admin settings UI with real-time preview.

Highlights

Layout override approach (lib/phoenix_kit_web/users/auth.ex)

• check_maintenance_mode/1 sets socket.private[:live_layout] to {PhoenixKitWeb.Layouts, :maintenance} for non-admins via the existing plugin-layout pattern already used
  elsewhere in phoenix_kit
• PubSub hook attached via attach_hook fires on every status change — non-admin tabs swap layouts instantly, admin tabs stay put with no reload
• save_original_layout + defensive restore (deletes the key when original was nil) prevents renderer crashes
• Process.send_after timer on connected mount unblocks users when a scheduled end arrives (clamped to Erlang's 32-bit timeout max)

Scheduled maintenance (lib/modules/maintenance/maintenance.ex)

• Start only (activates indefinitely), end only (auto-disables manual toggle), or both (active during window)
• validate_schedule/2 rejects: empty, past start/end (60s tolerance for minute-precision inputs), end ≤ start, and >1 year in future
• cleanup_expired_schedule/0 auto-cleans stale state on every page access
• active?/0 wrapped in rescue so a DB outage fails open with a logged error

Plug for non-LiveView routes (lib/modules/maintenance/web/plugs/maintenance_mode.ex)

• Renders inline 503 HTML with Phoenix.HTML.html_escape (XSS-safe) and Retry-After header
• Auth routes and static assets always pass through

Admin settings UI (lib/modules/maintenance/settings.ex)

• Manual toggle, scheduled datetime pickers with system timezone display, content editor with live preview
• Current time display ticks every 30s
• Activity logging for all admin actions
• All user-facing strings wrapped in gettext
• Form-level phx-change so preview updates on every keystroke (not just blur)

Timezone helpers extracted to PhoenixKit.Utils.Date (with doctests):
offset_to_seconds/1, shift_to_offset/2, parse_datetime_local/2, format_datetime_local/2

[ddon]

Hi @mdon — nice work on this one. Architecture is solid (layout-swap + PubSub live restore is a real UX win), the validate_schedule/2 design is clean, and the test coverage — especially the XSS regression on the plug and the doctests on the extracted Utils.Date helpers — is at the bar we want.

Full review at dev_docs/pull_requests/2026/491-maintenance-layout-override/CLAUDE_REVIEW.md. Summary of what needs to change before merge:

BUG — HIGH (blocking)

• MaintenanceCountdown phx-hook is referenced but never defined. Both lib/phoenix_kit_web/components/layouts/maintenance.html.heex:31 and lib/modules/maintenance/web/maintenance_page_live.ex:139 emit phx-hook="MaintenanceCountdown", and the check_status handler is wired to receive the "countdown finished" event. But priv/static/assets/phoenix_kit.js doesn't register window.PhoenixKitHooks.MaintenanceCountdown. Result: the <span id="countdown-value"> stays empty and "Expected back in …" renders with no timer — a feature advertised in the PR body. Either add the JS hook (and make sure parent apps pick it up via the existing phoenix_kit.js include) or remove the markup + dead server handler.

• Plug's 503 HTML references a stylesheet path that doesn't exist.lib/modules/maintenance/web/plugs/maintenance_mode.ex:108 emits <link rel="stylesheet" href="/assets/css/app.css" />, but the real root layout (lib/phoenix_kit_web/components/layouts/root.html.heex:49) serves ~p"/assets/app.css" (no css/ segment, typically digested). Non-LiveView routes hitting the plug render unstyled. Either inline critical CSS, resolve the digested path, or serve a bare page without relying on daisyUI classes.

BUG — MEDIUM

• disable_system clears scheduled_start but not scheduled_end (maintenance.ex:131), leaving a surprising stop-signal for later re-enables.
• Plug's auth-route / favicon skip uses String.contains? (maintenance_mode.ex:53, 75-78) — a parent-app URL like /blog/users/log-in-to-us would bypass maintenance. Switch to String.starts_with? for path prefixes.
• Stale Process.send_after timer (auth.ex:1267) isn't canceled when the schedule changes. Saved today only because the handle_info handler re-checks Maintenance.active?/0 rather than trusting the payload — worth either canceling on re-subscribe or adding a comment that the payload is intentionally distrusted.

IMPROVEMENT — MEDIUM

• check_maintenance_mode is called from 6 different on_mount clauses in auth.ex — fold into a shared helper so new live_sessions can't forget it.
• put_in socket.private[:live_layout] is Phoenix internals — add a # HACK: note tying it to the LV version so future upgrades flag it.
• Settings page PubSub refresh doesn't re-read header/subtext — for multi-admin UX, broadcast content changes too.
• schedule_error_message(_) catch-all swallows unknown atoms silently — log a warning so future validation additions are visible.

Let me know when you're ready for another pass. The HIGH items (missing JS hook + wrong CSS path + String.contains? → String.starts_with?) are the merge blockers; the rest is polish.

[ddon]

Thanks @mdon — re-reviewed the two follow-up commits (89e5633d, 48c1f6f8) and everything from the prior review is addressed. Spot-checked:

• ✅ MaintenanceCountdown registered in priv/static/assets/phoenix_kit.js:2116 — no more silent no-op
• ✅ Plug 503 page is now self-contained inline CSS (no broken /assets/css/app.css link)
• ✅ auth_route? and static_asset? use String.starts_with? — plus a regression test for parent-app look-alike paths, nice touch
• ✅ disable_system/0 clears both scheduled_start and scheduled_end
• ✅ Timer ref tracked in :phoenix_kit_maintenance_timer_ref and cancelled on reschedule
• ✅ check_maintenance_mode folded into mount_phoenix_kit_current_scope/3 — new live_sessions inherit it automatically
• ✅ HACK comment near socket.private[:live_layout], schedule error catch-all logs warning, content PubSub sync in settings

LGTM from my side. 🚀

[ddon]

Approved — follow-up commits address all HIGH/MEDIUM items from the review.