@roko-app/instant-admin 1.0.67-roko.2 → 1.0.67-roko.3

package/src/alarms.ts

@@ -0,0 +1,342 @@
+// Roko DB: alarms. An alarm asks the server to POST a signed JSON body to a
+// url at a given time. One alarm per key; setting a key again replaces it.
+
+// #region Types
+
+/** Where an alarm is in its life. */
+export type AlarmStatus =
+  /** Waits for its time. */
+  | 'pending'
+  /** Being delivered right now. */
+  | 'processing'
+  /** A delivery failed; it will be retried. */
+  | 'error'
+  /** Delivered. */
+  | 'fired'
+  /** Gave up after the last retry, or the endpoint answered 410 Gone. */
+  | 'failed';
+
+/** The last delivery attempt of an alarm. */
+export type AlarmAttempt = {
+  /** When the attempt was made (ISO 8601). */
+  at: string | null;
+  /** True if the endpoint answered with a 2xx status. */
+  success: boolean;
+  /** HTTP status of the answer, if there was one. */
+  statusCode: number | null;
+  /** Kind of failure when there was no answer, e.g. `timeout` or `dns`. */
+  errorType: string | null;
+  errorMessage: string | null;
+};
+
+/** An alarm as the server stores it. */
+export type AlarmInfo = {
+  /** Changes every time the key is set again; also the `Idempotency-Key` of its deliveries. */
+  id: string;
+  /** Your name for the alarm, unique per app. */
+  key: string;
+  /** When it fires (ISO 8601). */
+  fireAt: string;
+  /** The https url that is called. */
+  url: string;
+  /** Sent back to you, unchanged, when the alarm fires. */
+  payload: Record<string, unknown> | null;
+  status: AlarmStatus;
+  /** How many deliveries were attempted. */
+  attempts: number;
+  lastAttempt: AlarmAttempt | null;
+  /** When the next retry happens, while `status` is `error`. */
+  nextAttemptAfter: string | null;
+  firedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** The body POSTed to the alarm's url when it fires. */
+export type AlarmEvent = {
+  type: 'alarm';
+  id: string;
+  appId: string;
+  key: string;
+  /** The time the alarm was set for (ISO 8601). */
+  fireAt: string;
+  /** 1 for the first delivery, 2 for the first retry, and so on. */
+  attempt: number;
+  payload: Record<string, unknown> | null;
+};
+
+export type SetAlarmParams = {
+  /** Your name for the alarm. Setting the same key again replaces the alarm. */
+  key: string;
+  /** When to fire: a Date, milliseconds since the epoch, or an ISO 8601 string. A time in the past fires at once. */
+  fireAt: Date | number | string;
+  /** A public https url. It receives a POST signed with `Instant-Signature`. */
+  url: string;
+  /** A JSON object (64 KB at most) sent back to you when the alarm fires. */
+  payload?: Record<string, unknown> | null;
+};
+
+export type ListAlarmsParams = {
+  /** Keep one status only. */
+  status?: AlarmStatus;
+  /** Page size, 100 by default, 1000 at most. */
+  limit?: number;
+  /** Continue after this `fireAt` (the last alarm of the previous page). */
+  after?: Date | number | string;
+};
+
+export type AlarmValidateOpts = {
+  receivedAt?: Date | null;
+  /** Oldest signature accepted, in seconds. Default 300. */
+  tolerance?: number | null;
+};
+
+type AlarmsDeps = {
+  apiURI: string;
+  appId: string;
+  /** Builds the authorized request headers; throws without an admin token. */
+  headers: () => Record<string, string>;
+  jsonFetch: (input: string, init?: RequestInit) => Promise<unknown>;
+  /** Checks an `Instant-Signature` header and returns the verified body text. */
+  verifySignature: (
+    signatureHeader: string,
+    body: string | (() => Promise<string>),
+    opts?: AlarmValidateOpts | null,
+  ) => Promise<string>;
+};
+
+// #endregion
+
+// #region Parsing
+
+const ALARM_STATUSES: readonly AlarmStatus[] = [
+  'pending',
+  'processing',
+  'error',
+  'fired',
+  'failed',
+];
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+
+function isAlarmStatus(x: unknown): x is AlarmStatus {
+  return ALARM_STATUSES.some((status) => status === x);
+}
+
+function stringOrNull(x: unknown): string | null {
+  return typeof x === 'string' ? x : null;
+}
+
+function numberOrNull(x: unknown): number | null {
+  return typeof x === 'number' ? x : null;
+}
+
+function requiredString(source: Record<string, unknown>, field: string) {
+  const value = source[field];
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid alarm: expected a string in \`${field}\`.`);
+  }
+  return value;
+}
+
+function parseAttempt(x: unknown): AlarmAttempt | null {
+  if (!isRecord(x)) {
+    return null;
+  }
+  return {
+    at: stringOrNull(x.at),
+    success: x.success === true,
+    statusCode: numberOrNull(x.statusCode),
+    errorType: stringOrNull(x.errorType),
+    errorMessage: stringOrNull(x.errorMessage),
+  };
+}
+
+function parseAlarm(x: unknown): AlarmInfo {
+  if (!isRecord(x)) {
+    throw new Error('Invalid alarm: expected an object.');
+  }
+  if (!isAlarmStatus(x.status)) {
+    throw new Error('Invalid alarm: unknown status.');
+  }
+  return {
+    id: requiredString(x, 'id'),
+    key: requiredString(x, 'key'),
+    fireAt: requiredString(x, 'fireAt'),
+    url: requiredString(x, 'url'),
+    payload: isRecord(x.payload) ? x.payload : null,
+    status: x.status,
+    attempts: numberOrNull(x.attempts) ?? 0,
+    lastAttempt: parseAttempt(x.lastAttempt),
+    nextAttemptAfter: stringOrNull(x.nextAttemptAfter),
+    firedAt: stringOrNull(x.firedAt),
+    createdAt: requiredString(x, 'createdAt'),
+    updatedAt: requiredString(x, 'updatedAt'),
+  };
+}
+
+/** Reads a verified alarm body. Throws if it is not an alarm. */
+export function parseAlarmEvent(bodyText: string): AlarmEvent {
+  const body: unknown = JSON.parse(bodyText);
+  if (!isRecord(body) || body.type !== 'alarm') {
+    throw new Error(
+      'Invalid alarm body, expected an object with type "alarm".',
+    );
+  }
+  return {
+    type: 'alarm',
+    id: requiredString(body, 'id'),
+    appId: requiredString(body, 'appId'),
+    key: requiredString(body, 'key'),
+    fireAt: requiredString(body, 'fireAt'),
+    attempt: numberOrNull(body.attempt) ?? 1,
+    payload: isRecord(body.payload) ? body.payload : null,
+  };
+}
+
+/** Turns a Date / epoch milliseconds / ISO string into what the server takes. */
+export function toAlarmTime(time: Date | number | string): number | string {
+  if (time instanceof Date) {
+    const ms = time.getTime();
+    if (Number.isNaN(ms)) {
+      throw new Error('Invalid alarm time: the Date is not valid.');
+    }
+    return ms;
+  }
+  return time;
+}
+
+// #endregion
+
+// #region Alarms
+
+/**
+ * Alarms: ask the server to call your url at a given time.
+ *
+ * @example
+ *  // When work starts, ask to be called if it is not done in one hour.
+ *  await db.alarms.set({
+ *    key: `effort:${taskId}`,
+ *    fireAt: Date.now() + 60 * 60 * 1000,
+ *    url: 'https://example.com/api/alarms',
+ *    payload: { taskId },
+ *  });
+ *
+ *  // In the route behind that url.
+ *  export async function POST(req: Request) {
+ *    const alarm = await db.alarms.validateRequest(req);
+ *    await pauseTask(alarm.payload);
+ *    return new Response('ok');
+ *  }
+ */
+export class Alarms {
+  #deps: AlarmsDeps;
+
+  constructor(deps: AlarmsDeps) {
+    this.#deps = deps;
+  }
+
+  #url(query?: Record<string, string>): string {
+    const qs = new URLSearchParams({ app_id: this.#deps.appId, ...query });
+    return `${this.#deps.apiURI}/admin/alarms?${qs.toString()}`;
+  }
+
+  /**
+   * Creates the alarm for `key`, or replaces the one that exists. A replaced
+   * alarm starts over with a new id, even if it had already fired.
+   */
+  set = async (params: SetAlarmParams): Promise<AlarmInfo> => {
+    const res = await this.#deps.jsonFetch(this.#url(), {
+      method: 'PUT',
+      headers: this.#deps.headers(),
+      body: JSON.stringify({
+        key: params.key,
+        fireAt: toAlarmTime(params.fireAt),
+        url: params.url,
+        payload: params.payload ?? null,
+      }),
+    });
+    return parseAlarm(isRecord(res) ? res.alarm : null);
+  };
+
+  /** Returns the alarm for `key`, or null if there is none. */
+  get = async (key: string): Promise<AlarmInfo | null> => {
+    const res = await this.#deps.jsonFetch(this.#url({ key }), {
+      method: 'GET',
+      headers: this.#deps.headers(),
+    });
+    const alarm = isRecord(res) ? res.alarm : null;
+    return alarm == null ? null : parseAlarm(alarm);
+  };
+
+  /** Lists the app's alarms, soonest first. */
+  list = async (params: ListAlarmsParams = {}): Promise<AlarmInfo[]> => {
+    const query: Record<string, string> = {};
+    if (params.status) {
+      query.status = params.status;
+    }
+    if (params.limit !== undefined) {
+      query.limit = String(params.limit);
+    }
+    if (params.after !== undefined) {
+      const after = toAlarmTime(params.after);
+      query.after =
+        typeof after === 'number' ? new Date(after).toISOString() : after;
+    }
+    const res = await this.#deps.jsonFetch(this.#url(query), {
+      method: 'GET',
+      headers: this.#deps.headers(),
+    });
+    const alarms = isRecord(res) ? res.alarms : null;
+    return Array.isArray(alarms) ? alarms.map(parseAlarm) : [];
+  };
+
+  /** Deletes the alarm for `key`. Returns false if there was none. */
+  delete = async (key: string): Promise<boolean> => {
+    const res = await this.#deps.jsonFetch(this.#url({ key }), {
+      method: 'DELETE',
+      headers: this.#deps.headers(),
+    });
+    return isRecord(res) && res.deleted === true;
+  };
+
+  /**
+   * Verifies the `Instant-Signature` header of an alarm delivery against its
+   * raw body and returns the alarm. Throws if the signature is wrong or too
+   * old, if the body is not an alarm, or if the alarm belongs to another app.
+   */
+  validate = async (
+    signatureHeader: string,
+    body: string | (() => Promise<string>),
+    opts?: AlarmValidateOpts | null,
+  ): Promise<AlarmEvent> => {
+    const bodyText = await this.#deps.verifySignature(
+      signatureHeader,
+      body,
+      opts,
+    );
+    const event = parseAlarmEvent(bodyText);
+    // The signing key is the server's, shared by every app on it: without
+    // this check another app could aim its own alarm at this endpoint.
+    if (event.appId !== this.#deps.appId) {
+      throw new Error('Alarm belongs to another app');
+    }
+    return event;
+  };
+
+  /** Same as {@link validate}, reading the header and body from a `Request`. */
+  validateRequest = async (
+    req: Request,
+    opts?: AlarmValidateOpts | null,
+  ): Promise<AlarmEvent> => {
+    const signatureHeader = req.headers.get('instant-signature');
+    if (!signatureHeader) {
+      throw new Error('Request is missing Instant-Signature header');
+    }
+    return this.validate(signatureHeader, () => req.text(), opts);
+  };
+}
+
+// #endregion

