@remit/calendar-service 0.0.18 → 0.0.20

package/src/expand.ts

@@ -1,303 +0,0 @@
-import type { CalendarOccurrenceInput } from "@remit/data-ports";
-import ICAL from "ical.js";
-import type { ParsedCalendar } from "./parse.js";
-import { hasRecurrence, projectEventDisplay } from "./project.js";
-import {
-	dtEndTzid,
-	dtStartTzid,
-	resolveTime,
-	toUtcIso,
-	tzidOf,
-} from "./time.js";
-
-/**
- * How far past a series' own start its occurrences are written out.
- *
- * A recurring event may have no end at all, so something has to bound the
- * write. Two years covers every view a client asks for today and keeps the
- * index one bounded write rather than an unbounded one; a resource whose series
- * runs past it is marked with `expandedThrough` and stays the business of the
- * live expansion that reads it.
- */
-export const CALENDAR_EXPANSION_HORIZON_DAYS = 730;
-
-/**
- * Ceiling on occurrences written for one resource, independent of the horizon.
- * A per-minute RRULE fits three quarters of a million instances inside two
- * years; the ceiling turns that into a marked, truncated index instead of a
- * write that takes the process down.
- */
-export const CALENDAR_EXPANSION_MAX_OCCURRENCES = 1000;
-
-/**
- * Ceiling on iterator steps a live window expansion may take.
- *
- * A window expansion walks the series from its own start, because a rule is
- * only meaningful from where it was anchored. A daily event written in 2005 is
- * a few thousand steps away from today, which is cheap; a per-minute one is
- * millions, which is a read that never returns. The cap turns the second case
- * into a short answer rather than a hung request.
- */
-export const CALENDAR_WINDOW_MAX_STEPS = 50_000;
-
-const HORIZON_MS = CALENDAR_EXPANSION_HORIZON_DAYS * 24 * 60 * 60 * 1000;
-
-export interface CalendarExpansion {
-	occurrences: CalendarOccurrenceInput[];
-	/**
-	 * The instant through which `occurrences` is complete, or `""` when it holds
-	 * the whole series.
-	 */
-	expandedThrough: string;
-}
-
-const occurrenceOf = (
-	collectionTimezone: string,
-	recurrenceId: string,
-	source: ICAL.Component,
-	startDate: ICAL.Time,
-	endDate: ICAL.Time,
-	startTzid: string,
-	endTzid: string,
-): CalendarOccurrenceInput => {
-	const start = resolveTime(startDate, startTzid, collectionTimezone);
-	const end = resolveTime(endDate, endTzid, collectionTimezone);
-	return {
-		recurrenceId,
-		startAt: start.isoUtc,
-		endAt: end.isoUtc,
-		allDay: start.isDate,
-		...projectEventDisplay(source),
-	};
-};
-
-/**
- * The slot each override claims, canonicalized the way the iterator's slots
- * are, so the two can be compared at all.
- */
-export const overridesBySlot = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-): Map<string, ICAL.Component> => {
-	const bySlot = new Map<string, ICAL.Component>();
-	for (const override of calendar.overrides) {
-		const recurrenceId = override.getFirstPropertyValue("recurrence-id");
-		if (!(recurrenceId instanceof ICAL.Time)) continue;
-		const slot = resolveTime(
-			recurrenceId,
-			tzidOf(override.getFirstProperty("recurrence-id")),
-			collectionTimezone,
-		).isoUtc;
-		bySlot.set(slot, override);
-	}
-	return bySlot;
-};
-
-/** The window a walk collects occurrences in, and what bounds the walk. */
-interface WalkBounds {
-	/** Occurrences starting before this are stepped past, not collected. */
-	fromMs: number;
-	/** The walk stops once a slot starts after this. */
-	throughMs: number;
-	maxOccurrences: number;
-	maxSteps: number;
-}
-
-interface Walk {
-	occurrences: CalendarOccurrenceInput[];
-	/** Whether the walk stopped on a bound rather than on the series ending. */
-	truncated: boolean;
-	/** Start of the last slot the walk collected, or `""` when it collected none. */
-	lastIteratedStart: string;
-}
-
-/**
- * Walks a recurring resource's occurrences between the bounds it is given.
- *
- * EXDATEs are ical.js's business — `ICAL.Event` skips them. Overrides are not
- * left entirely to it: the iterator yields the master's own RRULE and RDATE
- * slots, so an override whose RECURRENCE-ID names a slot the rule never
- * produces — the shape a client writes after moving one instance and then
- * editing the rule — would never be reached. Those are walked explicitly, so
- * every VEVENT in the resource is an occurrence somebody can find.
- */
-const walkOccurrences = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-	bounds: WalkBounds,
-): Walk => {
-	const event = new ICAL.Event(calendar.master);
-	for (const override of calendar.overrides) {
-		event.relateException(override);
-	}
-
-	const overrideBySlot = overridesBySlot(calendar, collectionTimezone);
-	const masterStartTzid = dtStartTzid(calendar.master);
-	const occurrences: CalendarOccurrenceInput[] = [];
-	const claimed = new Set<string>();
-	const iterator = event.iterator();
-	let truncated = false;
-	let steps = 0;
-	let lastIteratedStart = "";
-
-	let next = iterator.next();
-	while (next) {
-		const slot = resolveTime(next, masterStartTzid, collectionTimezone);
-		if (
-			slot.instantMs > bounds.throughMs ||
-			occurrences.length >= bounds.maxOccurrences ||
-			steps >= bounds.maxSteps
-		) {
-			truncated = true;
-			break;
-		}
-		steps += 1;
-		claimed.add(slot.isoUtc);
-
-		if (slot.instantMs >= bounds.fromMs) {
-			// An overridden slot hands back the override's own DTSTART and DTEND, so
-			// the zones to read them in are the override's. A plain slot hands back
-			// the rule's start and an end derived from the master's duration, both in
-			// the master's start zone.
-			const source = overrideBySlot.get(slot.isoUtc);
-			const details = event.getOccurrenceDetails(next);
-			occurrences.push(
-				occurrenceOf(
-					collectionTimezone,
-					slot.isoUtc,
-					source ?? calendar.master,
-					details.startDate,
-					details.endDate,
-					dtStartTzid(source ?? calendar.master),
-					source ? dtEndTzid(source) : masterStartTzid,
-				),
-			);
-			lastIteratedStart = occurrences[occurrences.length - 1]?.startAt ?? "";
-		}
-		next = iterator.next();
-	}
-
-	// Overrides the rule never reached. Kept regardless of the horizon: they are
-	// a bounded, explicit list, and one moved instance is exactly the thing a
-	// user goes looking for.
-	for (const [slot, override] of overrideBySlot) {
-		if (claimed.has(slot)) continue;
-		const overrideEvent = new ICAL.Event(override);
-		const occurrence = occurrenceOf(
-			collectionTimezone,
-			slot,
-			override,
-			overrideEvent.startDate,
-			overrideEvent.endDate,
-			dtStartTzid(override),
-			dtEndTzid(override),
-		);
-		const startMs = Date.parse(occurrence.startAt);
-		if (startMs < bounds.fromMs || startMs > bounds.throughMs) continue;
-		occurrences.push(occurrence);
-	}
-
-	occurrences.sort((left, right) => left.startAt.localeCompare(right.startAt));
-
-	return { occurrences, truncated, lastIteratedStart };
-};
-
-/** The one occurrence a resource that does not recur produces. */
-const singleOccurrence = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-): CalendarOccurrenceInput => {
-	const event = new ICAL.Event(calendar.master);
-	return occurrenceOf(
-		collectionTimezone,
-		"",
-		calendar.master,
-		event.startDate,
-		event.endDate,
-		dtStartTzid(calendar.master),
-		dtEndTzid(calendar.master),
-	);
-};
-
-/**
- * Flattens a resource into the occurrence rows a date-range read returns.
- *
- * A non-recurring resource is one row under an empty `recurrenceId`. A
- * recurring one is a row per occurrence, each keyed by its RECURRENCE-ID slot
- * as a UTC instant — the same canonical form an override's own RECURRENCE-ID
- * resolves to, so an override lands on the occurrence it replaces instead of
- * beside it.
- *
- * The horizon is anchored at the series' own start, not at today: two years of
- * a series is a bounded write whatever a caller's clock says. A series running
- * past it comes back marked with `expandedThrough`, which is what tells a later
- * read to expand that resource live instead of trusting the index.
- */
-export const expandCalendar = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-): CalendarExpansion => {
-	if (!hasRecurrence(calendar)) {
-		return {
-			occurrences: [singleOccurrence(calendar, collectionTimezone)],
-			expandedThrough: "",
-		};
-	}
-
-	const event = new ICAL.Event(calendar.master);
-	const seriesStart = resolveTime(
-		event.startDate,
-		dtStartTzid(calendar.master),
-		collectionTimezone,
-	).instantMs;
-
-	const walk = walkOccurrences(calendar, collectionTimezone, {
-		fromMs: Number.NEGATIVE_INFINITY,
-		throughMs: seriesStart + HORIZON_MS,
-		maxOccurrences: CALENDAR_EXPANSION_MAX_OCCURRENCES,
-		maxSteps: Number.POSITIVE_INFINITY,
-	});
-
-	// Every truncated walk is marked, including one that collected nothing — a
-	// series whose first occurrence lands past the horizon. Its index is empty
-	// from the series start, which is the honest floor to write; `""` would
-	// claim the whole series is held and the live expansion would never run.
-	return {
-		occurrences: walk.occurrences,
-		expandedThrough: walk.truncated
-			? toUtcIso(
-					walk.lastIteratedStart
-						? Date.parse(walk.lastIteratedStart)
-						: seriesStart,
-				)
-			: "",
-	};
-};
-
-/**
- * The occurrences of a resource that fall inside one window, computed rather
- * than read.
- *
- * This is what serves a view of a series whose stored index stops before the
- * window — an open-ended weekly meeting written years ago, whose horizon ran
- * out long before today. The alternative is extending the index on read, which
- * turns every view of an old series into an unbounded write; a bounded
- * computation that persists nothing is the cheaper half of that trade, and the
- * one that cannot leave anything behind to be wrong later.
- */
-export const expandCalendarWindow = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-	window: { fromMs: number; toMs: number },
-): CalendarOccurrenceInput[] => {
-	if (!hasRecurrence(calendar)) {
-		return [singleOccurrence(calendar, collectionTimezone)];
-	}
-
-	return walkOccurrences(calendar, collectionTimezone, {
-		fromMs: window.fromMs,
-		throughMs: window.toMs,
-		maxOccurrences: CALENDAR_EXPANSION_MAX_OCCURRENCES,
-		maxSteps: CALENDAR_WINDOW_MAX_STEPS,
-	}).occurrences;
-};

