@oneuptime/common 12.0.29 → 12.0.31

package/build/dist/Server/Utils/OnCall/OnCallCalendarFeedRenderer.js

@@ -0,0 +1,983 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import DatabaseConfig from "../../DatabaseConfig";
+import { IsBillingEnabled, getAllEnvVars } from "../../EnvironmentConfig";
+import OnCallCalendarFeedCache from "../../Infrastructure/OnCallCalendarFeedCache";
+import OnCallDutyPolicyScheduleService from "../../Services/OnCallDutyPolicyScheduleService";
+import ProjectService from "../../Services/ProjectService";
+import UserService from "../../Services/UserService";
+import QueryHelper from "../../Types/Database/QueryHelper";
+import logger from "../Logger";
+import Response from "../Response";
+import AppMetrics from "../Telemetry/AppMetrics";
+import CaptureSpan from "../Telemetry/CaptureSpan";
+import OnCallCalendarFeedUrls from "./OnCallCalendarFeedUrls";
+import OnCallShiftMaterializer from "./OnCallShiftMaterializer";
+import SubscriptionPlan, { PlanType, } from "../../../Types/Billing/SubscriptionPlan";
+import OneUptimeDate from "../../../Types/Date";
+import { LIMIT_PER_PROJECT } from "../../../Types/Database/LimitMax";
+import ObjectID from "../../../Types/ObjectID";
+import SortOrder from "../../../Types/BaseDatabase/SortOrder";
+import CalendarFeedWindow, { BODY_CACHE_TTL_SECONDS, FEED_SIMULATION_ITERATION_CAP, MAX_EVENTS, MAX_GAP_EVENTS, SCHEDULE_CACHE_TTL_SECONDS, } from "../../../Types/OnCallDutyPolicy/CalendarFeedWindow";
+import MaterializedShiftUtil from "../../../Types/OnCallDutyPolicy/MaterializedShift";
+import OnCallCalendarFeedUtil, { OnCallCalendarFeedKind, } from "../../../Types/OnCallDutyPolicy/OnCallCalendarFeedUtil";
+import { createHash } from "crypto";
+/*
+ * Turns one feed row plus its request into a calendar body.
+ *
+ * Everything between "the token resolved to this row" and "send these bytes"
+ * lives here so the three public routes (personal, schedule, project) and
+ * the session-authenticated /my-shifts route share one pipeline:
+ *
+ *   authorisation (re-derived on EVERY fetch; a valid token is not
+ *   authorisation) -> body cache -> render slot -> schedule-level cache ->
+ *   materialize -> shrink to MAX_EVENTS -> coverage gaps -> serialize ->
+ *   body + last-good cache -> metrics.
+ *
+ * Three outcomes come out of it, matching the one response rule the routes
+ * apply: a rendered body (200), an empty calendar that says why (200, so
+ * subscribed clients clear their copy instead of dropping the calendar), or
+ * "unavailable" (503 + Retry-After) when nothing at all can be served.
+ *
+ * Stale-while-error: when a render throws, hits the per-process render cap
+ * or trips a schedule's iteration cap, the most recent body that rendered
+ * successfully for the same key is served instead, flagged `stale` so the
+ * route adds `Warning: 110` and the bookkeeping records lastRenderTruncated.
+ * Only when there is nothing to fall back to does the outcome turn into a
+ * 503.
+ *
+ * Nothing here ever sees the plaintext token. The body-cache key carries the
+ * token HASH (so a rotation is a new key) and the log lines carry the feed
+ * kind and row id.
+ */
+export var FeedRenderStatus;
+(function (FeedRenderStatus) {
+    FeedRenderStatus["Rendered"] = "rendered";
+    FeedRenderStatus["Empty"] = "empty";
+    FeedRenderStatus["Unavailable"] = "unavailable";
+})(FeedRenderStatus || (FeedRenderStatus = {}));
+export const RENDER_CAP_RETRY_AFTER_SECONDS = 60;
+/*
+ * The X-WR-CALDESC sentences for every "200 but empty" case. Exported so the
+ * routes, the tests and (through the docs) the users see the same words.
+ */
+export const FEED_DISABLED_REASON = "This calendar feed is turned off in OneUptime. Turn it back on from the Calendar Feed settings to see shifts here again.";
+export const TOKEN_ROTATED_REASON = "This calendar link was regenerated in OneUptime. Subscribe to the new link from the Calendar Feed settings; this one will stop working soon.";
+export const PLAN_REASON = "Calendar feeds need the Growth plan or higher. Upgrade the project's plan in OneUptime to see shifts here.";
+export const USER_MISSING_REASON = "The user this calendar link belongs to no longer exists.";
+export const NO_SCHEDULES_REASON = "You are not on any on-call schedule in this project right now. Shifts appear here once you are added to a schedule.";
+export const FILTERED_SCHEDULE_REASON = "You are not on the on-call schedule this calendar link is filtered to.";
+export const SCHEDULE_MISSING_REASON = "The on-call schedule this calendar link belongs to no longer exists.";
+export const PROJECT_MISSING_REASON = "The project this calendar link belongs to no longer exists.";
+export const NO_PROJECT_SCHEDULES_REASON = "This project has no on-call schedules yet. Shifts appear here once a schedule is created.";
+export default class OnCallCalendarFeedRenderer {
+    // -- Outcomes ----------------------------------------------------------
+    /*
+     * The empty VCALENDAR outcome for one of the "200 but nothing to show"
+     * cases. Cheap enough not to cache: it is a header and a sentence.
+     */
+    static buildEmptyOutcome(options) {
+        const now = options.now || OneUptimeDate.getCurrentDate();
+        const body = OnCallCalendarFeedUtil.renderEmpty({
+            kind: options.kind,
+            reason: options.reason,
+            scheduleName: options.scheduleName,
+            projectName: options.projectName,
+            filterScheduleName: options.filterScheduleName,
+            timezone: options.timezone,
+        });
+        return {
+            status: FeedRenderStatus.Empty,
+            kind: options.kind,
+            body,
+            etag: Response.getCalendarETag(body),
+            lastModified: now,
+            stale: false,
+            truncated: false,
+            eventCount: 0,
+            cacheHit: false,
+            reason: options.reason,
+            retryAfterSeconds: null,
+        };
+    }
+    static buildUnavailableOutcome(kind, retryAfterSeconds) {
+        return {
+            status: FeedRenderStatus.Unavailable,
+            kind,
+            body: "",
+            etag: "",
+            lastModified: OneUptimeDate.getCurrentDate(),
+            stale: false,
+            truncated: false,
+            eventCount: 0,
+            cacheHit: false,
+            reason: null,
+            retryAfterSeconds,
+        };
+    }
+    static outcomeFromCachedBody(data) {
+        return {
+            status: FeedRenderStatus.Rendered,
+            kind: data.kind,
+            body: data.cached.body,
+            etag: data.cached.etag,
+            lastModified: data.cached.lastModified,
+            stale: data.stale,
+            truncated: data.truncated,
+            eventCount: OnCallCalendarFeedRenderer.countEvents(data.cached.body),
+            cacheHit: data.cacheHit,
+            reason: null,
+            retryAfterSeconds: null,
+        };
+    }
+    // -- Plan --------------------------------------------------------------
+    /*
+     * Decision 3: below-plan projects render an EMPTY calendar, never a 404.
+     * The check is imperative because the public routes read as root, so the
+     * models' @TableBillingAccessControl never runs for them. A project whose
+     * plan cannot be read (deleted mid-request, or no plan yet) is treated as
+     * below plan: failing closed here costs one empty calendar, failing open
+     * would hand out rosters for free.
+     */
+    static async isProjectOnPlan(projectId, options) {
+        const billingEnabled = (options === null || options === void 0 ? void 0 : options.billingEnabled) === undefined
+            ? IsBillingEnabled
+            : options.billingEnabled;
+        if (!billingEnabled) {
+            return true;
+        }
+        try {
+            const current = await ProjectService.getCurrentPlan(projectId);
+            if (!current.plan) {
+                return false;
+            }
+            return SubscriptionPlan.isFeatureAccessibleOnCurrentPlan(PlanType.Growth, current.plan, getAllEnvVars());
+        }
+        catch (err) {
+            logger.warn(`OnCallCalendarFeedRenderer: could not read the plan of project ${projectId.toString()}; treating it as below plan.`);
+            logger.warn(err);
+            return false;
+        }
+    }
+    // -- Render ------------------------------------------------------------
+    static async render(request) {
+        const now = request.now || OneUptimeDate.getCurrentDate();
+        const pastDays = CalendarFeedWindow.clampPastDays(request.pastDays);
+        const futureDays = CalendarFeedWindow.clampFutureDays(request.futureDays);
+        const window = CalendarFeedWindow.computeFeedWindow({
+            now,
+            pastDays,
+            futureDays,
+        });
+        const context = await OnCallCalendarFeedRenderer.resolveContext(request, window);
+        if (context.empty) {
+            return OnCallCalendarFeedRenderer.buildEmptyOutcome({
+                kind: request.kind,
+                reason: context.reason,
+                scheduleName: context.scheduleName,
+                projectName: context.projectName,
+                filterScheduleName: context.filterScheduleName,
+                timezone: context.timezone,
+                now,
+            });
+        }
+        const scheduleIds = context.schedules.map((schedule) => {
+            return schedule.id.toString();
+        });
+        const bodyKey = OnCallCalendarFeedRenderer.buildBodyCacheKey({
+            request,
+            pastDays,
+            futureDays,
+            schedules: context.schedules,
+            now,
+        });
+        const lastGoodKey = OnCallCalendarFeedRenderer.buildLastGoodCacheKey({
+            request,
+            pastDays,
+            futureDays,
+            schedules: context.schedules,
+        });
+        const scope = {
+            projectId: request.projectId.toString(),
+            userId: request.kind === OnCallCalendarFeedKind.Personal
+                ? request.userId.toString()
+                : undefined,
+            scheduleIds,
+        };
+        const cachedBody = await OnCallCalendarFeedCache.getBody({ key: bodyKey, scope });
+        if (cachedBody) {
+            return OnCallCalendarFeedRenderer.outcomeFromCachedBody({
+                kind: request.kind,
+                cached: cachedBody,
+                stale: false,
+                cacheHit: true,
+                truncated: false,
+            });
+        }
+        if (!OnCallCalendarFeedCache.tryAcquireRenderSlot()) {
+            return await OnCallCalendarFeedRenderer.fallBackToLastGood({
+                kind: request.kind,
+                lastGoodKey,
+                why: "render cap reached",
+            });
+        }
+        const startedAt = Date.now();
+        try {
+            const segments = await OnCallCalendarFeedRenderer.loadScheduleSegmentsBatch({
+                schedules: context.schedules,
+                windowStart: window.feedStart,
+                windowEnd: window.feedEnd,
+                now,
+            });
+            const iterationTruncated = segments.filter((segment) => {
+                return segment.truncated;
+            });
+            /*
+             * A capped expansion is missing shifts. A complete body from an
+             * earlier render is better than a partial one now; only when there is
+             * none does the partial render go out, with a note saying so.
+             */
+            if (iterationTruncated.length > 0) {
+                const lastGood = await OnCallCalendarFeedCache.getLastGood(lastGoodKey);
+                if (lastGood) {
+                    logger.warn(`OnCallCalendarFeedRenderer: ${request.kind} feed ${request.feedId.toString()} hit the iteration cap; serving the last good body.`);
+                    return OnCallCalendarFeedRenderer.outcomeFromCachedBody({
+                        kind: request.kind,
+                        cached: lastGood,
+                        stale: true,
+                        cacheHit: false,
+                        truncated: true,
+                    });
+                }
+            }
+            /*
+             * The schedules' full resolution, before the personal feed narrows it to
+             * the subscriber. A policy-scoped override materializes as a variant
+             * shift belonging to the SUBSTITUTE, so filtering it away would leave
+             * the rostered user's own event claiming to page them through a policy
+             * that pages somebody else. The unfiltered list is handed to the mapper
+             * as context (it never becomes VEVENTs) so that event can say so.
+             */
+            const allScheduleShifts = OnCallCalendarFeedRenderer.collectShifts(segments, now);
+            let shifts = allScheduleShifts;
+            if (request.kind === OnCallCalendarFeedKind.Personal) {
+                shifts = OnCallShiftMaterializer.filterShiftsForUser(shifts, request.userId);
+            }
+            const shrink = OnCallCalendarFeedUtil.shrinkWindowToFit({
+                shifts,
+                feedStart: window.feedStart,
+                feedEnd: window.feedEnd,
+            });
+            const notes = [];
+            if (shrink.truncated) {
+                notes.push(`Shortened to ${Math.max(0, futureDays - shrink.daysDropped)} days ahead because the feed would exceed ${MAX_EVENTS} events.`);
+            }
+            if (iterationTruncated.length > 0) {
+                const names = iterationTruncated
+                    .map((segment) => {
+                    return segment.scheduleName;
+                })
+                    .join(", ");
+                notes.push(`Some shifts may be missing: the schedule ${names} is too complex to expand fully. Simplify its layers or shorten the feed window.`);
+            }
+            let gapEvents = [];
+            let gapsTruncated = false;
+            const dashboardUrl = (await DatabaseConfig.getDashboardUrl()).toString();
+            if (request.kind !== OnCallCalendarFeedKind.Personal &&
+                request.includeCoverageGaps) {
+                const gaps = OnCallCalendarFeedRenderer.buildGapEvents({
+                    segments,
+                    feedStart: window.feedStart,
+                    feedEnd: shrink.feedEnd,
+                    minimumGapMinutes: request.minimumGapMinutes,
+                    dashboardUrl,
+                });
+                gapEvents = gaps.events;
+                gapsTruncated = gaps.truncated;
+                if (gapsTruncated) {
+                    notes.push(`Only the first ${MAX_GAP_EVENTS} coverage gaps are shown.`);
+                }
+            }
+            const rendered = OnCallCalendarFeedUtil.render({
+                kind: request.kind,
+                shifts: shrink.shifts,
+                contextShifts: allScheduleShifts,
+                dashboardUrl,
+                viewerTimezone: context.viewerTimezone,
+                calendarTimezone: context.calendarTimezone,
+                scheduleName: context.scheduleName,
+                projectName: context.projectName,
+                filterScheduleName: context.filterScheduleName,
+                notes,
+                gapEvents,
+            });
+            const value = {
+                body: rendered.body,
+                etag: Response.getCalendarETag(rendered.body),
+                lastModified: rendered.lastModifiedAt || now,
+            };
+            await OnCallCalendarFeedCache.setBody({
+                key: bodyKey,
+                scope,
+                value,
+                ttlSeconds: BODY_CACHE_TTL_SECONDS,
+            });
+            /*
+             * A partial render must never become the "last good" body: the next
+             * complete render would then be shadowed by it on the next failure.
+             */
+            if (iterationTruncated.length === 0) {
+                await OnCallCalendarFeedCache.setLastGood(lastGoodKey, value);
+            }
+            OnCallCalendarFeedRenderer.recordMetrics({
+                kind: request.kind,
+                durationMs: Date.now() - startedAt,
+                eventCount: rendered.eventCount,
+            });
+            return {
+                status: FeedRenderStatus.Rendered,
+                kind: request.kind,
+                body: value.body,
+                etag: value.etag,
+                lastModified: value.lastModified,
+                stale: false,
+                truncated: shrink.truncated || iterationTruncated.length > 0 || gapsTruncated,
+                eventCount: rendered.eventCount,
+                cacheHit: false,
+                reason: null,
+                retryAfterSeconds: null,
+            };
+        }
+        catch (err) {
+            logger.error(`OnCallCalendarFeedRenderer: rendering the ${request.kind} feed ${request.feedId.toString()} failed.`);
+            logger.error(err);
+            return await OnCallCalendarFeedRenderer.fallBackToLastGood({
+                kind: request.kind,
+                lastGoodKey,
+                why: "render failed",
+            });
+        }
+        finally {
+            OnCallCalendarFeedCache.releaseRenderSlot();
+        }
+    }
+    // -- /my-shifts --------------------------------------------------------
+    /*
+     * The caller's own shifts between two instants, through the same
+     * schedule-level cache the feeds use. The window handed to the cache is
+     * widened to whole UTC days so a mobile client asking for "now to +30 d"
+     * every few minutes keys the same entries as the feeds do, and the result
+     * is then cut back to what was asked for.
+     */
+    static async materializeUserShifts(data) {
+        const now = data.now || OneUptimeDate.getCurrentDate();
+        const windowStart = new Date(CalendarFeedWindow.startOfUtcDay(data.from));
+        const endDayStart = CalendarFeedWindow.startOfUtcDay(data.to);
+        const windowEnd = new Date(data.to.getTime() > endDayStart
+            ? endDayStart + 24 * 60 * 60 * 1000
+            : endDayStart);
+        const candidateIds = await OnCallShiftMaterializer.getCandidateScheduleIdsForUser({
+            userId: data.userId,
+            projectIds: data.projectIds,
+            windowStart,
+            windowEnd,
+            includeCoveringShifts: true,
+        });
+        if (candidateIds.length === 0) {
+            return { shifts: [], truncated: false, generatedAt: now };
+        }
+        const schedules = await OnCallCalendarFeedRenderer.loadSchedules(candidateIds);
+        const segments = await OnCallCalendarFeedRenderer.loadScheduleSegmentsBatch({
+            schedules,
+            windowStart,
+            windowEnd,
+            now,
+        });
+        const own = OnCallShiftMaterializer.filterShiftsForUser(OnCallCalendarFeedRenderer.collectShifts(segments, now), data.userId);
+        const inRange = own.filter((shift) => {
+            return shift.start < data.to && shift.end > data.from;
+        });
+        return {
+            shifts: MaterializedShiftUtil.sortByStart(inRange),
+            truncated: segments.some((segment) => {
+                return segment.truncated;
+            }),
+            generatedAt: now,
+        };
+    }
+    // -- Schedule-level cache ---------------------------------------------
+    /*
+     * One schedule's materialization over one window, from the shared cache or
+     * freshly rendered into it. The key is the schedule's shiftConfigVersion
+     * plus the exact window, so every feed and /my-shifts call that lands on
+     * the same day-aligned window shares one LayerUtil expansion.
+     *
+     * The coverage envelope is computed in the same callback: it is the same
+     * cost class as the expansion and the gap-event path would otherwise
+     * expand every layer a second time.
+     */
+    static async loadScheduleSegments(data) {
+        const loaded = await OnCallCalendarFeedRenderer.loadScheduleSegmentsBatch({
+            schedules: [data.schedule],
+            windowStart: data.windowStart,
+            windowEnd: data.windowEnd,
+            now: data.now,
+        });
+        const segments = loaded[0];
+        if (!segments) {
+            throw new Error(`OnCallCalendarFeedRenderer: no segments were produced for schedule ${data.schedule.id.toString()}.`);
+        }
+        return segments;
+    }
+    /*
+     * Every schedule of one feed, over one window, in ONE pass: the cache
+     * separates hits from misses and the misses are materialized together.
+     * Reading them one by one made each schedule its own resolver call --
+     * seven queries per schedule and the same user and project rows read again
+     * for every one of them -- fanned out concurrently, which for a project
+     * feed over fifty schedules was hundreds of statements in flight against a
+     * fifty-connection pool. The order of `schedules` is preserved.
+     */
+    static async loadScheduleSegmentsBatch(data) {
+        if (data.schedules.length === 0) {
+            return [];
+        }
+        const byId = new Map();
+        for (const schedule of data.schedules) {
+            byId.set(schedule.id.toString(), schedule);
+        }
+        const entries = data.schedules.map((schedule) => {
+            return {
+                scheduleId: schedule.id.toString(),
+                key: `${schedule.shiftConfigVersion}:${data.windowStart.toISOString()}:${data.windowEnd.toISOString()}`,
+            };
+        });
+        const rendered = await OnCallCalendarFeedCache.getOrRenderScheduleSegmentsBatch({
+            entries,
+            ttlSeconds: SCHEDULE_CACHE_TTL_SECONDS,
+            renderMissing: async (missing) => {
+                const schedules = [];
+                for (const entry of missing) {
+                    const schedule = byId.get(entry.scheduleId);
+                    if (schedule) {
+                        schedules.push(schedule);
+                    }
+                }
+                return await OnCallCalendarFeedRenderer.renderScheduleSegments({
+                    schedules,
+                    windowStart: data.windowStart,
+                    windowEnd: data.windowEnd,
+                    now: data.now,
+                });
+            },
+        });
+        const ordered = [];
+        for (const schedule of data.schedules) {
+            const segments = rendered.get(schedule.id.toString());
+            if (segments) {
+                ordered.push(segments);
+            }
+        }
+        return ordered;
+    }
+    /*
+     * ONE resolver call for every schedule that missed the cache, split back
+     * into one cache entry per schedule.
+     */
+    static async renderScheduleSegments(data) {
+        var _a, _b, _c, _d;
+        const out = new Map();
+        if (data.schedules.length === 0) {
+            return out;
+        }
+        const result = await OnCallShiftMaterializer.materializeForSchedules({
+            scheduleIds: data.schedules.map((schedule) => {
+                return schedule.id;
+            }),
+            windowStart: data.windowStart,
+            windowEnd: data.windowEnd,
+            now: data.now,
+            maxSimulationIterations: FEED_SIMULATION_ITERATION_CAP,
+        });
+        const shiftsBySchedule = new Map();
+        for (const shift of result.shifts) {
+            const list = shiftsBySchedule.get(shift.scheduleId) || [];
+            list.push(shift);
+            shiftsBySchedule.set(shift.scheduleId, list);
+        }
+        for (const schedule of data.schedules) {
+            const scheduleId = schedule.id.toString();
+            const info = result.schedules.find((candidate) => {
+                return candidate.scheduleId === scheduleId;
+            });
+            let envelope = { segments: [], truncated: false };
+            if (info) {
+                envelope = OnCallCalendarFeedUtil.computeCoverageEnvelope({
+                    layers: info.layerProps,
+                    windowStart: data.windowStart,
+                    windowEnd: data.windowEnd,
+                    maxSimulationIterations: FEED_SIMULATION_ITERATION_CAP,
+                });
+            }
+            out.set(scheduleId, {
+                scheduleId,
+                scheduleName: (info === null || info === void 0 ? void 0 : info.scheduleName) || schedule.name,
+                scheduleTimezone: (_b = (_a = info === null || info === void 0 ? void 0 : info.scheduleTimezone) !== null && _a !== void 0 ? _a : schedule.timezone) !== null && _b !== void 0 ? _b : null,
+                projectId: (info === null || info === void 0 ? void 0 : info.projectId) || schedule.projectId.toString(),
+                projectName: (_c = info === null || info === void 0 ? void 0 : info.projectName) !== null && _c !== void 0 ? _c : null,
+                shiftConfigVersion: (_d = info === null || info === void 0 ? void 0 : info.shiftConfigVersion) !== null && _d !== void 0 ? _d : schedule.shiftConfigVersion,
+                lastModifiedAt: ((info === null || info === void 0 ? void 0 : info.lastModifiedAt) || data.now).toISOString(),
+                truncated: info ? info.truncated : result.truncated,
+                shifts: MaterializedShiftUtil.toJSONArray(shiftsBySchedule.get(scheduleId) || []),
+                envelope: envelope.segments.map((segment) => {
+                    return {
+                        start: segment.start.toISOString(),
+                        end: segment.end.toISOString(),
+                    };
+                }),
+                envelopeTruncated: envelope.truncated,
+            });
+        }
+        return out;
+    }
+    // -- Cache key ---------------------------------------------------------
+    /*
+     * `${kind}:${tokenHash}:${filters}:${window}` -- everything that identifies
+     * the FEED, with nothing in it that changes when the roster does. Shared by
+     * the body key and the last-good key.
+     */
+    static buildFeedIdentityKey(data) {
+        var _a;
+        const request = data.request;
+        let filters;
+        if (request.kind === OnCallCalendarFeedKind.Personal) {
+            filters = `s=${((_a = request.scheduleFilterId) === null || _a === void 0 ? void 0 : _a.toString()) || ""};c=${request.includeCoveringShifts ? 1 : 0}`;
+        }
+        else {
+            filters = `g=${request.includeCoverageGaps ? 1 : 0};m=${request.minimumGapMinutes}`;
+        }
+        return [
+            request.kind,
+            request.tokenHash,
+            filters,
+            `w=${data.pastDays}/${data.futureDays}`,
+        ].join(":");
+    }
+    static digestOf(value) {
+        return createHash("sha256")
+            .update(value, "utf8")
+            .digest("hex")
+            .slice(0, 24);
+    }
+    /*
+     * `${identity}:${digest(scheduleIds+versions)}:${day}`.
+     * The candidate set and every shiftConfigVersion are read from Postgres on
+     * each request, so any configuration edit changes the key immediately --
+     * no counters to lose. The day bucket rolls the window at UTC midnight.
+     */
+    static buildBodyCacheKey(data) {
+        const versions = data.schedules
+            .map((schedule) => {
+            return `${schedule.id.toString()}@${schedule.shiftConfigVersion}`;
+        })
+            .sort()
+            .join(",");
+        return [
+            OnCallCalendarFeedRenderer.buildFeedIdentityKey(data),
+            OnCallCalendarFeedRenderer.digestOf(versions),
+            CalendarFeedWindow.getUtcDayBucket(data.now),
+        ].join(":");
+    }
+    /*
+     * The key of the stale-while-error tier: `${identity}:${digest(scheduleIds)}`
+     * -- deliberately NOT the body key.
+     *
+     * The body key carries every schedule's shiftConfigVersion and the UTC day
+     * bucket, both of which change constantly: every layer/override/attachment
+     * edit bumps a version, and every feed's day bucket rolls at midnight UTC.
+     * Keying the last-good body on those meant the fallback existed only until
+     * the next edit or the next midnight -- and those are exactly the moments
+     * it is needed, because they are also when every subscriber's body cache
+     * misses at once and the four render slots are scarcest. The result was a
+     * 503 (which some clients answer by dropping the subscription) with a
+     * perfectly good body sitting one key away.
+     *
+     * The SORTED SCHEDULE-ID SET stays in the key. That is the authorisation
+     * property: a body rendered when the user was on schedules {A, B} can never
+     * be served after they are removed from B, because the key is different.
+     * The token hash is in it too, so a rotated token never reaches an old body.
+     * What is dropped is only "the roster changed" and "the day rolled", which
+     * is precisely what "stale" means.
+     */
+    static buildLastGoodCacheKey(data) {
+        const ids = data.schedules
+            .map((schedule) => {
+            return schedule.id.toString();
+        })
+            .sort()
+            .join(",");
+        return [
+            OnCallCalendarFeedRenderer.buildFeedIdentityKey(data),
+            OnCallCalendarFeedRenderer.digestOf(ids),
+        ].join(":");
+    }
+    // -- Context (authorization, re-derived per fetch) ----------------------
+    static async resolveContext(request, window) {
+        switch (request.kind) {
+            case OnCallCalendarFeedKind.Personal:
+                return await OnCallCalendarFeedRenderer.resolvePersonalContext(request, window);
+            case OnCallCalendarFeedKind.Schedule:
+                return await OnCallCalendarFeedRenderer.resolveScheduleContext(request);
+            case OnCallCalendarFeedKind.Project:
+                return await OnCallCalendarFeedRenderer.resolveProjectContext(request);
+            default:
+                return { empty: true, reason: USER_MISSING_REASON };
+        }
+    }
+    static async resolvePersonalContext(request, window) {
+        const user = await UserService.findOneById({
+            id: request.userId,
+            select: {
+                _id: true,
+                timezone: true,
+            },
+            props: {
+                isRoot: true,
+                ignoreHooks: true,
+            },
+        });
+        if (!user) {
+            return { empty: true, reason: USER_MISSING_REASON };
+        }
+        const viewerTimezone = user.timezone
+            ? user.timezone.toString()
+            : undefined;
+        if (!(await OnCallCalendarFeedRenderer.isProjectOnPlan(request.projectId))) {
+            return { empty: true, reason: PLAN_REASON, timezone: viewerTimezone };
+        }
+        const candidateIds = await OnCallShiftMaterializer.getCandidateScheduleIdsForUser({
+            userId: request.userId,
+            projectIds: [request.projectId],
+            scheduleId: request.scheduleFilterId,
+            windowStart: window.feedStart,
+            windowEnd: window.feedEnd,
+            includeCoveringShifts: request.includeCoveringShifts,
+        });
+        let filterScheduleName = undefined;
+        if (request.scheduleFilterId) {
+            const filtered = await OnCallCalendarFeedRenderer.loadSchedules([
+                request.scheduleFilterId,
+            ]);
+            const candidate = filtered[0];
+            /*
+             * loadSchedules is a root read by id, and the id came from the query
+             * string. The name goes into X-WR-CALNAME/X-WR-CALDESC of a 200 body,
+             * so naming a schedule that belongs to another project would turn any
+             * personal feed link into an id-to-name oracle across tenants. Only a
+             * schedule in the token's own project is ever named.
+             */
+            if (candidate &&
+                candidate.projectId.toString() === request.projectId.toString()) {
+                filterScheduleName = candidate.name;
+            }
+        }
+        if (candidateIds.length === 0) {
+            return {
+                empty: true,
+                reason: request.scheduleFilterId
+                    ? FILTERED_SCHEDULE_REASON
+                    : NO_SCHEDULES_REASON,
+                filterScheduleName,
+                timezone: viewerTimezone,
+            };
+        }
+        const schedules = (await OnCallCalendarFeedRenderer.loadSchedules(candidateIds)).filter((schedule) => {
+            /*
+             * Belt and braces: the candidate query was scoped to the project, but
+             * a schedule row from another project must never render under this
+             * project's token.
+             */
+            return schedule.projectId.toString() === request.projectId.toString();
+        });
+        if (schedules.length === 0) {
+            return {
+                empty: true,
+                reason: request.scheduleFilterId
+                    ? FILTERED_SCHEDULE_REASON
+                    : NO_SCHEDULES_REASON,
+                filterScheduleName,
+                timezone: viewerTimezone,
+            };
+        }
+        return {
+            empty: false,
+            schedules,
+            viewerTimezone,
+            calendarTimezone: viewerTimezone,
+            filterScheduleName,
+        };
+    }
+    static async resolveScheduleContext(request) {
+        const schedules = await OnCallCalendarFeedRenderer.loadSchedules([request.scheduleId]);
+        const schedule = schedules[0];
+        if (!schedule ||
+            schedule.projectId.toString() !== request.projectId.toString()) {
+            return { empty: true, reason: SCHEDULE_MISSING_REASON };
+        }
+        if (!(await OnCallCalendarFeedRenderer.isProjectOnPlan(request.projectId))) {
+            return {
+                empty: true,
+                reason: PLAN_REASON,
+                scheduleName: schedule.name,
+                timezone: schedule.timezone,
+            };
+        }
+        return {
+            empty: false,
+            schedules: [schedule],
+            scheduleName: schedule.name,
+            calendarTimezone: schedule.timezone,
+        };
+    }
+    static async resolveProjectContext(request) {
+        const project = await ProjectService.findOneById({
+            id: request.projectId,
+            select: {
+                _id: true,
+                name: true,
+            },
+            props: {
+                isRoot: true,
+                ignoreHooks: true,
+            },
+        });
+        if (!project) {
+            return { empty: true, reason: PROJECT_MISSING_REASON };
+        }
+        const projectName = project.name || undefined;
+        if (!(await OnCallCalendarFeedRenderer.isProjectOnPlan(request.projectId))) {
+            return { empty: true, reason: PLAN_REASON, projectName };
+        }
+        const rows = await OnCallDutyPolicyScheduleService.findBy({
+            query: {
+                projectId: request.projectId,
+            },
+            select: OnCallCalendarFeedRenderer.scheduleSelect(),
+            limit: LIMIT_PER_PROJECT,
+            skip: 0,
+            sort: {
+                name: SortOrder.Ascending,
+            },
+            props: {
+                isRoot: true,
+                ignoreHooks: true,
+            },
+        });
+        const schedules = OnCallCalendarFeedRenderer.toScheduleInfos(rows);
+        if (schedules.length === 0) {
+            return { empty: true, reason: NO_PROJECT_SCHEDULES_REASON, projectName };
+        }
+        return {
+            empty: false,
+            schedules,
+            projectName,
+        };
+    }
+    // -- Helpers -----------------------------------------------------------
+    static scheduleSelect() {
+        return {
+            _id: true,
+            name: true,
+            timezone: true,
+            projectId: true,
+            shiftConfigVersion: true,
+        };
+    }
+    /*
+     * Root read of the schedule facts the render needs (name, zone, project,
+     * shiftConfigVersion). Input order is preserved; unknown ids are dropped.
+     */
+    static async loadSchedules(ids) {
+        if (ids.length === 0) {
+            return [];
+        }
+        const rows = await OnCallDutyPolicyScheduleService.findBy({
+            query: {
+                _id: QueryHelper.any(ids),
+            },
+            select: OnCallCalendarFeedRenderer.scheduleSelect(),
+            limit: LIMIT_PER_PROJECT,
+            skip: 0,
+            props: {
+                isRoot: true,
+                ignoreHooks: true,
+            },
+        });
+        const byId = new Map();
+        for (const info of OnCallCalendarFeedRenderer.toScheduleInfos(rows)) {
+            byId.set(info.id.toString(), info);
+        }
+        const ordered = [];
+        for (const id of ids) {
+            const info = byId.get(id.toString());
+            if (info && !ordered.includes(info)) {
+                ordered.push(info);
+            }
+        }
+        return ordered;
+    }
+    static toScheduleInfos(rows) {
+        const infos = [];
+        for (const row of rows) {
+            if (!row.id || !row.projectId) {
+                continue;
+            }
+            const timezone = row.timezone
+                ? row.timezone.toString()
+                : undefined;
+            const info = {
+                id: row.id,
+                name: row.name || "",
+                projectId: row.projectId,
+                shiftConfigVersion: typeof row.shiftConfigVersion === "number" &&
+                    Number.isFinite(row.shiftConfigVersion)
+                    ? row.shiftConfigVersion
+                    : Number(row.shiftConfigVersion) || 0,
+            };
+            if (timezone) {
+                info.timezone = timezone;
+            }
+            infos.push(info);
+        }
+        return infos;
+    }
+    /*
+     * Every cached shift of every schedule as MaterializedShift objects, with
+     * isPast re-evaluated against THIS request's clock (a schedule entry can be
+     * up to an hour old).
+     */
+    static collectShifts(segments, now) {
+        const shifts = [];
+        for (const segment of segments) {
+            for (const shift of MaterializedShiftUtil.fromJSONArray(segment.shifts)) {
+                shift.isPast = shift.start.getTime() < now.getTime();
+                shifts.push(shift);
+            }
+        }
+        return MaterializedShiftUtil.sortByStart(shifts);
+    }
+    static buildGapEvents(data) {
+        const collected = [];
+        let truncated = false;
+        const minimumGapSeconds = Math.max(0, Math.floor(data.minimumGapMinutes)) * 60;
+        for (const segment of data.segments) {
+            const shifts = segment.shifts.map((shift) => {
+                return {
+                    start: new Date(shift.start),
+                    end: new Date(shift.end),
+                };
+            });
+            const envelope = segment.envelope.map((window) => {
+                return { start: new Date(window.start), end: new Date(window.end) };
+            });
+            const result = OnCallCalendarFeedUtil.buildCoverageGapEvents({
+                scheduleId: segment.scheduleId,
+                scheduleName: segment.scheduleName,
+                projectId: segment.projectId,
+                shifts,
+                feedStart: data.feedStart,
+                feedEnd: data.feedEnd,
+                envelope,
+                minimumGapSeconds,
+                lastModifiedAt: new Date(segment.lastModifiedAt),
+                shiftConfigVersion: segment.shiftConfigVersion,
+                dashboardUrl: data.dashboardUrl,
+                maxGapEvents: MAX_GAP_EVENTS,
+            });
+            truncated = truncated || result.truncated;
+            collected.push(...result.events);
+        }
+        collected.sort((a, b) => {
+            return a.start.getTime() - b.start.getTime();
+        });
+        if (collected.length > MAX_GAP_EVENTS) {
+            return { events: collected.slice(0, MAX_GAP_EVENTS), truncated: true };
+        }
+        return { events: collected, truncated };
+    }
+    static async fallBackToLastGood(data) {
+        const lastGood = await OnCallCalendarFeedCache.getLastGood(data.lastGoodKey);
+        if (lastGood) {
+            logger.warn(`OnCallCalendarFeedRenderer: ${data.why}; serving the last good ${data.kind} feed body.`);
+            return OnCallCalendarFeedRenderer.outcomeFromCachedBody({
+                kind: data.kind,
+                cached: lastGood,
+                stale: true,
+                cacheHit: false,
+                truncated: true,
+            });
+        }
+        logger.warn(`OnCallCalendarFeedRenderer: ${data.why} and nothing is cached for this ${data.kind} feed; answering unavailable.`);
+        return OnCallCalendarFeedRenderer.buildUnavailableOutcome(data.kind, RENDER_CAP_RETRY_AFTER_SECONDS);
+    }
+    static recordMetrics(data) {
+        try {
+            const attributes = {
+                [AppMetrics.ON_CALL_CALENDAR_FEED_KIND_ATTRIBUTE]: OnCallCalendarFeedUrls.getKindSegment(data.kind),
+            };
+            AppMetrics.getOnCallCalendarRenderDuration().record(data.durationMs, attributes);
+            AppMetrics.getOnCallCalendarRenderEvents().record(data.eventCount, attributes);
+        }
+        catch (err) {
+            logger.debug(`OnCallCalendarFeedRenderer: metrics unavailable (${String(err)})`);
+        }
+    }
+    /* VEVENT count of a serialized body, for outcomes rebuilt from a cache. */
+    static countEvents(body) {
+        return (body.match(/BEGIN:VEVENT/g) || []).length;
+    }
+}
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ObjectID, Object]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "isProjectOnPlan", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "render", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "materializeUserShifts", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "loadScheduleSegments", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "loadScheduleSegmentsBatch", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array]),
+    __metadata("design:returntype", Promise)
+], OnCallCalendarFeedRenderer, "loadSchedules", null);
+//# sourceMappingURL=OnCallCalendarFeedRenderer.js.map