package/src/index.ts

@@ -99,6 +99,16 @@ import {
 import { parseCookie } from 'cookie';
 import { EventSource } from '@instantdb/eventsource';
 import { MessageEventPolyfill } from './polyfill.ts';
+import {
+  Alarms,
+  type AlarmStatus,
+  type AlarmAttempt,
+  type AlarmInfo,
+  type AlarmEvent,
+  type SetAlarmParams,
+  type ListAlarmsParams,
+  type AlarmValidateOpts,
+} from './alarms.ts';
 import {
   Webhooks,
   WebhooksManager,
@@ -1142,6 +1152,8 @@ class InstantAdminDatabase<
   rooms: Rooms<Schema>;
   impersonationOpts?: ImpersonationOpts;
   webhooks: Webhooks<Schema>;
+  /** Roko DB: ask the server to call your url at a given time. */
+  alarms: Alarms;
 
   #sseConnection: SSEConnection | null = null;
   #sseBackoff = 0;
@@ -1157,6 +1169,14 @@ class InstantAdminDatabase<
     this.streams = new Streams(this.#ensureInstantStream.bind(this));
     this.rooms = new Rooms<Schema>(this.config);
     this.webhooks = new Webhooks<Schema>(this.config, jsonFetch);
+    this.alarms = new Alarms({
+      apiURI: this.config.apiURI,
+      appId: this.config.appId,
+      headers: () => authorizedHeaders(this.config),
+      jsonFetch,
+      verifySignature: (signatureHeader, body, opts) =>
+        this.webhooks.verifySignature(signatureHeader, body, opts),
+    });
     this.#log = createLogger(!!this.config.verbose, this.config.logger);
   }
 
@@ -1627,6 +1647,14 @@ export {
   type InstantRouteHandlerPayloadByType,
   type InstantRouteHandlerType,
   type InstantRouteHandlerBody,
+  Alarms,
+  type AlarmStatus,
+  type AlarmAttempt,
+  type AlarmInfo,
+  type AlarmEvent,
+  type SetAlarmParams,
+  type ListAlarmsParams,
+  type AlarmValidateOpts,
   Webhooks,
   WebhooksManager,
   type WebhookAction,