slotlock 0.2.0 → 0.3.0

package/agent-store-backend.js

@@ -5,18 +5,76 @@ import { expandRules } from './rules.js';
 import { calendarEventRollingHorizon } from './store.js';
 import { maintainSlotlockTenant } from './maintenance.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
+/**
+ * A write runs under READ COMMITTED whatever the role's default: a store given tenant limits (as
+ * `slotlock serve`'s is) counts it against them under the tenant's lock, which needs that level,
+ * and refuses it otherwise.
+ */
+const WRITE = { isolation: 'read committed' };
 function assertActive(context) {
     if (context.signal.aborted)
         throw new SlotlockAgentOperationError('request_aborted', 503);
 }
 async function withTenant(store, context, callback, options) {
     assertActive(context);
-    const value = options === undefined
-        ? await store.withTenant(context.principal.tenantRef, callback)
-        : await store.withTenant(context.principal.tenantRef, callback, options);
+    let value;
+    try {
+        value = await store.withTenant(context.principal.tenantRef, callback, {
+            ...options,
+            signal: context.signal,
+        });
+    }
+    catch (error) {
+        const code = error?.code;
+        // A suspended tenant may read; a write it asks for is forbidden, not a server failure.
+        if (code === 'tenant_suspended')
+            throw new SlotlockAgentOperationError('tenant_suspended', 403);
+        // Waited past the store's lock timeout behind the tenant's own writes: retry later.
+        if (code === 'lock_timeout')
+            throw new SlotlockAgentOperationError('server_busy', 503);
+        assertActive(context);
+        throw error;
+    }
     assertActive(context);
     return value;
 }
+/**
+ * Busy intervals one free/busy read or search may gather across all the resources it names: as many
+ * as the store reads for one resource. Without it, a request naming 100 resources at that limit, or
+ * one resource 100 times, did 100 times the work of one.
+ */
+const MAX_REQUEST_BUSY_INTERVALS = 10_000;
+/**
+ * Bookable windows one search may expand from its resources' availability rules in all: five
+ * resources of 50 daily rules over a year, or a hundred of two. Without it, a search of 100 such
+ * resources over a year expanded 1.8 million windows and held the process for seven seconds.
+ */
+const MAX_REQUEST_RULE_WINDOWS = 100_000;
+/** The resources a request names, each once, in the order first named. */
+function distinctResourceIds(input) {
+    return [...new Set(input.resource_ids)];
+}
+/** Counts a request's busy intervals against MAX_REQUEST_BUSY_INTERVALS, refusing past it. */
+function busyBudget() {
+    let left = MAX_REQUEST_BUSY_INTERVALS;
+    return (intervals) => {
+        left -= intervals;
+        if (left < 0)
+            throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+    };
+}
+/** The store's free/busy read, its refusal to read past its limit answered as the caller's to narrow. */
+async function readFreeBusy(tenantStore, params) {
+    try {
+        return await tenantStore.getFreeBusy(params);
+    }
+    catch (error) {
+        if (error?.code === 'calendar_work_limit') {
+            throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+        }
+        throw error;
+    }
+}
 function interval(input) {
     return { start: new Date(input.start), end: new Date(input.end) };
 }
@@ -181,25 +239,41 @@ function parseEventCursor(value) {
         throw new SlotlockAgentOperationError('invalid_cursor', 400);
     }
 }
