[simlarsen]

The problem

The maintainer asked (task doc, block 27): "Can you please have calendar view as separate page in side menu with its own side menu section called 'Calendar'. We can then also implement some of these ideas: #5084, where we can overlay external feeds (You can create a new page in Settings called Calendar Settings so all of these options are advanced and can be hidden)".

Until now the scheduled maintenance calendar was the Calendar half of a List | Calendar switch on All Events (#4942), and a project could publish .ics feeds but not read anyone else's (#5084: public holidays, a change freeze kept in Exchange, another project's maintenance).

What changed

The calendar is a page of its own, under a Calendar section

• Scheduled Maintenance's side menu has a new Calendar section, right after Overview and open like it, holding Maintenance Calendar (/dashboard/:projectId/scheduled-maintenance-events/calendar). It is the calendar Scheduled maintenance: a calendar view, the team's calendar link, and a status page's maintenance calendar (iCal) #4942 built - month, week, day, filters, the + to schedule on a day, Subscribe to calendar - with its own title, breadcrumb and side-menu highlight.
• All Events is the list again: no switch, and Subscribe to calendar moves to the calendar (where the dialog already lived under the grid). The calendar's filter chips live in its address; saved views stay the list's.
• The Dashboard's page search finds Maintenance Calendar and Calendar Settings (also by "subscribe to calendar", "external calendars", "public holidays", "change freeze").
• Old links: the switch never put the view in the address, so /scheduled-maintenance-events still opens All Events. A reader whose browser had left the old switch on Calendar is taken to Maintenance Calendar once (replace, so Back is not trapped); the stored choice is then forgotten and All Events is the list from then on.

External calendars (#5084), set up on Calendar Settings

• Calendar Settings is a new page in Scheduled Maintenance's Settings section (folded by default - "advanced and can be hidden"), before Numbering, which stays every product's last Settings entry. I put it in the product's own Settings rather than Project Settings: everything about maintenance lives in its side menu (the docs say so), and that is the Settings section the maintainer's words point at.
• Adding one asks for a Name and its Calendar Link (https://, http:// or webcal://). Color (one the project's other calendars do not use) and Refresh (every hour; 15/30 min, 6 h, a day) are folded under More fields. It is read at once and its row says Working with the events kept, Waiting for the first read, Off, or Not working with the reason and what to do. Row ⋯: Read now, Change link, Turn off / Turn on; Edit changes its name, colour and refresh; Delete. Each action reloads the list, so the row says what happened.
• On the calendar, their events are drawn beside the project's, lighter (a wash with stripes and a dashed edge in the calendar's colour), named "(Calendar name)", and open nothing. Under the grid, External calendars has a toggle per enabled calendar (hidden ones are never asked for; the reader's choice is kept per project in their browser), a mark on one that could not be read lately (its last good events stay), and Calendar settings. The calendar's ⋯ also has Add External Calendar, which opens Calendar Settings with its Add dialog open. A project with none sees nothing new. A period holding more than 500 overlay events says so.
• Blackout periods (Scheduling checks and approvals for scheduled maintenance (blackout periods, dependencies, approvals) #4884): not on master (the issue is open), so there is no "use as a source of blackout periods" option yet.

How the calendars are read (server)

• Two new models: ScheduledMaintenanceExternalCalendar (CRUD at /scheduled-maintenance-external-calendar, in the API reference and so Terraform) and ScheduledMaintenanceExternalCalendarEvent (read-only to everyone; written by the Workers alone). Migration 1805120000000-AddScheduledMaintenanceExternalCalendars, generated against a fully migrated database, no drift after it.
• The link can be a secret, so it is encrypted and write-only (read: []): never returned by any API or page; only its host is shown. Change link replaces it and forgets the old link's events.
• A Workers job (ScheduledMaintenance:RefreshExternalCalendars, every minute) reads each enabled calendar whose next read is due, one at a time, batch after batch for at most 45 seconds per run; a calendar is claimed with a compare-and-set first, so two Workers never read one calendar. Read now (POST .../:id/read-now, for whoever may update it) is refused within 30 s of the last read or while it is off.
• Fetch: through OneUptime's egress guard (DataSourceEgressGuard, like the data sources and threat-intel feeds): the host is resolved and checked before a socket opens and the socket is pinned to the checked addresses; redirects are re-checked (at most 3); 5 MB cap (decompressed), 20 s for the whole read. Never loopback or a metadata address; OneUptime Cloud also refuses private networks.
• Parse: ical.js (Mozilla's parser) in a worker thread with a heap cap, a recurrence step budget and a 10 s limit after which it is terminated (an RRULE written never to match makes ical.js loop forever - measured). Before it, a one-pass linear pre-scan drops every property never read. RRULE, RDATE, EXDATE, RECURRENCE-ID overrides and cancellations, VTIMEZONE (as Exchange writes it), IANA and old Mozilla TZIDs, floating times (X-WR-TIMEZONE) and all-day dates are handled. Kept: 90 days back to a year ahead, up to 2,000 events (nearest today), the same window the team's link serves. An unchanged calendar is not worked out or written again (content digest).
• Overlay events are never part of the project's own calendar links (the team's link and a status page's), so two projects showing each other's link see each event once.
• Up to 20 external calendars per project. Same permissions as scheduled maintenance events (create/edit/delete events -> manage calendars; read events -> see them).

Small things around it

• The filter bar's end slot (filterBarEnd in useResourceOwners) only ever held the old switch, so it goes; comments that still named the switch are updated (ViewSwitch, RememberedView, CalendarToolbar, the LLM Usage page).
• OnCallCalendarFeedWiring found the rotated-out link's two sentences by "old link" + "calendar"; Change link's dialog names both, so it now looks for "empty calendar", as its own comment says.
• Dashboard Offline UI group 6's comment says what the suite's 22 new specs add.

What changes for existing customers

• The calendar moves from the All Events switch to Scheduled Maintenance -> Calendar -> Maintenance Calendar; a browser left on the calendar is taken there once. All Events' ⋯ no longer has Subscribe to calendar (it is under the calendar). Existing calendar links keep working.
• Nothing else changes until someone adds an external calendar. The Workers job does nothing for projects without one.

Left out

• Blackout periods from an overlay (Scheduling checks and approvals for scheduled maintenance (blackout periods, dependencies, approvals) #4884 is not built).
• No full-stack e2e spec in packages/E2E/Tests: the deployed e2e stack has no calendar server its egress guard would let OneUptime read; the reads are covered by the server suites, the Postgres suite and the offline browser suite below.

Tests (what each proves)

Common:

• ExternalCalendarExpansion.test.ts - the parser on Exchange, Google and OneUptime calendars: weekly and yearly RRULEs, an ended rule, RDATE, EXDATE, RECURRENCE-ID moves and cancellations, VTIMEZONE across DST, IANA/Mozilla/floating times, all-day dates, private events' titles, the window, the 2,000 cap, step budgets, malformed input, and a rule that never matches stopped at the time limit off the main thread.
• ExternalCalendarText.test.ts - the linear pre-scan, with 400,000-character worst cases under 2 s.
• ExternalCalendarFetch.test.ts - against a real local server: size cap (plain and gzip), deadline, a server that drips bytes, redirects re-checked by the guard, SSRF refusal, statuses mapped to reasons that never name the link.
• ExternalCalendarRefresher.test.ts - the claim, what a read writes, a failed read keeping the last good events, the unchanged calendar, a link replaced mid-read, Read now's refusals, and the job: batches until a short one, each calendar tried once a run, the 45 s budget.
• ScheduledMaintenanceExternalCalendarService/EventService/API/Models tests - write-only encrypted link, normalisation, colour picking, 20-per-project limit, resets on Change link, permissions, Read now routing.
• ScheduledMaintenanceExternalCalendarPostgres.test.ts (opt-in, wired into Postgres Schema Drift) - bulk replace, the claim race and the cascade on the migrated tables.
• AddScheduledMaintenanceExternalCalendarsMigration.test.ts - two tables and nothing else, indexes, FKs, down().
• ExternalCalendarApiSpec.test.ts - from the real OpenAPI generator (what Terraform is built from): the six routes, the link taken on create and update but never read back, nothing the Workers write taken, the events left out of the reference.
• OwnCalendarLinksLeaveOverlaysOut.test.ts - the team's and status pages' feeds never read external events.
• Dashboard: side menu (Calendar section open, Calendar Settings in folded Settings), page search covering both pages, overlays (hidden per project, all-day dates in every zone, timed events in the reader's), the calendar drawing and toggling them, the status words, the Calendar Settings page's contract (form fold, write-only link, every row action reloads the list and a refused one does not), every new sentence in every language.

App: ScheduledMaintenanceCalendarWiring (routes, page, the switch gone, the one-time redirect), ScheduledMaintenanceCalendarDarkMode, MaintenanceCalendarDocsFacts / ScheduledMaintenanceDocsFacts (docs held to the product: menus, fields, limits, permissions, egress guard).

Offline browser suite (test-maintenance-calendar-ui, 64 tests, 22 new): the Calendar section and page, All Events alone, the one-time move, overlays drawn/toggled/hidden/failing/truncated, Calendar Settings (status, add with folded fields, refused link, Change link, Turn off/on, refused Read now, a viewer's locked Add External Calendar), at 1280 and 390, light and dark, German and Japanese. It adds about 45 s locally (about 2 min 10 s with its bundle) to Dashboard Offline UI group 6, which lost Custom Roles (about 3 min) to group 7 today.

Run locally

• Offline browser suite (test-maintenance-calendar-ui): 64/64 green, about 2 min 10 s with its bundle.
• The whole Common and App jest suites after merging master. Every failure left is environmental or master's own, none in a file this branch touches: the Valkey/Redis suites (no Valkey here), the suites that need CI's config.env (SsoInCommunityEdition "Invalid Plan", the WebAuthn suites' "Invalid URL" without HOST, McpAuthorizePage's /api path), and two from master's own recent merges - TestSendRoutesAskTheRule (ExternalMcpServerAPI /test is not listed) and DashboardStorageArrayListComponents (the Incident template's extra MTTA query).
• After the last merge of master: this change's Common and App suites, the suites that read the files it changes (search index, saved views, calendar feed wording, docs facts and translations), npx jest Guard and npx jest Locale in Common, npx jest Locale and the root-level tests in App, DashboardLocalesGuard, i18n:check, i18n:validate, docs:check-anchors, repo-root Tests/Ops, and this change's suites once more with ee/ hidden.
• Postgres: every migration on a throwaway Postgres, CheckSchemaDrift.sh (no drift), then the opt-in external calendar suite against it.
• npm run compile in Common, App, the Dashboard and E2E, compile-tests in Common, the tsc --listFiles check (nothing from another package), prettier and eslint on every changed file, and the ReDoS checker (no pattern that is not linear).
• Not run: a full-stack e2e stack (see Left out).

UI review

Looked at, on the real pages in the offline fixture (the product's theme, Tailwind and Inter) at 1280, 1024, 768 and 390 px, light and dark, in English, German, Japanese, French and Russian: the Maintenance Calendar (month, week, day; a busy month; calendars failing, hidden, never read; a viewer), the external calendars' toggles, the calendar's ⋯ menu (owner and viewer), Calendar Settings (rows, empty, waiting, failing, off; Read now refused; Turn off), the Add dialog with More fields open, Edit, Change link, the row menu, All Events, and the docs page's External calendars section (en, de, ja at 1280 and 390).

Changed:

1. The project's own events come first. In a busy month a calendar from outside the project (a team's shifts, a holiday calendar, a change freeze across the week) took a cell's rows and folded the project's own maintenance into "+N more": react-big-calendar fills a cell by length and start time, and the "own events first" order the calendar handed it was never used. The shared Calendar now lays a page's own events out first and the overlays in the rows they leave (getCalendarLocalizer: a sort that puts overlays after, and a daySpan that never counts an overlay among the multi-day blocks laid out first). Pages without overlays (the on-call schedules) keep the calendar's one localizer.
2. A keyboard no longer stops on an overlay block in the week and day views. react-big-calendar draws those blocks as buttons in the tab order; an overlay's opened nothing and had its focus ring removed, so a Tab press went nowhere visible. CalendarEventWrapper takes overlays out of the tab order; a screen reader still reads them where they are.
3. The calendar card's header is All Events'. At tablet widths the card's default header broke "Maintenance Calendar" into a column a word wide beside "Create Scheduled Maintenance Event", and on a laptop wrapped the description over two lines. It now uses the toolbar header the list uses: title and buttons on one line, the description under both. On a phone, Create and the ⋯ are one group as on All Events (the button wraps its words beside the ⋯, instead of taking the line and leaving the ⋯ a line of its own).
4. Add External Calendar, in the calendar's ⋯, opens the Add dialog on Calendar Settings (?open=add-external-calendar, read once, for whoever may add one, then taken out of the address). It used to open the list, where the same button had to be found again. The docs' add step says so, in all 17 languages.
5. The toggles. Each is named by its calendar and says shown or hidden with aria-pressed; its name used to flip between "Hide X on the calendar" and "Show X on the calendar" while also pressed and unpressed ("Hide Public holidays, pressed"). What a click does is now the pointer's hint. A calendar not read lately has its mark inside its own chip (it sat between two chips, belonging to neither), and the reason is the toggle's description. A hidden chip's text is gray-500 (gray-400 was 2.5:1).
6. Overlay blocks are flat: no lift shadow, no hover change (the stylesheet said hovering changes nothing, but the shared hover shadow applied), and no second edge inside the dashed one in dark mode.
7. Copy. Calendar Settings' description is one sentence: "Show the events of other calendars, such as public holidays or a change freeze, on the Maintenance Calendar." It ran to two lines, three in the empty state. The breadcrumb names the page Maintenance Calendar, as its side menu entry and card do. Two keys nothing reads any more are gone from all 17 locales: the old switch's "Show the events as", and the toggles' short warning.

Left alone (shared, not this change): "Name is required." shows once More fields is opened before the name is typed (BasicForm marks a field touched on blur); the side menu's 224px column truncates "Maintenance Calendar" between 768 and 1023 px; a required dropdown (Refresh) keeps its clear button.

Tests added or changed in the review:

• Common UI/Components/Calendar/CalendarOverlayEvents.test.tsx (new): own events sort before overlays, an overlay never counts as multi-day, the localizer copy keeps the calendar's settings; month cells laid out own-first (same day, a long own event against a long holiday that began a day earlier, a change freeze across the week); week and day blocks of overlays out of the tab order, month blocks untouched.
• ScheduledMaintenanceCalendarExternalCalendars.test.tsx: toggles named by their calendar with aria-pressed and hints, the mark inside its toggle with the reason as its description, own events before overlays, the toolbar header.
• ScheduledMaintenanceCalendarSettingsPage.test.tsx: the Add dialog opened by the address (not otherwise, never for a viewer), the ask removed and the rest of the address kept; the new description.
• ExternalCalendarAddLink.test.ts (new): the ask and what does not count as one.
• MaintenanceCalendarInLocale.test.tsx: the toggles' names, hints and description in German, Russian, Japanese and Persian.
• App ScheduledMaintenanceCalendarWiring (the trail's name, the ⋯ item's wiring to the dialog) and MaintenanceCalendarDocsFacts (the reworded add step and the behaviour behind it).
• Offline suite (test-maintenance-calendar-ui, 69 tests, 5 new, about 2 min 20 s with its bundle, about 10 s more): the header at 1280, 1024 and 768; a busy month keeps the project's events visible, a long one included; a keyboard in the week skips overlays; Add External Calendar opens the dialog, once; on a phone Create and the ⋯ share a line as on All Events. The toggle tests follow the new names.
• Mutation-checked: each change reverted on its own fails its tests (14 mutations, 14 caught).

Run after merging master (344bfa3, the Code redesign; its locale conflict resolved with i18n:extract): the changed suites and every suite reading the changed files (the Calendar suites, the on-call schedule calendar suites, breadcrumbs, the readers of ScheduledMaintenanceTable, App's dark mode suites), npx jest Guard (Common 154 suites, App 41), npx jest Locale in Common and App, the general docs suites with the scheduled maintenance and calendar docs suites and DocsCriteriaConditions, App's root tests, RelationSelectColumnsWiring, Tests/Ops/E2ESuitesRunInCi, the changed suites with ee/ hidden, i18n:check, i18n:extract (nothing new), i18n:validate, docs:check-anchors, npm run compile in Common, App, the Dashboard and E2E, compile-tests, the tsc --listFiles check, prettier and eslint on every changed file, the ReDoS checker (no new pattern), and the whole offline suite (69/69). Not run: a full-stack e2e stack.

🤖 Generated with Claude Code

[simlarsen]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.