dsh-model-pool 0.0.0-stage → 0.1.0

package/lib/holiday-calendar.js

@@ -0,0 +1,595 @@
+/**
+* The Chinese statutory holiday calendar, fetched and cached.
+*
+* A worked calendar cannot be derived from a rule: the State Council shifts workdays
+* around every year (调休), so the only honest sources are the published annual notices.
+* This module reads a maintained machine-readable version of those notices, caches it on
+* disk, and hands the router plain date sets.
+*
+* ## Why a data source and not a table
+*
+* A hard-coded table silently rots: the year it was not written for is simply wrong, and
+* nothing reports that. Fetching means the table is refreshed by whoever maintains the
+* dataset, and an unpublished year is an explicit, expected state rather than a bug.
+*
+* ## Offline is a first-class state
+*
+* Routing must never block on, or fail because of, the network. Every caller reads
+* `holidays()` / `makeupWorkdays()` from memory; `refresh()` is the only thing that
+* touches I/O, it is always cache-first, and it never throws.
+*
+* @module dsh-model-pool/lib/holiday-calendar
+*/
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Source id to the URLs tried in order.
+ *
+ * Three independent mirrors, because any one of them can be slow or blocked depending on
+ * the network: jsDelivr's main CDN, jsDelivr's Fastly endpoint, then GitHub itself. The
+ * first that answers wins.
+ */
+export const DEFAULT_SOURCE_URLS = {
+	'holiday-cn': [
+		'https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json',
+		'https://fastly.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json',
+		'https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json',
+	],
+};
+
+/** Cache file name inside the data directory. */
+const CACHE_FILE = 'calendar.json';
+
+/** How many years of history to load alongside the current one. */
+const HISTORY_YEARS = 1;
+
+/** Network budget for one year's document. */
+const FETCH_TIMEOUT_MS = 8000;
+
+/** Shape version of the on-disk cache. */
+const CACHE_VERSION = 1;
+
+/** A `YYYY-MM-DD` calendar date, validated the same way `lib/peak.js` validates one. */
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+* Whether a string is a real calendar date in `YYYY-MM-DD` form.
+* @param value - candidate value.
+* @returns true for a date such as `2026-02-17`.
+*/
+function isDate(value) {
+	if (typeof value !== 'string' || !DATE_RE.test(value)) return false;
+	const year = Number(value.slice(0, 4));
+	const month = Number(value.slice(5, 7));
+	const day = Number(value.slice(8, 10));
+	if (month < 1 || month > 12 || day < 1 || day > 31) return false;
+	const probe = new Date(Date.UTC(year, month - 1, day));
+	return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+}
+
+/**
+* Parse one year's source document.
+*
+* The document is untrusted: it arrives over the network. Every entry is validated and
+* unusable ones are dropped, so a corrupted or truncated response degrades to "fewer
+* known holidays" instead of a wrong answer or an exception in the router.
+*
+* @param raw - the parsed JSON body, or a JSON string.
+* @returns `{ year, papers, days }` with `days` holding only well-formed entries.
+* @throws when the document is not a usable calendar at all.
+*/
+export function parseSourceDocument(raw) {
+	const doc = typeof raw === 'string' ? JSON.parse(raw) : raw;
+	if (doc === null || typeof doc !== 'object') throw new Error('holiday calendar: not an object');
+	if (!Array.isArray(doc.days)) throw new Error('holiday calendar: no "days" array');
+	const year = Number.isFinite(doc.year) ? Math.trunc(doc.year) : undefined;
+	const days = [];
+	for (const entry of doc.days) {
+		if (entry === null || typeof entry !== 'object') continue;
+		if (!isDate(entry.date)) continue;
+		if (typeof entry.isOffDay !== 'boolean') continue;
+		const day = { date: entry.date, isOffDay: entry.isOffDay };
+		// The holiday name is display-only, so a missing one is not a defect.
+		if (typeof entry.name === 'string' && entry.name !== '') day.name = entry.name;
+		days.push(day);
+	}
+	const papers = (Array.isArray(doc.papers) ? doc.papers : [])
+		.filter((paper) => typeof paper === 'string' && paper !== '')
+		.map((paper) => paper.trim());
+	return { ...year === undefined ? {} : { year }, papers, days };
+}
+
+/**
+* Split parsed days into the two sets the peak policy needs.
+*
+* `isOffDay: true` is a statutory holiday (法定节假日); `isOffDay: false` is a 调休上班日 —
+* a weekend the State Council opened for work. Keeping them separate is what lets the
+* policy treat "closed" and "opened a Saturday" as different facts.
+*
+* @param days - parsed days.
+* @returns `{ holidays, makeupWorkdays }`, each sorted and de-duplicated.
+*/
+export function toCalendar(days) {
+	const holidays = new Set();
+	const makeupWorkdays = new Set();
+	for (const day of Array.isArray(days) ? days : []) {
+		if (day === null || typeof day !== 'object' || !isDate(day.date)) continue;
+		if (day.isOffDay === true) holidays.add(day.date);
+		else if (day.isOffDay === false) makeupWorkdays.add(day.date);
+	}
+	return {
+		holidays: [...holidays].sort(),
+		makeupWorkdays: [...makeupWorkdays].sort(),
+	};
+}
+
+/**
+* Union several calendars.
+* @param calendars - calendars to merge.
+* @returns one calendar holding every date seen, sorted.
+*/
+export function mergeCalendars(...calendars) {
+	const holidays = new Set();
+	const makeup = new Set();
+	for (const calendar of calendars.flat()) {
+		if (calendar === null || typeof calendar !== 'object') continue;
+		for (const date of Array.isArray(calendar.holidays) ? calendar.holidays : []) {
+			if (isDate(date)) holidays.add(date);
+		}
+		for (const date of Array.isArray(calendar.makeupWorkdays) ? calendar.makeupWorkdays : []) {
+			if (isDate(date)) makeup.add(date);
+		}
+	}
+	return {
+		holidays: [...holidays].sort(),
+		makeupWorkdays: [...makeup].sort(),
+	};
+}
+
+/**
+* Layer manual corrections on top of a fetched calendar.
+*
+* An override is a date an operator decided differently about, so it wins outright: it is
+* added to the set it names and removed from the other, which keeps the two lists
+* consistent after a correction. Without this, moving a date from `holidays` to
+* `makeupWorkdays` would leave it in both and the router's precedence rule would quietly
+* override the operator.
+*
+* @param calendar - the fetched calendar.
+* @param override - `{ holidays?, makeupWorkdays? }` manual dates.
+* @returns the corrected calendar.
+*/
+export function mergeOverride(calendar, override = {}) {
+	const holidays = new Set(Array.isArray(calendar?.holidays) ? calendar.holidays : []);
+	const makeup = new Set(Array.isArray(calendar?.makeupWorkdays) ? calendar.makeupWorkdays : []);
+	for (const date of Array.isArray(override?.holidays) ? override.holidays : []) {
+		if (!isDate(date)) continue;
+		holidays.add(date);
+		makeup.delete(date);
+	}
+	for (const date of Array.isArray(override?.makeupWorkdays) ? override.makeupWorkdays : []) {
+		if (!isDate(date)) continue;
+		makeup.add(date);
+		holidays.delete(date);
+	}
+	return { holidays: [...holidays].sort(), makeupWorkdays: [...makeup].sort() };
+}
+
+/**
+* Expand a URL template for one year.
+* @param template - a URL containing `{year}`, or empty to use the source default.
+* @param year - calendar year.
+* @param source - source id, used when `template` is empty.
+* @returns the first URL to try, or undefined when no template is known.
+*/
+export function buildUrl(template, year, source = 'holiday-cn') {
+	const chosen = typeof template === 'string' && template.trim() !== ''
+		? template.trim()
+		: DEFAULT_SOURCE_URLS[source]?.[0];
+	if (typeof chosen !== 'string') return undefined;
+	return chosen.replaceAll('{year}', String(year));
+}
+
+/**
+* Every URL to try for one year, in order.
+* @param template - configured template; empty uses the source defaults.
+* @param year - calendar year.
+* @param source - source id.
+* @returns the candidate URLs.
+*/
+export function sourceUrls(template, year, source = 'holiday-cn') {
+	const own = typeof template === 'string' && template.trim() !== '' ? [template.trim()] : [];
+	const candidates = own.length > 0 ? own : DEFAULT_SOURCE_URLS[source] ?? [];
+	return candidates.map((url) => url.replaceAll('{year}', String(year)));
+}
+
+/**
+* Whether a cached calendar should be re-fetched.
+*
+* Two independent reasons: the cache is simply old (schedule drift), or a year the policy
+* can currently reach is missing because it had not been published yet when the cache was
+* written. The second is what makes a November notice land without a restart.
+*
+* @param meta - cache metadata (`fetchedAt`, `years`).
+* @param now - clock reading.
+* @param options - `{ cacheDays, years }`.
+* @returns true when a refresh is warranted.
+*/
+export function needsRefresh(meta, now, options = {}) {
+	const fetchedAt = Number.isFinite(meta?.fetchedAt) ? meta.fetchedAt : undefined;
+	if (fetchedAt === undefined) return true;
+	const cacheDays = Number.isFinite(options.cacheDays) ? options.cacheDays : 30;
+	if (now - fetchedAt >= cacheDays * 86_400_000) return true;
+	const loaded = new Set(Array.isArray(meta?.years) ? meta.years : []);
+	return (Array.isArray(options.years) ? options.years : []).some((year) => !loaded.has(year));
+}
+
+/**
+* The years the current policy can reach: this year, next year (their notice may already
+* be out) and enough history to cover a session that started just before New Year.
+*
+* Next year is not optional. The dataset files a date under the *notice's* title year, not
+* the calendar year, so a December date can belong to the following year's document — the
+* upstream dataset says to check both. Loading one year early also means the next year's
+* notice lands on its own once it is published in November.
+*
+* @param now - clock reading, epoch milliseconds.
+* @returns ascending years.
+*/
+export function yearsAround(now) {
+	const year = new Date(now).getUTCFullYear();
+	const years = [];
+	for (let offset = HISTORY_YEARS; offset >= 0; offset -= 1) years.push(year - offset);
+	years.push(year + 1);
+	return years;
+}
+
+/**
+* One process-lifetime holiday calendar.
+*
+* Holds the merged date sets in memory so a routing decision is a set lookup, and writes
+* its state to a single JSON file so a restart does not re-download.
+*/
+export class HolidayCalendar {
+	/**
+	 * @param {object} options - calendar dependencies.
+	 * @param {string} options.dir - data directory; the cache lives at `<dir>/calendar.json`.
+	 * @param {string} [options.source] - source id, default `holiday-cn`.
+	 * @param {string} [options.urlTemplate] - custom URL template with `{year}`.
+	 * @param {object} [options.logger] - host logger.
+	 * @param {Function} [options.fetchImpl] - fetch implementation, injectable for tests.
+	 * @param {() => number} [options.now] - clock, injectable for tests.
+	 */
+	constructor({ dir, source = 'holiday-cn', urlTemplate = '', logger, fetchImpl, now } = {}) {
+		this.dir = dir;
+		this.source = source;
+		this.urlTemplate = urlTemplate;
+		this.logger = logger;
+		this.fetchImpl = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch;
+		this.now = typeof now === 'function' ? now : () => Date.now();
+		/** Per-year calendars as fetched, keyed by year. */
+		this.byYear = new Map();
+		/** Per-year source metadata (`papers`). */
+		this.papers = new Map();
+		/** Years the source answered for but has not published a notice for yet. */
+		this.pending = new Set();
+		/** Years the source answered for, but has not published a notice for yet. */
+		this.pending = new Set();
+		this.fetchedAt = undefined;
+		this.lastError = undefined;
+		/** Serializes refreshes so concurrent calls share one request. */
+		this.refreshing = undefined;
+	}
+
+	/**
+	 * Load the cache from disk once. Safe to call repeatedly.
+	 * @returns {Promise<boolean>} true when a usable cache was read.
+	 */
+	async load() {
+		if (this.loaded === true) return this.ready();
+		this.loaded = true;
+		try {
+			const text = await readFile(join(this.dir, CACHE_FILE), 'utf8');
+			const cache = JSON.parse(text);
+			if (cache?.version !== CACHE_VERSION || cache.source !== this.source) return false;
+			if (!Array.isArray(cache.years)) return false;
+			for (const entry of cache.years) {
+				if (entry === null || typeof entry !== 'object') continue;
+				const year = Number(entry.year);
+				if (!Number.isFinite(year)) continue;
+				const calendar = mergeCalendars({
+					holidays: Array.isArray(entry.holidays) ? entry.holidays : [],
+					makeupWorkdays: Array.isArray(entry.makeupWorkdays) ? entry.makeupWorkdays : [],
+				});
+				this.byYear.set(year, calendar);
+				this.papers.set(year, Array.isArray(entry.papers) ? entry.papers : []);
+			}
+			if (Number.isFinite(cache.fetchedAt)) this.fetchedAt = cache.fetchedAt;
+			return this.ready();
+		} catch {
+			// No cache, or an unreadable one: `ready()` stays false and the first refresh
+			// simply has nothing to fall back on.
+			return false;
+		}
+	}
+
+	/**
+	 * Write the current state to disk.
+	 * @returns {Promise<void>} settles when the write is attempted.
+	 */
+	async save() {
+		const payload = {
+			version: CACHE_VERSION,
+			source: this.source,
+			fetchedAt: this.fetchedAt,
+			years: [...this.byYear].map(([year, calendar]) => ({
+				year,
+				...calendar,
+				papers: this.papers.get(year) ?? [],
+			})),
+		};
+		try {
+			await mkdir(this.dir, { recursive: true });
+			await writeFile(join(this.dir, CACHE_FILE), JSON.stringify(payload, null, '	'), 'utf8');
+		} catch (error) {
+			// A read-only data directory must not break routing; the calendar simply
+			// becomes memory-only for this process generation.
+			this.logger?.warn?.('model-pool: could not write the holiday cache: %s', error?.message ?? String(error));
+		}
+	}
+
+	/**
+	 * Point the calendar at a different source.
+	 *
+	 * A changed source or template invalidates the loaded years: they came from the old
+	 * source, and silently mixing two sources would produce a calendar nobody can reason
+	 * about. The cache stays on disk until the next refresh overwrites it.
+	 *
+	 * @param {object} options - `{ source, urlTemplate }`.
+	 * @returns {boolean} true when the source actually changed.
+	 */
+	reconfigure({ source, urlTemplate } = {}) {
+		const nextSource = typeof source === 'string' && source !== '' ? source : this.source;
+		const nextTemplate = typeof urlTemplate === 'string' ? urlTemplate : this.urlTemplate;
+		if (nextSource === this.source && nextTemplate === this.urlTemplate) return false;
+		this.source = nextSource;
+		this.urlTemplate = nextTemplate;
+		this.byYear.clear();
+		this.papers.clear();
+		this.pending.clear();
+		this.fetchedAt = undefined;
+		this.lastError = undefined;
+		return true;
+	}
+
+	/**
+	 * The newest year loaded.
+	 * @returns {number|undefined} that year, or undefined before the first load.
+	 */
+	#newestYear() {
+		let newest;
+		for (const year of this.byYear.keys()) {
+			if (newest === undefined || year > newest) newest = year;
+		}
+		return newest;
+	}
+
+	/** @returns {boolean} true when at least one year is known. */
+	ready() {
+		return this.byYear.size > 0;
+	}
+
+	/** The merged calendar across every loaded year. */
+	calendar() {
+		return mergeCalendars(...this.byYear.values());
+	}
+
+	/** @returns {Set<string>} statutory holidays. */
+	holidays() {
+		return new Set(this.calendar().holidays);
+	}
+
+	/** @returns {Set<string>} 调休上班日. */
+	makeupWorkdays() {
+		return new Set(this.calendar().makeupWorkdays);
+	}
+
+	/** The official notice URLs the loaded data was generated from. */
+	paperList() {
+		const papers = new Set();
+		for (const list of this.papers.values()) {
+			for (const paper of list) papers.add(paper);
+		}
+		return [...papers].sort();
+	}
+
+	/**
+	 * A JSON-friendly view for the settings API.
+	 *
+	 * Two different questions live in this payload, and they are deliberately kept apart.
+	 * The whole-set fields (`years`, `holidayCount`, `makeupCount`) describe everything
+	 * loaded, because routing consumes all of it: the 16-day `nextChangeAt` lookahead
+	 * crosses New Year, so a session on 31 December still needs next year's notice. The
+	 * `current*` triple answers the narrower question a reader actually has — "is today's
+	 * calendar right?" — and Settings shows only that.
+	 *
+	 * Pure read: nothing here is mutated, and the counts are derived from the year already
+	 * in memory, so a `/state` poll stays a couple of array scans.
+	 *
+	 * @param {object} [options] - `{ cacheDays, year }`.
+	 * @param {number} [options.year] - year to report as current; defaults to the UTC
+	 *   calendar year of `now()`, matching `yearsAround` so the module has one convention.
+	 * @returns the status snapshot.
+	 */
+	status(options = {}) {
+		const calendar = this.calendar();
+		const fetchedAt = this.fetchedAt;
+		const currentYear = Number.isFinite(options.year)
+			? Math.trunc(options.year)
+			: new Date(this.now()).getUTCFullYear();
+		const current = this.byYear.get(currentYear);
+		// A year that is not loaded reports zero rather than borrowing a neighbour's
+		// figures: "nothing known for this year" is the honest answer, and the card says
+		// so. Silently showing another year's counts would misreport today's policy.
+		const prefix = `${currentYear}-`;
+		const currentHolidays = (current?.holidays ?? []).filter((date) => date.startsWith(prefix));
+		const currentMakeup = (current?.makeupWorkdays ?? []).filter((date) => date.startsWith(prefix));
+		return {
+			years: [...this.byYear.keys()].sort((left, right) => left - right),
+			// Years the source knows about but has no notice for yet: published in November,
+			// so Settings can say "not published" instead of implying the data is complete.
+			pendingYears: [...this.pending].sort((left, right) => left - right),
+			fetchedAt: fetchedAt ?? null,
+			source: this.source,
+			stale: fetchedAt === undefined
+				? true
+				: this.now() - fetchedAt >= (Number.isFinite(options.cacheDays) ? options.cacheDays : 30) * 86_400_000,
+			lastError: this.lastError ?? null,
+			holidayCount: calendar.holidays.length,
+			makeupCount: calendar.makeupWorkdays.length,
+			papers: this.paperList(),
+			// One year only — the one the caller named. See the note above.
+			currentYear,
+			currentHolidayCount: currentHolidays.length,
+			currentMakeupCount: currentMakeup.length,
+		};
+	}
+
+	/**
+	 * Fetch one year's document.
+	 * @param {number} year - calendar year.
+	 * @returns {Promise<object|null>} the calendar for that year, or null when unavailable.
+	 */
+	async #fetchYear(year) {
+		const urls = sourceUrls(this.urlTemplate, year, this.source);
+		for (const url of urls) {
+			try {
+				if (typeof this.fetchImpl !== 'function') throw new Error('no fetch implementation');
+				const controller = typeof AbortController === 'function' ? new AbortController() : undefined;
+				const timer = controller === undefined ? undefined : setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+				let response;
+				try {
+					response = await this.fetchImpl(url, {
+						headers: { accept: 'application/json' },
+						...controller === undefined ? {} : { signal: controller.signal },
+					});
+				} finally {
+					if (timer !== undefined) clearTimeout(timer);
+				}
+				// A year whose notice has not been published yet answers 404, or 200 with an
+				// empty `days` array (the dataset pre-creates the file once the year starts).
+				// Both mean "not published", which is a state of the world, not a failure:
+				// the callers must not report it as an error, and must keep asking for it.
+				if (response?.status === 404) return { year, published: false, papers: [] };
+				if (response?.ok !== true) throw new Error(`HTTP ${response?.status ?? '?'}`);
+				const text = await response.text();
+				const parsed = parseSourceDocument(text);
+				const calendar = toCalendar(parsed.days);
+				const published = calendar.holidays.length > 0 || calendar.makeupWorkdays.length > 0;
+				return { year, published, ...calendar, papers: parsed.papers };
+			} catch (error) {
+				this.logger?.debug?.(
+					'model-pool: holiday calendar %s from %s failed: %s',
+					year,
+					url,
+					error?.message ?? String(error),
+				);
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Refresh from the source, cache first.
+	 *
+	 * Concurrent callers share one run. A refresh that finds a usable cache does no I/O at
+	 * all unless `force` is set or `needsRefresh` says otherwise.
+	 *
+	 * @param {object} [options] - `{ force, cacheDays, years }`.
+	 * @returns {Promise<object>} the status after the attempt.
+	 */
+	async refresh(options = {}) {
+		if (this.refreshing !== undefined) return this.refreshing;
+		this.refreshing = (async () => {
+			try {
+				await this.load();
+				const now = this.now();
+				const years = Array.isArray(options.years) && options.years.length > 0 ? options.years : yearsAround(now);
+				const meta = { fetchedAt: this.fetchedAt, years: [...this.byYear.keys()] };
+				const wanted = options.force === true
+					|| !this.ready()
+					|| needsRefresh(meta, now, { cacheDays: options.cacheDays, years });
+				if (!wanted) return this.status(options);
+
+				// Two different reasons to be here. A cache that has aged out is re-read
+				// wholesale. A fresh cache that is merely missing a year (its notice is not out
+				// yet) only re-asks for that year, so the steady state before a November
+				// publication costs one request per sync, not one per known year.
+				const cacheDays = Number.isFinite(options.cacheDays) ? options.cacheDays : 30;
+				const aged = this.fetchedAt === undefined || now - this.fetchedAt >= cacheDays * 86_400_000;
+				const wantedYears = options.force === true || aged || !this.ready()
+					? years
+					: years.filter((year) => !this.byYear.has(year));
+				if (wantedYears.length === 0) return this.status(options);
+
+				let failures = 0;
+				let changed = false;
+				for (const year of wantedYears) {
+					// A past year is settled once it is known: its notice has been published and
+					// the dataset no longer moves. Only the newest loaded year and any year still
+					// missing are worth asking for, which keeps a monthly refresh to one or two
+					// requests instead of one per loaded year.
+					const newest = this.#newestYear();
+					const settled = this.byYear.has(year) && newest !== undefined && year < newest;
+					if (options.force !== true && settled) continue;
+					const calendar = await this.#fetchYear(year);
+					if (calendar === null) {
+						// A transport or parse failure. Only worth reporting when we have nothing
+						// at all for that year; a cached year keeps serving.
+						if (!this.byYear.has(year)) failures += 1;
+						continue;
+					}
+					if (calendar.published !== true) {
+						// The notice is not out yet. Recording the year would make `needsRefresh`
+						// believe it is settled, and the November publication would then wait for
+						// the cache to age out instead of landing on the next sync. So a pending
+						// year is deliberately left out of `byYear` and named separately.
+						this.pending.add(year);
+						continue;
+					}
+					this.byYear.set(year, {
+						holidays: calendar.holidays,
+						makeupWorkdays: calendar.makeupWorkdays,
+					});
+					this.papers.set(year, calendar.papers);
+					// It is published now, so it is no longer pending.
+					this.pending.delete(year);
+					changed = true;
+				}
+				if (changed) {
+					this.fetchedAt = now;
+					this.lastError = undefined;
+					await this.save();
+				} else if (!this.ready()) {
+					// Nothing loaded and nothing fetched: say so once, and keep routing on
+					// the weekday rule rather than failing.
+					this.lastError = `could not load the holiday calendar (source: ${this.source})`;
+					this.logger?.warn?.('model-pool: %s', this.lastError);
+				} else if (failures > 0) {
+					this.lastError = `${failures} year(s) unavailable; serving the cached calendar`;
+				}
+				return this.status(options);
+			} catch (error) {
+				// Belt and braces: routing must survive any surprise here.
+				this.lastError = error?.message ?? String(error);
+				this.logger?.warn?.('model-pool: holiday calendar refresh failed: %s', this.lastError);
+				return this.status(options);
+			} finally {
+				this.refreshing = undefined;
+			}
+		})();
+		return this.refreshing;
+	}
+}