-function encodeEventCursor(event) {
-    return Buffer.from(JSON.stringify({ start: event.start.toISOString(), id: event.id }), 'utf8').toString('base64url');
+/** The cursor after one row of a page ordered by start then id: an event, a hold or a booking. */
+function encodeEventCursor(row) {
+    return Buffer.from(JSON.stringify({ start: row.start.toISOString(), id: row.id }), 'utf8').toString('base64url');
+}
+/** One page of rows read with one more than `limit`, and the cursor to the next when there is one. */
+function page(rows, limit) {
+    const shown = rows.slice(0, limit);
+    const last = shown.at(-1);
+    return { shown, next: rows.length > limit && last ? encodeEventCursor(last) : null };
 }
 /**
  * The caller's resource with this id, or `resource_not_found`. The tools accept any id an agent may
  * send (an external reference such as `vehicle-42`, the nil UUID, a version 7 UUID). The store
  * issues version 4 UUIDs (gen_random_uuid) and refuses an id that is not a version 1 to 5 UUID as an
  * invalid identity, so such an id names no resource: it is not found, like a well-formed id that
- * names nothing or another tenant's resource.
+ * names nothing or another tenant's resource. With `visibility`, a resource of the other is not
+ * found either: agents ask for `shared`, so a private resource is invisible to them.
  */
-async function requireResource(tenantStore, tenantRef, resourceId) {
+async function requireResource(tenantStore, tenantRef, resourceId, visibility) {
     if (!STORE_ID_PATTERN.test(resourceId)) {
         throw new SlotlockAgentOperationError('resource_not_found', 404);
     }
-    const resource = await tenantStore.getResource({ tenantRef, id: resourceId });
+    const resource = await tenantStore.getResource({
+        tenantRef,
+        id: resourceId,
+        ...(visibility !== undefined ? { visibility } : {}),
+    });
     if (!resource)
         throw new SlotlockAgentOperationError('resource_not_found', 404);
     return resource;
 }
+/** The caller's shared resource with this id: what an agent may see and book. */
+function requireAgentResource(tenantStore, tenantRef, resourceId) {
+    return requireResource(tenantStore, tenantRef, resourceId, 'shared');
+}
 /** Bind the protocol server to the production store without giving a request control of tenancy. */
 export function createSlotlockStoreAgentBackend(store, options) {
     return {
@@ -210,6 +284,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const resource = await tenantStore.getResource({
                     tenantRef: context.principal.tenantRef,
                     id: resourceId,
+                    visibility: 'shared',
                 });
                 return resource
                     ? { name: resource.externalRef ?? null, timezone: resource.timezone }
@@ -222,6 +297,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const limit = input.limit;
                 const resources = await tenantStore.listResources({
                     tenantRef: context.principal.tenantRef,
+                    visibility: 'shared',
                     limit: limit + 1,
                     ...(cursor !== undefined ? { after: cursor } : {}),
                 });
@@ -238,13 +314,14 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async getFreeBusy(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
+            const charge = busyBudget();
             return withTenant(store, context, async (tenantStore) => {
                 const resources = [];
                 for (const resourceId of resourceIds) {
-                    const resource = await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    const resource = await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     const sources = await requiredSources(options, context, resource);
-                    const result = await tenantStore.getFreeBusy({
+                    const result = await readFreeBusy(tenantStore, {
                         tenantRef: context.principal.tenantRef,
                         resourceId,
                         window,
@@ -253,6 +330,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                             ? { coverageMaxAgeMs: options.coverageMaxAgeMs }
                             : {}),
                     });
+                    charge(result.busy.length);
                     resources.push({
                         resource_id: resourceId,
                         busy: result.busy.map((busy) => ({
@@ -267,15 +345,17 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async findNextAvailable(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
             const durationMs = input.duration_minutes * 60_000;
+            const charge = busyBudget();
+            let windowsLeft = MAX_REQUEST_RULE_WINDOWS;
             return withTenant(store, context, async (tenantStore) => {
                 let best = null;
                 let incomplete = false;
                 for (const resourceId of resourceIds) {
-                    const resource = await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    const resource = await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     const sources = await requiredSources(options, context, resource);
-                    const freeBusy = await tenantStore.getFreeBusy({
+                    const freeBusy = await readFreeBusy(tenantStore, {
                         tenantRef: context.principal.tenantRef,
                         resourceId,
                         window,
@@ -284,16 +364,17 @@ export function createSlotlockStoreAgentBackend(store, options) {
                             ? { coverageMaxAgeMs: options.coverageMaxAgeMs }
                             : {}),
                     });
+                    charge(freeBusy.busy.length);
                     if (freeBusy.coverage.state !== 'complete') {
                         incomplete = true;
                         continue;
                     }
                     const rules = resource.availabilityRules ?? (await options.availabilityRules(context, resource));
-                    const candidate = findNextAvailable({
-                        busy: freeBusy.busy,
-                        windows: expandRules(rules, window, resource.timezone),
-                        durationMs,
-                    });
+                    const windows = expandRules(rules, window, resource.timezone);
+                    windowsLeft -= windows.length;
+                    if (windowsLeft < 0)
+                        throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+                    const candidate = findNextAvailable({ busy: freeBusy.busy, windows, durationMs });
                     if (candidate &&
                         (!best ||
                             candidate.start.getTime() < best.interval.start.getTime() ||
@@ -317,7 +398,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
         async createEvent(context, rawInput) {
             const input = rawInput;
             return withTenant(store, context, async (tenantStore) => {
-                await requireResource(tenantStore, context.principal.tenantRef, input.resource_id);
+                await requireAgentResource(tenantStore, context.principal.tenantRef, input.resource_id);
                 const recurrence = recurrenceFromInput(input.recurrence_rule, input.recurrence_exceptions);
                 const content = {
                     start: new Date(input.starts_at),
@@ -361,7 +442,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 if (!created)
                     throw new SlotlockAgentOperationError('store_inconsistent', 503);
                 return { event: projectSlotlockCalendarEvent(created), replayed: result.idempotent };
-            });
+            }, WRITE);
         },
         async getEvent(context, input) {
             return withTenant(store, context, async (tenantStore) => {
@@ -377,13 +458,13 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async listEvents(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
             const limit = input.limit;
             const after = parseEventCursor(input.cursor);
             return withTenant(store, context, async (tenantStore) => {
                 const combined = [];
                 for (const resourceId of resourceIds) {
-                    await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     combined.push(...(await tenantStore.listCalendarEvents({
                         tenantRef: context.principal.tenantRef,
                         ownerRef: agentOwnerRef(context),
@@ -404,6 +485,11 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async updateEvent(context, rawInput) {
             const input = rawInput;
+            // No event is on a resource the store never issued (an external reference, say).
+            if (input.expected_resource_id !== undefined &&
+                !STORE_ID_PATTERN.test(input.expected_resource_id)) {
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            }
             return withTenant(store, context, async (tenantStore) => {
                 const current = await tenantStore.getCalendarEvent({
                     tenantRef: context.principal.tenantRef,
@@ -414,7 +500,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     throw new SlotlockAgentOperationError('event_not_found', 404);
                 const resourceId = input.resource_id ?? current.resourceId;
                 if (resourceId !== current.resourceId) {
-                    await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                 }
                 const recurrence = input.recurrence_rule === null
                     ? undefined
@@ -473,6 +559,9 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     tenantRef: context.principal.tenantRef,
                     ownerRef: agentOwnerRef(context),
                     externalRef: current.externalRef,
+                    // The caller's fence when it sent one, checked under the event's lock; otherwise the
+                    // resource just read, so a move between that read and the write is not overwritten.
+                    expectedResourceId: input.expected_resource_id ?? current.resourceId,
                     resourceId,
                     expectedRevision: input.expected_revision,
                     idempotencyKey: agentCommandIdempotencyKey(context, input.idempotency_key),
@@ -490,7 +579,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 if (!updated)
                     throw new SlotlockAgentOperationError('store_inconsistent', 503);
                 return { event: projectSlotlockCalendarEvent(updated), replayed: result.idempotent };
-            });
+            }, WRITE);
         },
         async deleteEvent(context, input) {
             return withTenant(store, context, async (tenantStore) => {
@@ -506,6 +595,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     tenantRef: context.principal.tenantRef,
                     ownerRef: agentOwnerRef(context),
                     externalRef,
+                    expectedResourceId: current.resourceId,
                     idempotencyKey: agentCommandIdempotencyKey(context, input.idempotency_key),
                     expectedRevision: input.expected_revision,
                 });
@@ -517,7 +607,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     deleted: true,
                     replayed: result.idempotent,
                 };
-            });
+            }, WRITE);
         },
     };
 }
@@ -526,8 +616,9 @@ function storeRefusal(error) {
     const code = error?.code;
     if (typeof code !== 'string')
         return error;
-    if (code === 'resource_limit_reached')
+    if (code === 'resource_limit_reached' || code === 'resource_visibility_conflict') {
         return new SlotlockAgentOperationError(code, 409);
+    }
     if (code.startsWith('invalid_') && code !== 'invalid_transaction_isolation') {
         return new SlotlockAgentOperationError(code, 400);
     }
@@ -574,6 +665,17 @@ function resourceOutput(resource) {
         external_ref: resource.externalRef,
         timezone: resource.timezone,
         availability: rulesOutput(resource.availabilityRules),
+        visibility: resource.visibility ?? 'shared',
+        archived_at: resource.archivedAt?.toISOString() ?? null,
+    };
+}
+/** Any of a tenant's events: the store's id, which the tenant-event routes take, and its owner's. */
+function tenantEventOutput(event) {
+    return {
+        ...projectSlotlockCalendarEvent(event),
+        id: event.id,
+        event_ref: event.externalRef,
+        owner_ref: event.ownerRef,
     };
 }
 function holdOutput(hold) {
@@ -599,6 +701,26 @@ function reservationOutput(reservation) {
         source: reservation.source,
     };
 }
+/**
+ * The namespace an application caller's idempotency keys live in: a digest of its tenant and
+ * subject, so the authenticated subject never lands in a durable row.
+ */
+function applicationPrincipalRef(context) {
+    return `application:${createHash('sha256')
+        .update(`${context.principal.tenantRef}\0${context.principal.subject}`)
+        .digest('hex')}`;
+}
+/**
+ * An application caller's event command key: its tenant, subject and own key, digested, so one
+ * caller's key never replays another's command and neither the subject nor the raw key is stored.
+ */
+function applicationCommandKey(context, idempotencyKey) {
+    return `application-command:${createHash('sha256')
+        .update(`${context.principal.tenantRef}\0${context.principal.subject}\0${idempotencyKey}`)
+        .digest('hex')}`;
+}
+/** The most busy intervals one slotlock_list_busy answers, as one free/busy request reads. */
+const MAX_LISTED_BUSY = MAX_REQUEST_BUSY_INTERVALS;
 /**
  * Serve the application API (application-api.ts) from the production store, in the principal's
  * tenant. Every resource an operation names must be the tenant's, or it is not found; holds are
@@ -613,6 +735,7 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
     if (!(Number.isSafeInteger(batches) && batches >= 1 && batches <= 100)) {
         throw new RangeError('maintenanceBatches must be a whole number from 1 to 100');
     }
+    const tenantErasure = options.tenantErasure === true;
     const tenantOf = (context) => context.principal.tenantRef;
     return {
         async createResource(context, input) {
@@ -623,6 +746,9 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                         tenantRef: tenantOf(context),
                         externalRef: input.external_ref,
                         timezone: input.timezone,
+                        ...(input.visibility !== undefined
+                            ? { visibility: input.visibility }
+                            : {}),
                         ...(max !== undefined ? { maxTenantResources: max } : {}),
                     });
                     return { resource: resourceOutput(resource) };
@@ -637,6 +763,59 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 resource: resourceOutput(await requireResource(tenant, tenantOf(context), input.resource_id)),
             }));
         },
+        async archiveResource(context, input) {
+            const id = input.resource_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('resource_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await tenant.archiveResource({ tenantRef: tenantOf(context), id });
+                if (!resource)
+                    throw new SlotlockAgentOperationError('resource_not_found', 404);
+                return { resource: resourceOutput(resource) };
+            }, WRITE);
+        },
+        async restoreResource(context, input) {
+            const id = input.resource_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('resource_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await tenant.restoreResource({ tenantRef: tenantOf(context), id });
+                if (!resource)
+                    throw new SlotlockAgentOperationError('resource_not_found', 404);
+                return { resource: resourceOutput(resource) };
+            }, WRITE);
+        },
+        async deleteResource(context, input) {
+            const id = input.resource_id;
+            // An id the store never issues names no resource: there is nothing to delete.
+            if (!STORE_ID_PATTERN.test(id))
+                return { deleted: false };
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.deleteResource({ tenantRef: tenantOf(context), id });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { deleted: result.deleted };
+            }, WRITE);
+        },
+        async listBusy(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                // One row past the cap is enough to refuse: the rest is never read.
+                const busy = await tenant.listBusy(resource.id, interval(input), {
+                    tenantRef: tenantOf(context),
+                    limit: MAX_LISTED_BUSY + 1,
+                });
+                if (busy.length > MAX_LISTED_BUSY) {
+                    throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+                }
+                return {
+                    busy: busy.map((occupied) => ({
+                        start: occupied.start.toISOString(),
+                        end: occupied.end.toISOString(),
+                    })),
+                };
+            });
+        },
         async setResourceAvailability(context, input) {
             const rules = rulesInput(input.rules);
             const id = input.resource_id;
@@ -675,15 +854,51 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
             return withTenant(store, context, async (tenant) => {
                 const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
                 const result = await tenant.acquireHold({
+                    tenantRef: tenantOf(context),
                     resourceId: resource.id,
                     start: new Date(input.start),
                     end: new Date(input.end),
                     ttlMs: input.ttl_seconds * 1_000,
                     ...(input.source !== undefined ? { source: input.source } : {}),
+                    ...(input.buffer_after_minutes !== undefined
+                        ? { bufferAfterMs: input.buffer_after_minutes * 60_000 }
+                        : {}),
+                    // A retried request with the caller's key answers the hold the first one made.
+                    ...(input.idempotency_key !== undefined
+                        ? {
+                            idempotencyKey: input.idempotency_key,
+                            principalRef: applicationPrincipalRef(context),
+                        }
+                        : {}),
                 });
                 if (!result.ok)
                     throw applicationRefusal(result.code);
                 return { hold: holdOutput(result.hold) };
+            }, WRITE);
+        },
+        async getHold(context, input) {
+            const id = input.hold_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('hold_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const hold = await tenant.getHold({ tenantRef: tenantOf(context), holdId: id });
+                if (!hold)
+                    throw new SlotlockAgentOperationError('hold_not_found', 404);
+                return { hold: holdOutput(hold) };
+            });
+        },
+        async listHolds(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listHolds({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { holds: shown.map(holdOutput), next_cursor: next };
             });
         },
         async confirmHold(context, input) {
@@ -695,7 +910,7 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 if (!result.ok)
                     throw applicationRefusal(result.code);
                 return { reservation: reservationOutput(result.reservation) };
-            });
+            }, WRITE);
         },
         async releaseHold(context, input) {
             const id = input.hold_id;
@@ -706,6 +921,32 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 released: (await tenant.releaseHold(id, { tenantRef: tenantOf(context) })).released,
             }));
         },
+        async getReservation(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const reservation = await tenant.getReservation({
+                    tenantRef: tenantOf(context),
+                    externalRef: input.reservation_ref,
+                });
+                if (!reservation)
+                    throw new SlotlockAgentOperationError('reservation_not_found', 404);
+                return { reservation: reservationOutput(reservation) };
+            });
+        },
+        async listReservations(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listReservations({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    window: interval(input),
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { reservations: shown.map(reservationOutput), next_cursor: next };
+            });
+        },
         async putReservation(context, input) {
             return withTenant(store, context, async (tenant) => {
                 const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
@@ -725,7 +966,7 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 if (!result.ok)
                     throw applicationRefusal(result.code);
                 return { reservation: reservationOutput(result.reservation), replayed: result.idempotent };
-            });
+            }, WRITE);
         },
         async cancelReservation(context, input) {
             return withTenant(store, context, async (tenant) => {
@@ -737,7 +978,7 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 if (!result.ok)
                     throw applicationRefusal(result.code);
                 return { cancelled: result.cancelled, revision: result.revision };
-            });
+            }, WRITE);
         },
         async recordCoverage(context, input) {
             return withTenant(store, context, async (tenant) => {
@@ -752,17 +993,95 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 if (!result.ok)
                     throw applicationRefusal(result.code);
                 return { revision: result.revision, replayed: result.idempotent };
+            }, WRITE);
+        },
+        async listTenantEvents(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listCalendarEvents({
+                    tenantRef: tenantOf(context),
+                    allOwners: true,
+                    resourceId: resource.id,
+                    window: interval(input),
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { events: shown.map(tenantEventOutput), next_cursor: next };
             });
         },
+        async getTenantEvent(context, input) {
+            const id = input.event_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const event = await tenant.getCalendarEventById({ tenantRef: tenantOf(context), eventId: id });
+                if (!event)
+                    throw new SlotlockAgentOperationError('event_not_found', 404);
+                return { event: tenantEventOutput(event) };
+            });
+        },
+        async cancelTenantEvent(context, input) {
+            const id = input.event_id;
+            const expectedResourceId = input.expected_resource_id;
+            // An id the store never issues names no event, and no event is on a resource it never issued.
+            if (!STORE_ID_PATTERN.test(id) ||
+                (expectedResourceId !== undefined && !STORE_ID_PATTERN.test(expectedResourceId))) {
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            }
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.cancelCalendarEventById({
+                    tenantRef: tenantOf(context),
+                    eventId: id,
+                    idempotencyKey: applicationCommandKey(context, input.idempotency_key),
+                    expectedRevision: input.expected_revision,
+                    ...(expectedResourceId !== undefined ? { expectedResourceId } : {}),
+                });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return {
+                    event_id: result.eventId,
+                    revision: result.revision,
+                    cancelled: true,
+                    replayed: result.idempotent,
+                };
+            }, WRITE);
+        },
+        async getTenant(context) {
+            return withTenant(store, context, async (tenant) => ({
+                tenant: {
+                    ref: tenantOf(context),
+                    suspended: await tenant.isTenantSuspended({ tenantRef: tenantOf(context) }),
+                },
+            }));
+        },
+        async eraseTenant(context, input) {
+            if (!tenantErasure)
+                throw new SlotlockAgentOperationError('tenant_erasure_disabled', 403);
+            // The reference, not a yes: a key of another tenant than the caller believes cannot erase it.
+            if (input.confirm_tenant_ref !== tenantOf(context)) {
+                throw new SlotlockAgentOperationError('invalid_confirmation', 400);
+            }
+            return withTenant(store, context, async (tenant) => {
+                // Read under the tenant's lock, which a suspension waits for: a suspended tenant's data is
+                // kept for its operator, who erases it (slotlock tenant erase) when they decide to.
+                if (await tenant.isTenantSuspended({ tenantRef: tenantOf(context) })) {
+                    throw new SlotlockAgentOperationError('tenant_suspended', 403);
+                }
+                const erased = await tenant.eraseTenant({ tenantRef: tenantOf(context) });
+                return { total: erased.total, rows: erased.rows };
+            }, WRITE);
+        },
         async runMaintenance(context) {
             assertActive(context);
             try {
-                return {
-                    ...(await maintainSlotlockTenant(store, tenantOf(context), {
-                        batches,
-                        signal: context.signal,
-                    })),
-                };
+                // A caller goes round again while `capped`; when to do so at once is the scheduler's.
+                const { rollPending: _, ...result } = await maintainSlotlockTenant(store, tenantOf(context), {
+                    batches,
+                    signal: context.signal,
+                });
+                return result;
             }
             catch (error) {
                 if (context.signal.aborted)

package/api-keys.d.ts

@@ -117,7 +117,10 @@ export declare function createSlotlockApiKeyStore(sql: SlotlockSql): SlotlockApi
 export interface SlotlockApiKeyAuthenticatorOptions {
     /** Key lookups that may run at once, default 2: at most this many connections serve them. */
     maxConcurrentLookups?: number;
-    /** Lookups that may wait for one, default 256. A request beyond that is anonymous at once. */
+    /**
+     * Lookups that may wait for one, default 256, and as many again for keys that recently
+     * authenticated. A request beyond that is refused as busy at once.
+     */
     maxWaitingLookups?: number;
 }
 /**
@@ -126,7 +129,12 @@ export interface SlotlockApiKeyAuthenticatorOptions {
  * `authorize`. A value that is not a well-formed key is anonymous without a lookup.
  *
  * Anyone can make well-formed keys, so lookups are bounded: a flood of made-up keys waits for at
- * most `maxConcurrentLookups` connections and is refused past `maxWaitingLookups`, and the rest of
- * the pool stays free for authenticated work. Rate-limit a public server in front of it as well.
+ * most `maxConcurrentLookups` connections, and past `maxWaitingLookups` a request is refused with a
+ * `SlotlockAgentOperationError` (`server_busy`, 503) rather than answered anonymous, which would
+ * tell a client holding a valid key that its key is bad. A key that authenticated in the last 15
+ * minutes waits in a queue of its own that is served first, so made-up keys, which never
+ * authenticate, cannot keep it waiting. Every request is still looked up, so a revoked key stops
+ * at once. Rate-limit a public server in front of it as well (`slotlock serve` does, per client
+ * address, before any lookup).
  */
 export declare function createSlotlockApiKeyAuthenticator(keys: Pick<SlotlockApiKeyStore, 'authenticate'>, options?: SlotlockApiKeyAuthenticatorOptions): (request: Request) => Promise<SlotlockAgentPrincipal | null>;