package/src/feed.test.ts

@@ -1,334 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type {
-	CalendarCollectionItem,
-	CalendarObjectItem,
-} from "@remit/data-ports";
-import {
-	buildCalendarFeed,
-	CALENDAR_FEED_TOKEN_BYTES,
-	calendarFeedIsUnchanged,
-	calendarFeedIsUnmodifiedSince,
-	hashCalendarFeedToken,
-	isCalendarFeedToken,
-	mintCalendarFeedToken,
-	readCalendarFeedToken,
-	redactCalendarFeedPath,
-} from "./feed.js";
-import { AMSTERDAM_VTIMEZONE, ical, singleEvent } from "./fixtures.js";
-
-const collection = (
-	overrides: Partial<CalendarCollectionItem> = {},
-): CalendarCollectionItem =>
-	({
-		calendarId: "cal-1",
-		accountConfigId: "acc-1",
-		urlSegment: "work",
-		displayName: "Work",
-		color: "Cal1",
-		componentSet: "VeventOnly",
-		source: "UserCreated",
-		timezone: "",
-		syncSequence: 3,
-		createdAt: 1_700_000_000_000,
-		updatedAt: 1_700_000_000_000,
-		...overrides,
-	}) as CalendarCollectionItem;
-
-const object = (
-	resourceName: string,
-	icalData: string,
-	updatedAt = 1_700_000_100_000,
-): CalendarObjectItem =>
-	({
-		calendarObjectId: `obj-${resourceName}`,
-		calendarId: "cal-1",
-		resourceName,
-		icalData,
-		updatedAt,
-	}) as CalendarObjectItem;
-
-/** Content lines as a subscriber reads them, with RFC 5545 3.1 folding undone. */
-const unfolded = (icalData: string): string =>
-	icalData.replace(/\r\n[ \t]/g, "");
-
-describe("a feed token", () => {
-	it("is base64url over the declared number of random bytes", () => {
-		const minted = mintCalendarFeedToken();
-
-		assert.equal(
-			Buffer.from(minted.token, "base64url").length,
-			CALENDAR_FEED_TOKEN_BYTES,
-		);
-		assert.ok(isCalendarFeedToken(minted.token));
-		assert.equal(minted.tokenHash, hashCalendarFeedToken(minted.token));
-		assert.equal(minted.tokenHash.length, 64);
-		assert.equal(
-			minted.tokenHash.includes(minted.token),
-			false,
-			"the stored value is a digest, not the secret",
-		);
-	});
-
-	it("is never the same twice", () => {
-		const minted = new Set(
-			Array.from({ length: 64 }, () => mintCalendarFeedToken().token),
-		);
-
-		assert.equal(minted.size, 64);
-	});
-
-	it("refuses anything that is not the shape of one", () => {
-		for (const candidate of [
-			"",
-			"short",
-			"a".repeat(42),
-			"a".repeat(44),
-			`${"a".repeat(42)}/`,
-			`${"a".repeat(42)}.`,
-			"../../etc/passwd",
-		]) {
-			assert.equal(isCalendarFeedToken(candidate), false, candidate);
-		}
-	});
-});
-
-describe("a feed address", () => {
-	it("reads back the token it was written from", () => {
-		const minted = mintCalendarFeedToken();
-
-		assert.equal(
-			readCalendarFeedToken(`/feeds/calendar/${minted.token}.ics`),
-			minted.token,
-		);
-	});
-
-	it("is not a feed address without the path and the suffix", () => {
-		assert.equal(readCalendarFeedToken("/feeds/calendar/abc"), null);
-		assert.equal(readCalendarFeedToken("/calendars/abc.ics"), null);
-		assert.equal(readCalendarFeedToken("/feeds/calendar/a/b.ics"), null);
-	});
-});
-
-describe("the calendar a feed serves", () => {
-	it("names itself from the collection and terminates its last line", () => {
-		const feed = buildCalendarFeed(collection({ displayName: "Team" }), [
-			object(
-				"a.ics",
-				singleEvent("SUMMARY:Stand-up", "DTSTART:20260907T090000Z"),
-			),
-		]);
-
-		assert.match(feed.icalData, /^BEGIN:VCALENDAR\r\n/);
-		assert.match(feed.icalData, /X-WR-CALNAME:Team\r\n/);
-		assert.match(feed.icalData, /END:VCALENDAR\r\n$/);
-		assert.match(feed.icalData, /SUMMARY:Stand-up/);
-	});
-
-	it("escapes the separators a name may carry", () => {
-		const feed = buildCalendarFeed(
-			collection({ displayName: "Work, Home; C:\\shared" }),
-			[],
-		);
-
-		assert.match(
-			unfolded(feed.icalData),
-			/X-WR-CALNAME:Work\\, Home\\; C:\\\\shared\r\n/,
-		);
-	});
-
-	it("cannot be made to smuggle a component through its name", () => {
-		const feed = buildCalendarFeed(
-			collection({
-				displayName:
-					"Work\r\nBEGIN:VEVENT\r\nUID:injected\r\nDTSTART:20250101T000000Z\r\nSUMMARY:pwned\r\nEND:VEVENT",
-			}),
-			[
-				object(
-					"a.ics",
-					singleEvent("SUMMARY:Stand-up", "DTSTART:20260907T090000Z"),
-				),
-			],
-		);
-		const served = unfolded(feed.icalData);
-
-		assert.equal(served.match(/^BEGIN:VEVENT\r\n/gm)?.length, 1);
-		assert.doesNotMatch(served, /^UID:injected/m);
-		assert.doesNotMatch(served, /^SUMMARY:pwned/m);
-		assert.match(served, /X-WR-CALNAME:Work\\nBEGIN:VEVENT\\nUID:injected/);
-	});
-
-	it("leaves no bare carriage return in what it serves", () => {
-		const feed = buildCalendarFeed(
-			collection({ displayName: "Work\rHome" }),
-			[],
-		);
-
-		assert.match(unfolded(feed.icalData), /X-WR-CALNAME:Work\\nHome\r\n/);
-		assert.doesNotMatch(feed.icalData, /\r(?!\n)/);
-	});
-
-	it("carries the collection's zone so a client reads floating times the same way", () => {
-		const feed = buildCalendarFeed(
-			collection({ timezone: "Europe/Amsterdam" }),
-			[],
-		);
-
-		assert.match(feed.icalData, /X-WR-TIMEZONE:Europe\/Amsterdam\r\n/);
-	});
-
-	it("keeps the rule rather than the occurrences it would produce", () => {
-		const feed = buildCalendarFeed(collection(), [
-			object(
-				"a.ics",
-				singleEvent(
-					"SUMMARY:Weekly",
-					"DTSTART:20260907T090000Z",
-					"RRULE:FREQ=WEEKLY;COUNT=5",
-				),
-			),
-		]);
-
-		assert.equal(feed.icalData.match(/BEGIN:VEVENT/g)?.length, 1);
-		assert.match(feed.icalData, /RRULE:FREQ=WEEKLY;COUNT=5/);
-	});
-
-	it("carries one copy of a VTIMEZONE two resources both declare", () => {
-		const withZone = (uid: string) =>
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"PRODID:-//Remit//Calendar Tests//EN",
-				...AMSTERDAM_VTIMEZONE,
-				"BEGIN:VEVENT",
-				`UID:${uid}`,
-				"DTSTAMP:20260801T090000Z",
-				"DTSTART;TZID=Europe/Amsterdam:20260907T090000",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			);
-
-		const feed = buildCalendarFeed(collection(), [
-			object("a.ics", withZone("a@example.com")),
-			object("b.ics", withZone("b@example.com")),
-		]);
-
-		assert.equal(feed.icalData.match(/BEGIN:VTIMEZONE/g)?.length, 1);
-		assert.equal(feed.icalData.match(/BEGIN:VEVENT/g)?.length, 2);
-	});
-
-	it("declares one VERSION however many resources it gathered", () => {
-		const feed = buildCalendarFeed(collection(), [
-			object("a.ics", singleEvent("DTSTART:20260907T090000Z")),
-			object("b.ics", singleEvent("DTSTART:20260908T090000Z")),
-		]);
-
-		assert.equal(feed.icalData.match(/^VERSION:/gm)?.length, 1);
-		assert.equal(feed.icalData.match(/^PRODID:/gm)?.length, 1);
-	});
-
-	it("moves its tag when the bytes change and holds it when they do not", () => {
-		const one = object("a.ics", singleEvent("DTSTART:20260907T090000Z"));
-		const two = object("b.ics", singleEvent("DTSTART:20260908T090000Z"));
-
-		const first = buildCalendarFeed(collection(), [one]);
-		const again = buildCalendarFeed(collection(), [one]);
-		const grown = buildCalendarFeed(collection(), [one, two]);
-		const renamed = buildCalendarFeed(collection({ displayName: "Team" }), [
-			one,
-		]);
-
-		assert.equal(again.etag, first.etag);
-		assert.notEqual(grown.etag, first.etag);
-		assert.notEqual(renamed.etag, first.etag);
-	});
-
-	it("carries no modification time of its own", () => {
-		// The newest surviving event is not when the calendar last changed: a
-		// delete removes the newest one and leaves every survivor older than the
-		// change. The collection's own timestamp is what the feed serves, and it
-		// belongs to the store rather than to these bytes (issue #1067).
-		const feed = buildCalendarFeed(collection({ updatedAt: 500 }), [
-			object("a.ics", singleEvent("DTSTART:20260907T090000Z"), 900),
-		]);
-
-		assert.deepEqual(Object.keys(feed).sort(), ["etag", "icalData"]);
-	});
-});
-
-describe("a conditional poll", () => {
-	it("is unchanged for the tag it holds, quoted, weak or in a list", () => {
-		for (const header of ['"abc"', "abc", 'W/"abc"', '"other", "abc"', "*"]) {
-			assert.ok(calendarFeedIsUnchanged(header, "abc"), String(header));
-		}
-	});
-
-	it("is changed with no header, an empty one, or somebody else's tag", () => {
-		for (const header of [undefined, "", '"other"', 'W/"other"']) {
-			assert.equal(
-				calendarFeedIsUnchanged(header, "abc"),
-				false,
-				String(header),
-			);
-		}
-	});
-});
-
-describe("a feed path in a log line", () => {
-	it("keeps the route and drops the token", () => {
-		const minted = mintCalendarFeedToken();
-
-		const redacted = redactCalendarFeedPath(
-			`/feeds/calendar/${minted.token}.ics`,
-		);
-
-		assert.equal(redacted.includes(minted.token), false);
-		assert.equal(redacted, "/feeds/calendar/<redacted>.ics");
-	});
-
-	it("leaves a path that carries no token alone", () => {
-		for (const path of [
-			"/calendars/abc",
-			"/feeds/calendar/no-suffix",
-			"/health",
-		]) {
-			assert.equal(redactCalendarFeedPath(path), path, path);
-		}
-	});
-});
-
-describe("a poll carrying a date", () => {
-	const lastModified = Date.UTC(2026, 8, 7, 9, 0, 0);
-
-	it("is unmodified for the second it was last written in", () => {
-		// Last-Modified went out truncated to the second, so the value that comes
-		// back is 750ms behind the stored timestamp and still means "the copy I
-		// have is the one you served".
-		assert.ok(
-			calendarFeedIsUnmodifiedSince(
-				new Date(lastModified).toUTCString(),
-				lastModified + 750,
-			),
-		);
-	});
-
-	it("is modified once the calendar moves into a later second", () => {
-		assert.equal(
-			calendarFeedIsUnmodifiedSince(
-				new Date(lastModified).toUTCString(),
-				lastModified + 1000,
-			),
-			false,
-		);
-	});
-
-	it("is not a condition when the date is absent or unreadable", () => {
-		for (const header of [undefined, "", "whenever"]) {
-			assert.equal(
-				calendarFeedIsUnmodifiedSince(header, lastModified),
-				false,
-				String(header),
-			);
-		}
-	});
-});