slotlock 0.7.0 → 0.9.0

package/lifecycle.js

@@ -0,0 +1,115 @@
+export const SLOTLOCK_BOOKING_STATUSES = Object.freeze([
+    'held',
+    'confirmed',
+    'checked_in',
+    'completed',
+    'cancelled',
+    'no_show',
+    'released',
+    'expired',
+    'erased',
+]);
+/** What moves a hold or booking, and who does it. */
+export const SLOTLOCK_BOOKING_ACTIONS = Object.freeze([
+    /** The holder books the held time (confirmHold, slotlock_confirm_slot). */
+    'confirm',
+    /** The holder lets the hold go (releaseHold, slotlock_release_slots). */
+    'release',
+    /** Its time to live runs out; the next writer in its way reaps it. */
+    'expire',
+    /** A new time or resource, at the next revision (rescheduleExternalReservation). */
+    'reschedule',
+    /** Claimed in person (checkInReservation), from an hour before the start until the end. */
+    'check_in',
+    /** Cancelled at the next revision (cancelExternalReservation). */
+    'cancel',
+    /** Not checked in within the resource's checkInMinutes: maintenance releases it. */
+    'no_show',
+    /** Its end passes: maintenance says so on the feed. */
+    'complete',
+    /** The tenant is erased. */
+    'erase',
+]);
+/** Where an end leaves a hold or booking: nothing moves it again, but erasure. */
+export const SLOTLOCK_BOOKING_ENDS = new Set([
+    'cancelled',
+    'no_show',
+    'released',
+    'expired',
+    'erased',
+]);
+/**
+ * Each allowed move: the status it leads to and the feed change it writes (null: none; a list: all
+ * of them, in order). Anything not here is refused with `SLOTLOCK_BOOKING_REFUSALS`.
+ */
+export const SLOTLOCK_BOOKING_TRANSITIONS = Object.freeze({
+    held: {
+        confirm: { to: 'confirmed', change: 'hold.confirmed' },
+        release: { to: 'released', change: 'hold.released' },
+        expire: { to: 'expired', change: 'hold.expired' },
+        reschedule: { to: 'held', change: 'hold.updated' },
+        erase: { to: 'erased', change: null },
+    },
+    confirmed: {
+        reschedule: { to: 'confirmed', change: ['reservation.updated', 'reservation.rescheduled'] },
+        check_in: { to: 'checked_in', change: 'reservation.checked_in' },
+        cancel: { to: 'cancelled', change: 'reservation.cancelled' },
+        no_show: { to: 'no_show', change: 'reservation.no_show' },
+        complete: { to: 'completed', change: 'reservation.completed' },
+        erase: { to: 'erased', change: null },
+    },
+    checked_in: {
+        reschedule: { to: 'checked_in', change: ['reservation.updated', 'reservation.rescheduled'] },
+        // Checking in again answers the first check-in.
+        check_in: { to: 'checked_in', change: null },
+        cancel: { to: 'cancelled', change: 'reservation.cancelled' },
+        complete: { to: 'completed', change: 'reservation.completed' },
+        erase: { to: 'erased', change: null },
+    },
+    completed: {
+        // A system of record may correct or void a booking after it ended.
+        reschedule: { to: 'completed', change: ['reservation.updated', 'reservation.rescheduled'] },
+        cancel: { to: 'cancelled', change: 'reservation.cancelled' },
+        erase: { to: 'erased', change: null },
+    },
+    cancelled: { erase: { to: 'erased', change: null } },
+    no_show: { erase: { to: 'erased', change: null } },
+    released: {},
+    expired: {},
+    erased: {},
+});
+/** The refusal a move gets from a status it is not allowed from, as the store names it. */
+export function slotlockBookingRefusal(from, action) {
+    const holdAction = action === 'confirm' || action === 'release' || action === 'expire';
+    switch (from) {
+        case 'held':
+            // A hold is not a booking: booking operations do not find it.
+            return 'reservation_not_found';
+        case 'confirmed':
+        case 'checked_in':
+            if (holdAction)
+                return 'hold_not_found';
+            // Only maintenance releases no-shows, and never one checked in.
+            return 'reservation_checked_in';
+        case 'completed':
+            return holdAction ? 'hold_not_found' : 'reservation_ended';
+        case 'cancelled':
+        case 'no_show':
+            // The reference is retired: writing it again is refused, checking it in finds nothing.
+            return action === 'check_in' ? 'reservation_not_found' : holdAction ? 'hold_not_found' : 'reservation_cancelled';
+        case 'released':
+            return action === 'confirm' ? 'hold_not_found' : 'not_found';
+        case 'expired':
+            return action === 'confirm' ? 'hold_expired' : 'not_found';
+        case 'erased':
+            return 'not_found';
+    }
+}
+/** What `action` does from `from`: the status it leads to and the change it writes, or its refusal. */
+export function slotlockBookingNext(from, action) {
+    const move = SLOTLOCK_BOOKING_TRANSITIONS[from][action];
+    if (!move)
+        return { ok: false, code: slotlockBookingRefusal(from, action) };
+    const changes = move.change === null ? [] : typeof move.change === 'string' ? [move.change] : move.change;
+    return { ok: true, to: move.to, changes };
+}

