slotlock 0.3.0 → 0.5.0

package/types.d.ts

@@ -1,3 +1,4 @@
+import type { SlotlockBookingRule, SlotlockBookingRules } from './booking-rules.js';
 /** Half-open time interval `[start, end)`. */
 export interface Interval {
     start: Date;
@@ -29,6 +30,13 @@ export interface SlotlockResource {
     visibility?: 'shared' | 'private';
     /** When the tenant archived it: no longer listed or booked, its history kept. Absent in use. */
     archivedAt?: Date;
+    /** What a booking on it must satisfy (`SlotlockBookingRules`). Absent when it has none. */
+    bookingRules?: SlotlockBookingRules;
+    /**
+     * The pool it belongs to: interchangeable resources sharing a name, such as a vehicle class or a
+     * room type, booked by the class (`slotlock_book_pool`). Absent when it is in none.
+     */
+    pool?: string;
 }
 /** A confirmed occupation of a resource. The DB EXCLUDE constraint is the overlap arbiter. */
 export interface SlotlockReservation {
@@ -115,6 +123,12 @@ export type ExternalReservationResult = {
     ok: false;
     code: 'reservation_limit_reached';
     limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -193,6 +207,12 @@ export type CreateReservationResult = {
     ok: false;
     code: 'reservation_limit_reached';
     limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -208,6 +228,24 @@ export interface SlotlockHold {
     bufferAfterMs: number;
     expiresAt: Date;
     source: string | null;
+    /** The alternatives it was held with (`groupId` when acquired); absent when held alone. */
+    groupId?: string;
+}
+/** One entry of a tenant's agenda (`listAgenda`): what occupies a resource, and from when. */
+export interface SlotlockAgendaEntry {
+    id: string;
+    resourceId: string;
+    start: Date;
+    end: Date;
+    /** A booking, a calendar event's occurrence, or a live hold. */
+    kind: 'booking' | 'event' | 'hold';
+    /** The booking's reference; null for an event's occurrence and a hold. */
+    reference: string | null;
+    /** The calendar event's summary; null for a booking and a hold. */
+    summary: string | null;
+    /** When the hold lapses; null for a booking and an event. */
+    expiresAt: Date | null;
+    source: string | null;
 }
 export type AcquireHoldResult = 
 /** `idempotent`: a retry of a keyed hold, answered with the hold the first request made. */
@@ -258,6 +296,21 @@ export type AcquireHoldResult =
     ok: false;
     code: 'hold_limit_reached';
     limit: number;
+}
+/**
+ * The holder's live holds would together hold more hours than `maxHeldHoursPerHolder` allows
+ * (`limit`, in hours): one agent cannot keep a resource's month from everyone, a hold at a time.
+ */
+ | {
+    ok: false;
+    code: 'held_time_limit_reached';
+    limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -387,6 +440,24 @@ export interface PutCalendarEventCommand extends CalendarEventContent {
     /** Mandatory for recurrence; bounded to 367 days. Defaults to the event interval otherwise. */
     materializationWindow?: Interval;
     source?: string;
+    /**
+     * Judge the event as a booking made now against the resource's booking rules (its first
+     * occurrence for notice and advance, every occurrence for step and hours), and keep the
+     * resource's turnaround after each occurrence. Off by default: an imported event is what happened
+     * elsewhere. The agent tools set it.
+     */
+    enforceBookingRules?: boolean;
+    /**
+     * Book the time a live hold keeps: the hold must be `holderRef`'s (`acquireHold`'s
+     * `principalRef`), on this resource, and cover the event, a single occurrence. In one transaction
+     * the hold and the rest of its group are released and the event takes the time, so no rival can
+     * come between. Its notice and advance were judged when it was held; step and hours are judged
+     * again.
+     */
+    fromHold?: {
+        holdId: string;
+        holderRef: string;
+    };
 }
 export type PutCalendarEventResult = {
     ok: true;
@@ -438,6 +509,16 @@ export type PutCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 }
+/** `fromHold` names no live hold of that holder's: released, booked, expired, or another's. */
+ | {
+    ok: false;
+    code: 'hold_not_found';
+}
+/** `fromHold`'s hold is on another resource, or does not cover the event. */
+ | {
+    ok: false;
+    code: 'hold_mismatch';
+}
 /**
  * A recurring event on the resource is not stored as far as this write reaches, and cannot be
  * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
@@ -445,6 +526,12 @@ export type PutCalendarEventResult = {
  | {
     ok: false;
     code: 'recurrence_not_materialized';
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';

package/types.js

@@ -1,3 +1 @@
-// Slotlock core types. Every interval is half-open `[start, end)`: back-to-back reservations do not
-// conflict, matching RFC 5545 interval semantics and PostgreSQL range boundaries.
 export {};

package/webhooks.d.ts

@@ -0,0 +1,91 @@
+import type { SlotlockChange, SlotlockEventFeed } from './event-feed.js';
+/** The CloudEvents envelope a change is delivered and listed as. */
+export interface SlotlockCloudEvent {
+    specversion: '1.0';
+    id: string;
+    source: string;
+    type: string;
+    subject: string;
+    time: string;
+    datacontenttype: 'application/json';
+    data: Record<string, unknown>;
+}
+/** A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`. */
+export declare function slotlockCloudEvent(change: SlotlockChange): SlotlockCloudEvent;
+/**
+ * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
+ * secret's bytes, of `id.timestamp.body`.
+ */
+export declare function signSlotlockWebhook(params: {
+    secret: string;
+    id: string;
+    timestamp: number;
+    body: string;
+}): string;
+/**
+ * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
+ * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
+ * sooner than the endpoint's Retry-After (capped at a day).
+ */
+export declare function slotlockWebhookRetryDelayMs(attempts: number, retryAfterMs?: number, random?: () => number): number;
+/** Whether `address` is one a webhook may not reach: loopback, private, link-local, and the like. */
+export declare function isPrivateAddress(address: string): boolean;
+export interface SlotlockWebhookResponse {
+    status: number;
+    /** From the response's Retry-After, when it gave one in seconds. */
+    retryAfterMs?: number;
+}
+export type SlotlockWebhookSender = (request: {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<SlotlockWebhookResponse>;
+/**
+ * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
+ * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
+ * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ */
+export declare function createSlotlockWebhookSender(options?: {
+    timeoutMs?: number;
+    allowPrivateNetworks?: boolean;
+}): SlotlockWebhookSender;
+export interface SlotlockWebhookPassResult {
+    /** Changes an endpoint accepted. */
+    delivered: number;
+    /** Endpoints whose next change failed, to be tried again later. */
+    failed: number;
+}
+/**
+ * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
+ * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
+ * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ */
+export declare function deliverSlotlockWebhooks(params: {
+    feed: Pick<SlotlockEventFeed, 'claimWebhookDeliveries' | 'settleWebhookDelivery'>;
+    tenantRef: string;
+    send: SlotlockWebhookSender;
+    batch?: number;
+    leaseMs?: number;
+    /** After this long (default 30,000 ms) no further change is sent this pass; the rest wait. */
+    budgetMs?: number;
+    now?: () => number;
+}): Promise<SlotlockWebhookPassResult>;
+export interface SlotlockWebhookScheduler {
+    /** Deliver for this tenant too (a server calls it for each tenant it serves). */
+    touch(tenantRef: string): void;
+    close(): Promise<void>;
+}
+/**
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
+ * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
+ * is reported and the next one runs as usual.
+ */
+export declare function startSlotlockWebhookDelivery(options: {
+    tenants: () => Promise<readonly string[]>;
+    /** Tenants delivered at once (1-64, default 8), so one slow tenant's endpoints hold up none other. */
+    concurrency?: number;
+    deliver: (tenantRef: string) => Promise<SlotlockWebhookPassResult>;
+    intervalMs?: number;
+    onPass?: (tenantRef: string, result: SlotlockWebhookPassResult) => void;
+    onError?: (error: unknown) => void;
+}): SlotlockWebhookScheduler;

package/webhooks.js

@@ -0,0 +1,300 @@
+// Webhook delivery of the event feed (RFC 0002 P1-5): each change is a CloudEvents 1.0 envelope,
+// signed and headed as Standard Webhooks asks (webhook-id, webhook-timestamp, webhook-signature),
+// sent to each endpoint in feed order, one at a time, and retried on a growing schedule until the
+// endpoint has failed for a day. The store keeps the position and the schedule (event-feed.ts), so
+// a worker that stops mid-batch loses nothing: the next one sends the rest, with the same ids.
+import { createHmac } from 'node:crypto';
+import { lookup as dnsLookup } from 'node:dns';
+import { Agent as HttpAgent, request as httpRequest } from 'node:http';
+import { Agent as HttpsAgent, request as httpsRequest } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+import { ignoreRejection } from './hooks.js';
+/** A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`. */
+export function slotlockCloudEvent(change) {
+    return {
+        specversion: '1.0',
+        id: change.id,
+        source: change.resourceId ? `/slotlock/resources/${change.resourceId}` : '/slotlock',
+        type: `io.pylota.slotlock.${change.type}`,
+        subject: change.subject,
+        time: change.occurredAt.toISOString(),
+        datacontenttype: 'application/json',
+        data: change.data,
+    };
+}
+/**
+ * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
+ * secret's bytes, of `id.timestamp.body`.
+ */
+export function signSlotlockWebhook(params) {
+    if (!params.secret.startsWith('whsec_'))
+        throw new TypeError('Slotlock webhook secret must start with whsec_');
+    const key = Buffer.from(params.secret.slice('whsec_'.length), 'base64');
+    const signature = createHmac('sha256', key)
+        .update(`${params.id}.${params.timestamp}.${params.body}`)
+        .digest('base64');
+    return `v1,${signature}`;
+}
+/**
+ * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
+ * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
+ * sooner than the endpoint's Retry-After (capped at a day).
+ */
+export function slotlockWebhookRetryDelayMs(attempts, retryAfterMs, random = Math.random) {
+    const schedule = [5_000, 300_000, 1_800_000, 7_200_000, 18_000_000, 36_000_000];
+    const base = schedule[Math.min(Math.max(attempts, 1), schedule.length) - 1];
+    const jittered = Math.round(base * (0.9 + random() * 0.2));
+    return Math.max(jittered, Math.min(retryAfterMs ?? 0, 86_400_000));
+}
+// One list per family: a BlockList also checks an IPv4 address against IPv6 rules through its
+// mapped form, so ::ffff:0:0/96 in the same list would match every IPv4 address.
+const PRIVATE_IPV4 = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['224.0.0.0', 3],
+]) {
+    PRIVATE_IPV4.addSubnet(address, prefix, 'ipv4');
+}
+const PRIVATE_IPV6 = new BlockList();
+for (const [address, prefix] of [
+    ['::', 96], // unspecified, loopback and IPv4-compatible
+    ['::ffff:0:0:0', 96], // IPv4-translated
+    ['64:ff9b::', 96], // NAT64
+    ['64:ff9b:1::', 48], // local-use NAT64
+    ['100::', 64], // discard
+    ['2001::', 32], // Teredo
+    ['2002::', 16], // 6to4
+    ['fc00::', 7], // unique local
+    ['fe80::', 10], // link-local
+    ['fec0::', 10], // site-local
+    ['ff00::', 8], // multicast
+]) {
+    PRIVATE_IPV6.addSubnet(address, prefix, 'ipv6');
+}
+/** Whether `address` is one a webhook may not reach: loopback, private, link-local, and the like. */
+export function isPrivateAddress(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return PRIVATE_IPV4.check(address, 'ipv4');
+    if (family !== 6)
+        return true;
+    // An IPv4-mapped address (::ffff:a.b.c.d, or its hex form) is the IPv4 address it carries.
+    const mapped = /^::ffff:(?:(\d+\.\d+\.\d+\.\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/i.exec(address);
+    if (mapped) {
+        if (mapped[1])
+            return PRIVATE_IPV4.check(mapped[1], 'ipv4');
+        const high = Number.parseInt(mapped[2], 16);
+        const low = Number.parseInt(mapped[3], 16);
+        return PRIVATE_IPV4.check(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`, 'ipv4');
+    }
+    return PRIVATE_IPV6.check(address, 'ipv6');
+}
+/**
+ * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
+ * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
+ * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ */
+export function createSlotlockWebhookSender(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const lookup = ((hostname, lookupOptions, callback) => {
+        dnsLookup(hostname, { ...lookupOptions, all: true }, (error, addresses) => {
+            if (error)
+                return callback(error);
+            const list = addresses;
+            if (!options.allowPrivateNetworks && list.some(({ address }) => isPrivateAddress(address))) {
+                return callback(Object.assign(new Error(`webhook host ${hostname} resolves to a private address`), { code: 'webhook_private_address' }));
+            }
+            const all = lookupOptions.all;
+            if (all)
+                return callback(null, list);
+            const first = list[0];
+            return first ? callback(null, first.address, first.family) : callback(new Error('no address'));
+        });
+    });
+    return (request) => new Promise((resolve, reject) => {
+        const url = new URL(request.url);
+        if (isIP(url.hostname.replace(/^\[|\]$/g, '')) && !options.allowPrivateNetworks) {
+            if (isPrivateAddress(url.hostname.replace(/^\[|\]$/g, ''))) {
+                reject(Object.assign(new Error('webhook URL names a private address'), { code: 'webhook_private_address' }));
+                return;
+            }
+        }
+        const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const outgoing = send(url, {
+            method: 'POST',
+            headers: { ...request.headers, 'Content-Length': String(Buffer.byteLength(request.body)) },
+            // An agent of its own, never the global one: with NODE_USE_ENV_PROXY a proxy from the
+            // environment would connect for us, and the address check below would never run.
+            agent: url.protocol === 'https:' ? new HttpsAgent({ lookup }) : new HttpAgent({ lookup }),
+            lookup,
+            timeout: timeoutMs,
+        }, (response) => {
+            let read = 0;
+            response.on('data', (chunk) => {
+                read += chunk.length;
+                if (read > 65_536)
+                    response.destroy();
+            });
+            const finish = () => {
+                const retryAfter = Number(response.headers['retry-after']);
+                resolve({
+                    status: response.statusCode ?? 0,
+                    ...(Number.isFinite(retryAfter) && retryAfter >= 0 ? { retryAfterMs: retryAfter * 1_000 } : {}),
+                });
+            };
+            response.on('end', finish);
+            response.on('close', finish);
+        });
+        const timedOut = () => outgoing.destroy(Object.assign(new Error('webhook request timed out'), { code: 'webhook_timeout' }));
+        outgoing.on('timeout', timedOut);
+        // `timeout` is idleness only: an answer dripped a byte at a time would hold the request
+        // open for hours. The whole exchange has this long.
+        const deadline = setTimeout(timedOut, timeoutMs);
+        deadline.unref?.();
+        outgoing.on('close', () => clearTimeout(deadline));
+        outgoing.on('error', reject);
+        outgoing.end(request.body);
+    });
+}
+/**
+ * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
+ * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
+ * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ */
+export async function deliverSlotlockWebhooks(params) {
+    const now = params.now ?? Date.now;
+    const claims = await params.feed.claimWebhookDeliveries({
+        tenantRef: params.tenantRef,
+        leaseMs: params.leaseMs ?? 60_000,
+        batch: params.batch ?? 20,
+    });
+    let delivered = 0;
+    let failed = 0;
+    const stopAt = now() + (params.budgetMs ?? 30_000);
+    await Promise.all(claims.map(async (claim) => {
+        let last;
+        let failure;
+        // The failures before this pass set the delay: the schedule grows across passes.
+        let attempts = claim.endpoint.attempts;
+        for (const change of claim.changes) {
+            if (now() >= stopAt)
+                break;
+            const body = JSON.stringify(slotlockCloudEvent(change));
+            const timestamp = Math.floor(now() / 1_000);
+            try {
+                const response = await params.send({
+                    url: claim.endpoint.url,
+                    headers: {
+                        'Content-Type': 'application/cloudevents+json',
+                        'User-Agent': 'Slotlock-Webhooks/1',
+                        'webhook-id': change.id,
+                        'webhook-timestamp': String(timestamp),
+                        'webhook-signature': signSlotlockWebhook({
+                            secret: claim.endpoint.secret,
+                            id: change.id,
+                            timestamp,
+                            body,
+                        }),
+                    },
+                    body,
+                });
+                if (response.status >= 200 && response.status < 300) {
+                    last = change.position;
+                    delivered++;
+                    continue;
+                }
+                attempts = last ? 1 : attempts + 1;
+                failure = {
+                    status: response.status,
+                    error: `HTTP ${response.status}`,
+                    retryInMs: slotlockWebhookRetryDelayMs(attempts, response.retryAfterMs),
+                    ...(response.status === 410 ? { gone: true } : {}),
+                };
+            }
+            catch (error) {
+                attempts = last ? 1 : attempts + 1;
+                const code = error.code;
+                failure = {
+                    status: null,
+                    error: typeof code === 'string' ? code : 'webhook_unreachable',
+                    retryInMs: slotlockWebhookRetryDelayMs(attempts),
+                };
+            }
+            break;
+        }
+        if (failure)
+            failed++;
+        await params.feed.settleWebhookDelivery({
+            tenantRef: params.tenantRef,
+            endpointId: claim.endpoint.id,
+            leaseToken: claim.leaseToken,
+            ...(last ? { delivered: last } : {}),
+            ...(failure ? { failure } : {}),
+        });
+    }));
+    return { delivered, failed };
+}
+/**
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
+ * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
+ * is reported and the next one runs as usual.
+ */
+export function startSlotlockWebhookDelivery(options) {
+    const intervalMs = options.intervalMs ?? 2_000;
+    if (!(Number.isSafeInteger(intervalMs) && intervalMs >= 250 && intervalMs <= 60_000)) {
+        throw new RangeError('Slotlock webhook interval must be 250-60,000 ms');
+    }
+    const touched = new Set();
+    let closed = false;
+    let running = null;
+    const concurrency = options.concurrency ?? 8;
+    if (!(Number.isSafeInteger(concurrency) && concurrency >= 1 && concurrency <= 64)) {
+        throw new RangeError('Slotlock webhook concurrency must be 1-64');
+    }
+    const pass = async () => {
+        const queue = [...new Set([...(await options.tenants()), ...touched])];
+        const worker = async () => {
+            for (let tenantRef = queue.shift(); tenantRef !== undefined && !closed; tenantRef = queue.shift()) {
+                try {
+                    const result = await options.deliver(tenantRef);
+                    if (result.delivered + result.failed > 0)
+                        options.onPass?.(tenantRef, result);
+                }
+                catch (error) {
+                    options.onError?.(error);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, worker));
+    };
+    const timer = setInterval(() => {
+        // A pass still running skips this tick rather than queue another behind it.
+        if (running || closed)
+            return;
+        running = pass()
+            .catch((error) => options.onError?.(error))
+            .finally(() => {
+            running = null;
+        });
+        ignoreRejection(running);
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        touch(tenantRef) {
+            touched.add(tenantRef);
+        },
+        async close() {
+            closed = true;
+            clearInterval(timer);
+            await running;
+        },
+    };
+}