slotlock 0.2.0 → 0.3.0

package/engine.js

@@ -47,13 +47,27 @@ export function findNextAvailable(params) {
     const { busy, windows, durationMs } = params;
     if (!Number.isFinite(durationMs) || durationMs <= 0)
         return null;
-    const orderedWindows = mergeIntervals(windows);
-    for (const window of orderedWindows) {
-        for (const free of subtractBusy(window, busy)) {
-            if (free.end.getTime() - free.start.getTime() >= durationMs) {
-                return { start: free.start, end: new Date(free.start.getTime() + durationMs) };
-            }
+    const slotAt = (start) => ({ start, end: new Date(start.getTime() + durationMs) });
+    // One walk of the merged busy list alongside the merged windows, both by start: a busy interval
+    // ending by a window's start ends before every later one too.
+    const merged = mergeIntervals(busy);
+    let next = 0;
+    for (const window of mergeIntervals(windows)) {
+        while (next < merged.length && merged[next].end.getTime() <= window.start.getTime()) {
+            next += 1;
         }
+        let cursor = window.start;
+        for (let index = next; index < merged.length; index++) {
+            const taken = merged[index];
+            if (taken.start.getTime() >= window.end.getTime())
+                break;
+            if (taken.start.getTime() - cursor.getTime() >= durationMs)
+                return slotAt(cursor);
+            if (taken.end.getTime() > cursor.getTime())
+                cursor = taken.end;
+        }
+        if (window.end.getTime() - cursor.getTime() >= durationMs)
+            return slotAt(cursor);
     }
     return null;
 }

package/event-schema.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export declare const SLOTLOCK_EVENT_OUTPUT: z.ZodObject<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    starts_at: z.ZodString;
+    ends_at: z.ZodString;
+    timezone: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    location: z.ZodNullable<z.ZodString>;
+    organizer: z.ZodNullable<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    attendees: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        role: z.ZodEnum<{
+            chair: "chair";
+            non_participant: "non_participant";
+            optional: "optional";
+            required: "required";
+        }>;
+        participation_status: z.ZodEnum<{
+            accepted: "accepted";
+            declined: "declined";
+            delegated: "delegated";
+            needs_action: "needs_action";
+            tentative: "tentative";
+        }>;
+        rsvp: z.ZodBoolean;
+    }, z.core.$strict>>;
+    reminders: z.ZodArray<z.ZodObject<{
+        minutes_before: z.ZodNumber;
+        channel: z.ZodEnum<{
+            display: "display";
+            email: "email";
+        }>;
+    }, z.core.$strict>>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        confirmed: "confirmed";
+        tentative: "tentative";
+    }>;
+    transparency: z.ZodEnum<{
+        opaque: "opaque";
+        transparent: "transparent";
+    }>;
+    sequence: z.ZodNumber;
+    revision: z.ZodNumber;
+    recurrence_rule: z.ZodNullable<z.ZodString>;
+    recurrence_exceptions: z.ZodArray<z.ZodObject<{
+        recurrence_id: z.ZodString;
+        cancelled: z.ZodBoolean;
+        starts_at: z.ZodNullable<z.ZodString>;
+        ends_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    recurrence_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;

package/event-schema.js

@@ -0,0 +1,85 @@
+// A calendar event as the event tools return it, and as the application API returns any of a
+// tenant's events. Its own module because both the agent server and the application API describe
+// events with it, and the application API imports nothing from the agent server at runtime (the
+// agent server imports it, so the reverse would be a cycle).
+import { z } from 'zod';
+const DATE_TIME = z.string().datetime({ offset: true });
+const RESOURCE_ID = z.string().trim().min(1).max(200);
+const EVENT_ID = z.string().trim().min(1).max(500);
+const REVISION = z.number().int().positive();
+// Output bounds mirror the trusted store's byte ceilings. A value admitted by a UTF-8 byte
+// ceiling can never exceed that many UTF-16 code units, so every valid stored/provider event is
+// serializable without truncating recurrence semantics or calendar identities.
+const TRUSTED_SUMMARY_OUTPUT_MAX = 4_096;
+const TRUSTED_TEXT_OUTPUT_MAX = 16_384;
+const TRUSTED_PERSON_NAME_OUTPUT_MAX = 1_024;
+const TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX = 1_000;
+const TRUSTED_REMINDER_MINUTES_OUTPUT_MAX = 366 * 24 * 60;
+// The grammar the store keeps an address in (normalizeEmail in sync.ts), so every stored one can be
+// returned: an address from an imported feed need not be one z.email() takes (ops@localhost).
+const STORED_ADDRESS = z
+    .string()
+    .min(3)
+    .max(320)
+    .refine((value) => /^[^\s@]+@[^\s@]+$/.test(value), {
+    message: 'must be one @ between characters other than spaces',
+});
+const ORGANIZER = z
+    .object({
+    address: STORED_ADDRESS,
+    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
+})
+    .strict();
+const ATTENDEE = z
+    .object({
+    address: STORED_ADDRESS,
+    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
+    role: z.enum(['chair', 'required', 'optional', 'non_participant']),
+    participation_status: z.enum([
+        'needs_action',
+        'accepted',
+        'declined',
+        'tentative',
+        'delegated',
+    ]),
+    rsvp: z.boolean(),
+})
+    .strict();
+const REMINDER = z
+    .object({
+    minutes_before: z.number().int().min(0).max(TRUSTED_REMINDER_MINUTES_OUTPUT_MAX),
+    channel: z.enum(['display', 'email']),
+})
+    .strict();
+const RECURRENCE_EXCEPTION = z
+    .object({
+    recurrence_id: DATE_TIME,
+    cancelled: z.boolean(),
+    starts_at: DATE_TIME.nullable(),
+    ends_at: DATE_TIME.nullable(),
+})
+    .strict();
+export const SLOTLOCK_EVENT_OUTPUT = z
+    .object({
+    id: EVENT_ID,
+    resource_id: RESOURCE_ID,
+    starts_at: DATE_TIME,
+    ends_at: DATE_TIME,
+    timezone: z.string().min(1).max(100),
+    title: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
+    description: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
+    location: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
+    organizer: ORGANIZER.nullable(),
+    attendees: z.array(ATTENDEE).max(100),
+    reminders: z.array(REMINDER).max(20),
+    status: z.enum(['tentative', 'confirmed', 'cancelled']),
+    transparency: z.enum(['opaque', 'transparent']),
+    sequence: z.number().int().nonnegative(),
+    revision: REVISION,
+    recurrence_rule: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
+    recurrence_exceptions: z
+        .array(RECURRENCE_EXCEPTION)
+        .max(TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX),
+    recurrence_id: DATE_TIME.nullable(),
+})
+    .strict();

package/ical-worker-thread.js

@@ -1,7 +1,7 @@
 // One worker of createICalendarWorkerPool: reads the feeds it is sent with the ordinary parsers and
 // posts back what they return, or the code of the CalendarContractError they throw.
 import { parentPort } from 'node:worker_threads';
-import { CalendarContractError, CalendarExpansionLimitError, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
+import { CalendarContractError, CalendarExpansionLimitError, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, } from './sync.js';
 const port = parentPort;
 if (!port)
     throw new Error('slotlock: ical-worker-thread runs only as a worker thread');
@@ -10,7 +10,9 @@ port.on('message', (request) => {
     try {
         const value = request.op === 'changes'
             ? parseICalendarChanges(request.input, request.calendarTimezone, request.window)
-            : parseTrustedICalendarEvents(request.input, request.calendarTimezone);
+            : request.op === 'feed'
+                ? parseICalendarFeed(request.input, request.calendarTimezone, request.window)
+                : parseTrustedICalendarEvents(request.input, request.calendarTimezone);
         reply = { id: request.id, ok: true, value };
     }
     catch (error) {

package/ical-worker.d.ts

@@ -1,9 +1,9 @@
-import { CalendarContractError, type ExternalCalendarChange, type ICalendarExpansionWindow } from './sync.js';
+import { CalendarContractError, type ExternalCalendarChange, type ICalendarExpansionWindow, type ICalendarFeedRead } from './sync.js';
 import type { TrustedICalendarEvent } from './types.js';
 /** What the pool posts to a worker. */
 export type ICalendarWorkerRequest = {
     id: number;
-    op: 'changes';
+    op: 'changes' | 'feed';
     input: string;
     calendarTimezone: string | undefined;
     window: ICalendarExpansionWindow | undefined;
@@ -29,8 +29,8 @@ export interface ICalendarWorkerPoolOptions {
     size?: number;
     /**
      * How long one parse may run on its worker, in ms, before the worker is stopped and the feed
-     * refused (CalendarExpansionLimitError), 100-60,000. Defaults to 3,000: three times the parser's
-     * own limit, with room for a new worker to start.
+     * refused (CalendarExpansionLimitError), 100-60,000. Defaults to 3,000: several times what the
+     * parser's step budget takes, with room for a new worker to start.
      */
     deadlineMs?: number;
     /** Parses that may wait for a worker, 0-10,000; more are refused at once. Defaults to 64. */
@@ -46,6 +46,8 @@ export interface ICalendarWorkerPoolOptions {
 export interface ICalendarWorkerPool {
     /** `parseICalendarChanges`, run on a worker. */
     parseICalendarChanges(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): Promise<ExternalCalendarChange[]>;
+    /** `parseICalendarFeed`, run on a worker. */
+    parseICalendarFeed(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): Promise<ICalendarFeedRead>;
     /** `parseTrustedICalendarEvents`, run on a worker. */
     parseTrustedICalendarEvents(input: string, calendarTimezone?: string): Promise<TrustedICalendarEvent[]>;
     /** Refuse waiting parses and stop every worker. */
@@ -63,7 +65,8 @@ export declare class ICalendarWorkerPoolClosedError extends Error {
 }
 /**
  * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges` and `parseTrustedICalendarEvents` (the same
+ * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
+ * `parseTrustedICalendarEvents` (the same
  * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
  * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.

package/ical-worker.js

@@ -31,7 +31,8 @@ function workerFailure(error) {
 }
 /**
  * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges` and `parseTrustedICalendarEvents` (the same
+ * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
+ * `parseTrustedICalendarEvents` (the same
  * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
  * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.
@@ -134,7 +135,7 @@ export function createICalendarWorkerPool(options = {}) {
         if (request.calendarTimezone !== undefined && typeof request.calendarTimezone !== 'string') {
             throw new CalendarContractError('invalid_icalendar');
         }
-        if (request.op === 'changes' &&
+        if (request.op !== 'trusted' &&
             request.window !== undefined &&
             !(request.window?.start instanceof Date && request.window.end instanceof Date)) {
             throw new CalendarContractError('invalid_icalendar');
@@ -172,6 +173,12 @@ export function createICalendarWorkerPool(options = {}) {
                 window,
             }));
         },
+        async parseICalendarFeed(input, calendarTimezone, expansionWindow) {
+            const window = expansionWindow
+                ? { start: expansionWindow.start, end: expansionWindow.end }
+                : undefined;
+            return (await run({ op: 'feed', input, calendarTimezone, window }));
+        },
         async parseTrustedICalendarEvents(input, calendarTimezone) {
             return (await run({ op: 'trusted', input, calendarTimezone }));
         },

package/index.d.ts

@@ -21,8 +21,8 @@ export type { SlotlockDashboard, SlotlockDashboardOptions, SlotlockDashboardReso
 export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';
-export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
-export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ITipMethod, } from './sync.js';
-export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
-export { calendarEventRollingHorizon, createSlotlockStore, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MAX_EVENT_DURATION_DAYS, type SlotlockHoldTenantOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantStore, } from './store.js';
-export type { AcquireHoldResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';
+export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
+export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ICalendarFeedRead, ICalendarSeriesRefusal, ITipMethod, } from './sync.js';
+export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
+export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
+export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -15,6 +15,6 @@ export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenan
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
-export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
-export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
-export { calendarEventRollingHorizon, createSlotlockStore, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MAX_EVENT_DURATION_DAYS, } from './store.js';
+export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
+export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
+export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, } from './store.js';

package/maintenance.d.ts

@@ -5,17 +5,27 @@ export interface SlotlockMaintenanceResult {
     extended: number;
     /** Series that could not extend because an occurrence would overlap a booking. */
     conflicts: number;
-    /** Series over the expansion budget; they keep their old coverage. */
+    /** Series over the expansion budget, or whose roll failed otherwise; they keep their old coverage. */
     refused: number;
-    /** Idempotency commands and tombstones deleted. */
+    /**
+     * Expired holds and the answers kept for keyed ones, and past the retention window event
+     * idempotency answers, agents' event cancellations and booking references retired with no
+     * booking, deleted. A cancelled booking's tombstone stays.
+     */
     pruned: number;
     /** More was left than one pass does: run another. */
     capped: boolean;
+    /**
+     * The roll stopped before the series it had put back: series it has not tried since may still
+     * extend, so another pass should follow at once.
+     */
+    rollPending: boolean;
 }
 /**
- * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then prune
- * past the retention window, each in at most `batches` batches (1-100, default 10), every batch its
- * own transaction. Aborting `signal` stops it between batches with the signal's reason.
+ * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
+ * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
+ * retention window, each in at most `batches` batches (1-100, default 10), every batch its own
+ * transaction. Aborting `signal` stops it between batches with the signal's reason.
  */
 export declare function maintainSlotlockTenant(store: SlotlockStore, tenantRef: string, options?: {
     batches?: number;

package/maintenance.js

@@ -1,9 +1,10 @@
 import { ignoreRejection } from './hooks.js';
 import { calendarEventRollingHorizon } from './store.js';
 /**
- * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then prune
- * past the retention window, each in at most `batches` batches (1-100, default 10), every batch its
- * own transaction. Aborting `signal` stops it between batches with the signal's reason.
+ * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
+ * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
+ * retention window, each in at most `batches` batches (1-100, default 10), every batch its own
+ * transaction. Aborting `signal` stops it between batches with the signal's reason.
  */
 export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     const batches = options.batches ?? 10;
@@ -16,31 +17,55 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     let refused = 0;
     let rollCapped = true;
     let after = null;
-    for (let batch = 0; batch < batches; batch++) {
-        options.signal?.throwIfAborted();
-        const from = after;
-        const roll = await store.withTenant(tenantRef, (tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
-        extended += roll.extended;
-        conflicts += roll.conflicts;
-        refused += roll.refused;
-        after = roll.next;
-        if (!after) {
-            rollCapped = false;
-            break;
+    // A roll that fails does not stop the pruning: expired holds are purged all the same, and the
+    // roll's error is thrown after.
+    let rollFailure = null;
+    try {
+        for (let batch = 0; batch < batches; batch++) {
+            options.signal?.throwIfAborted();
+            const from = after;
+            const roll = await store.withTenant(tenantRef, (tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
+            extended += roll.extended;
+            conflicts += roll.conflicts;
+            refused += roll.refused;
+            after = roll.next;
+            if (!after) {
+                rollCapped = false;
+                break;
+            }
         }
     }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        rollFailure = { error };
+    }
     let pruned = 0;
-    let pruneCapped = true;
-    for (let batch = 0; batch < batches; batch++) {
+    let eventsLeft = true;
+    let bookingsLeft = true;
+    for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft); batch++) {
         options.signal?.throwIfAborted();
-        const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
-        pruned += prune.commandsDeleted + prune.tombstonesDeleted;
-        if (!prune.hasMore) {
-            pruneCapped = false;
-            break;
+        if (eventsLeft) {
+            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
+            pruned += prune.commandsDeleted + prune.tombstonesDeleted;
+            eventsLeft = prune.hasMore;
+        }
+        if (bookingsLeft) {
+            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneBookingRetention({ tenantRef }));
+            pruned += prune.expiredHoldsDeleted + prune.holdCommandsDeleted + prune.tombstonesDeleted;
+            bookingsLeft = prune.hasMore;
         }
     }
-    return { extended, conflicts, refused, pruned, capped: rollCapped || pruneCapped };
+    if (rollFailure)
+        throw rollFailure.error;
+    return {
+        extended,
+        conflicts,
+        refused,
+        pruned,
+        capped: rollCapped || eventsLeft || bookingsLeft,
+        rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
+    };
 }
 /** The advisory lock key for one tenant's maintenance (64-bit, from the tenant reference). */
 const LOCK_NAMESPACE = 'slotlock.maintenance:';
@@ -119,9 +144,14 @@ export function startSlotlockMaintenance(options) {
                         catch {
                             // Reporting must never stop maintenance, or make a pass that ran look failed.
                         }
-                        // A capped pass that got somewhere goes round again at once; one that only met series it
-                        // cannot extend waits for the next interval rather than examine them again and again.
-                        again = result.capped && result.extended + result.pruned > 0;
+                        // A capped pass that got somewhere goes round again at once, as does one whose roll
+                        // stopped before the series it had put back: each series it could not extend is now
+                        // behind every one it has not tried (the store puts it there), so the next pass meets
+                        // new ones, and however many are stuck, each is met once before a healthy one is
+                        // reached. A pass that reached the series put back waits for the next interval: they
+                        // take turns there, and the next pass reaches anything new before them.
+                        const progressed = result.extended + result.pruned > 0;
+                        again = result.capped && (progressed || result.rollPending);
                     }
                 }
                 catch (error) {
@@ -165,8 +195,10 @@ export function startSlotlockMaintenance(options) {
             const previous = served.get(tenantRef);
             served.delete(tenantRef);
             served.set(tenantRef, previous ?? 0);
-            while (served.size > maxTenants)
-                served.delete(served.keys().next().value);
+            while (served.size > maxTenants) {
+                const forgotten = served.keys().next().value;
+                served.delete(forgotten);
+            }
             if (due(tenantRef))
                 enqueue(tenantRef);
         },

package/node-server.d.ts

@@ -1,9 +1,17 @@
 /// <reference types="node" preserve="true" />
 import { type Server } from 'node:http';
 export type SlotlockNodeServerErrorPhase = 'client' | 'listen' | 'request' | 'server' | 'shutdown';
+/** What the listener knows about a request's connection, beside the Request itself. */
+export interface SlotlockNodeServerConnection {
+    /**
+     * The peer's address as the socket reports it (an IPv4 client of a dual-stack listener reads
+     * `::ffff:a.b.c.d`). Behind a proxy it is the proxy's; never taken from a request field.
+     */
+    remoteAddress?: string;
+}
 /** The narrow Fetch-compatible boundary returned by `createSlotlockAgentServer`. */
 export interface SlotlockNodeServerFetchTarget {
-    fetch(request: Request): Promise<Response>;
+    fetch(request: Request, connection?: SlotlockNodeServerConnection): Promise<Response>;
     /**
      * Called once when `close()` begins, after the listener stops accepting connections, to end
      * long-lived responses (MCP subscription streams) so they drain within the grace period.

package/node-server.js

@@ -137,8 +137,9 @@ function toWebRequest(request, requestOrigin, signal) {
     }
     // URL parsing resolves dot segments, `%2E` spellings included: `/v1/resources/%2E%2E/availability`
     // would reach the target as `/v1/availability`, a path parameter of `..` naming another route.
+    // It also takes a backslash for a slash, so a segment ends at either.
     const path = target.split(/[?#]/, 1)[0] ?? '';
-    if (path.split('/').some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
+    if (path.split(/[\\/]/).some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
         throw new Error('invalid_request_target');
     }
     const url = new URL(target, requestOrigin);
@@ -281,7 +282,11 @@ export function createSlotlockNodeServer(target, options) {
             timeout.unref();
         });
         try {
-            const outcome = await Promise.race([target.fetch(webRequest), handlerTimeout]);
+            const connection = {};
+            if (request.socket.remoteAddress !== undefined) {
+                connection.remoteAddress = request.socket.remoteAddress;
+            }
+            const outcome = await Promise.race([target.fetch(webRequest, connection), handlerTimeout]);
             if (outcome === HANDLER_TIMEOUT) {
                 controller.abort(abortReason('handler_timeout'));
                 safeReport(config.onError, new Error('handler_timeout'), 'request');