package/maintenance.d.ts

@@ -26,6 +26,18 @@ export interface SlotlockMaintenanceResult {
     waitlistOffers: number;
     /** Approvals no one decided in time, their held time freed (`approval.expired`). */
     approvalsExpired: number;
+    /** Bookings whose end has passed in the last week, now said on the feed (`reservation.completed`). */
+    bookingsCompleted: number;
+    /**
+     * Event reminders that came due, each now on the feed once (`reminder.due`) for a sender to send
+     * (RFC 0004 P3).
+     */
+    remindersDue: number;
+    /**
+     * Holiday calendar subscriptions imported again (RFC 0004 B1), with `holidayFetch`; one that
+     * could not be read keeps its closures and is tried again a day later.
+     */
+    holidayCalendarsImported: number;
     /** More was left than one pass does: run another. */
     capped: boolean;
     /**
@@ -49,6 +61,11 @@ export declare function maintainSlotlockTenant(store: SlotlockStore, tenantRef:
      * (SLOTLOCK_USAGE=on).
      */
     usage?: boolean;
+    /**
+     * Fetches holiday calendar subscriptions due to be imported again (the guarded fetch under
+     * `serve`); without it, none is.
+     */
+    holidayFetch?: typeof fetch;
 }): Promise<SlotlockMaintenanceResult>;
 /**
  * Run `work` holding the tenant's maintenance lock on a connection of its own, or return
@@ -83,6 +100,8 @@ export interface SlotlockMaintenanceSchedulerOptions {
     batches?: number;
     /** Roll each tenant's bookings and holds up into its usage, first (maintainSlotlockTenant `usage`). */
     usage?: boolean;
+    /** Fetches holiday calendar subscriptions due to be imported again (maintainSlotlockTenant). */
+    holidayFetch?: typeof fetch;
     /** A pass that ran: counts only, never the tenant. Not awaited; what it throws is ignored. */
     onPass?: (result: SlotlockMaintenanceResult) => void;
     /**

package/maintenance.js

@@ -1,5 +1,6 @@
 import { ignoreRejection } from './hooks.js';
 import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon, } from './store.js';
+import { readSlotlockHolidayCalendar } from './holiday-import.js';
 /**
  * One maintenance pass for a tenant: roll its recurring events to the horizon, then purge expired
  * holds and prune bookkeeping past retention, each in at most `batches` batches (1-100, default
@@ -78,6 +79,10 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     // in the same pass.
     const approvals = await withTenant((tenant) => tenant.expireApprovals({ tenantRef, limit: 100 }));
     const noShows = await withTenant((tenant) => tenant.releaseNoShows({ tenantRef }));
+    // Bookings that ended since the last pass (RFC 0004 B4): no row changes, the feed says so.
+    const completed = await withTenant((tenant) => tenant.completeEndedBookings({ tenantRef, limit: 500 }));
+    const reminders = await withTenant((tenant) => tenant.dueReminders({ tenantRef, limit: 500 }));
+    const holidays = options.holidayFetch ? await importDueHolidayCalendars(withTenant, tenantRef, options) : 0;
     // The whole waitlist in join order, a page per transaction, so a later free entry is offered
     // however many wait before it.
     let waitlistOffers = 0;
@@ -103,10 +108,58 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         noShows,
         waitlistOffers,
         approvalsExpired: approvals.expired,
-        capped: rollCapped || eventsLeft || bookingsLeft || changesLeft || approvals.expired === 100,
+        bookingsCompleted: completed,
+        remindersDue: reminders,
+        holidayCalendarsImported: holidays,
+        capped: rollCapped ||
+            eventsLeft ||
+            bookingsLeft ||
+            changesLeft ||
+            approvals.expired === 100 ||
+            completed === 500 ||
+            reminders === 500,
         rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
     };
 }
+/** Holiday calendar subscriptions imported again in one pass, at most: each is a fetch. */
+const HOLIDAY_IMPORTS_PER_PASS = 5;
+/**
+ * Import again the tenant's holiday calendar subscriptions that are due: each fetched outside any
+ * transaction, then imported in one; one that cannot be read or imported keeps its closures and
+ * notes why, to be tried again a day later.
+ */
+async function importDueHolidayCalendars(withTenant, tenantRef, options) {
+    const due = await withTenant((tenant) => tenant.dueHolidayCalendars({ tenantRef, limit: HOLIDAY_IMPORTS_PER_PASS }));
+    let imported = 0;
+    for (const calendar of due) {
+        options.signal?.throwIfAborted();
+        if (!calendar.url)
+            continue;
+        try {
+            const read = await readSlotlockHolidayCalendar({ url: calendar.url, subscribe: true, name: calendar.name }, options.holidayFetch);
+            await withTenant((tenant) => tenant.importHolidayCalendar({
+                tenantRef,
+                ...(calendar.location !== undefined ? { location: calendar.location } : {}),
+                ...(calendar.resourceId !== undefined ? { resourceId: calendar.resourceId } : {}),
+                name: calendar.name,
+                ...(read.url !== undefined ? { url: read.url } : {}),
+                holidays: read.holidays,
+                span: read.span,
+            }));
+            imported++;
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            await withTenant((tenant) => tenant.noteHolidayCalendarFailure({
+                tenantRef,
+                id: calendar.id,
+                error: error instanceof Error ? error.message : 'The import failed',
+            }));
+        }
+    }
+    return imported;
+}
 /** Pages of 50 that cover a tenant's whole waitlist (SLOTLOCK_MAX_WAITLIST_PER_TENANT). */
 const WAITLIST_PAGES = Math.ceil(SLOTLOCK_MAX_WAITLIST_PER_TENANT / 50);
 /** How often the scheduler sweeps every tenant's expired assistant conversations, at most. */
@@ -183,6 +236,7 @@ export function startSlotlockMaintenance(options) {
                     const result = await withSlotlockMaintenanceLock(options.sql, tenantRef, () => maintainSlotlockTenant(options.store, tenantRef, {
                         ...(options.batches !== undefined ? { batches: options.batches } : {}),
                         ...(options.usage ? { usage: true } : {}),
+                        ...(options.holidayFetch ? { holidayFetch: options.holidayFetch } : {}),
                         signal: controller.signal,
                     }));
                     recordPass(tenantRef, Date.now());

package/metrics.js

@@ -19,6 +19,9 @@ const MAINTENANCE_COUNTS = [
     'noShows',
     'waitlistOffers',
     'approvalsExpired',
+    'bookingsCompleted',
+    'remindersDue',
+    'holidayCalendarsImported',
 ];
 /** A label value: an operation, protocol or outcome code. Anything else is counted as `other`. */
 const LABEL = /^[a-z0-9_.]{1,64}$/;