@sanoma-ai/workflows 0.7.0 → 0.7.1

package/src/wakeup-driver.ts

@@ -0,0 +1,270 @@
+import { z } from "zod";
+import { type CallContext, defineDriver, DriverError, retryableStatus } from "./op.ts";
+import type { PlanAction } from "./resource.ts";
+import { defineSteps } from "./steps.ts";
+import type { WakeupRegistration } from "./wakeup.ts";
+import { instanceUrl, mintInstanceToken, WAKEUP_TOKEN } from "./wakeup-service.ts";
+import { wakeupOps } from "./wakeup-type.ts";
+
+// `sanoma.wakeup`'s operations over a wakeup service (`WakeupApi`): the driver's call it over
+// HTTP (plain `fetch`, the service has no SDK), the fake's (`fakeSanomaWakeup` in `fake.ts`)
+// answer from its state. Both go through `wakeupCalls`, so they plan, post the token and refuse
+// alike. `config.ts` puts the two together as the built-in `sanomaWakeup`.
+
+/** An instance as the service shows it (`GET /wakeup/instances/{id}`): the fields read here. */
+const instanceSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  at: z.string().nullable(),
+  lastError: z.string().nullable(),
+});
+export type Instance = z.output<typeof instanceSchema>;
+
+/** The wakeup service, as the operations use it. Each call fails with a `DriverError`. */
+export interface WakeupApi {
+  /**
+   * `POST /wakeup/instances { url, token }` with the account's token: the instance the token
+   * names, made, or moved to `url` when the account registered it before.
+   */
+  put(url: string, token: string): Promise<{ id: string }>;
+  /** `GET /wakeup/instances/{id}` with the account's token; undefined when there is none (404). */
+  get(id: string): Promise<Instance | undefined>;
+  /** `DELETE /wakeup/instances/{id}` with the account's token; nothing when there is none. */
+  remove(id: string): Promise<void>;
+  /** `PUT /wakeup/wake { at }` with the instance's token, which names the instance. */
+  wake(registration: WakeupRegistration, token: string): Promise<void>;
+}
+
+/** What the service holds of an instance that registered no wake: a new one's, and one moved to a new URL. */
+export const UNREGISTERED = { at: null, lastError: null } as const;
+
+export const fail = (message: string, status: number) =>
+  new DriverError(`sanoma.wakeup: ${message}`, { retryable: retryableStatus(status), status });
+
+/** The driver's own refusal, before or instead of a call: never retried. */
+const refused = (message: string, vendorCode?: string) =>
+  new DriverError(`sanoma.wakeup: ${message}`, { retryable: false, ...(vendorCode && { vendorCode }) });
+
+/** A wakeup's state: the service's instance, its URL as `host`. */
+const stateOf = ({ id, url, at, lastError }: Instance) => ({ id, host: url, at, lastError });
+type State = ReturnType<typeof stateOf>;
+
+/** What `plan` finds: the action, what it would leave, and the state it planned from. */
+interface Planned {
+  action: PlanAction;
+  planned?: Record<string, unknown>;
+  state?: State;
+  unknown: string[];
+  replace: string[];
+}
+
+/** A URL as the service keeps it (`instanceUrl`, the service's own rule), or as given when the service would refuse it. */
+const normalUrl = (url: unknown) => {
+  const checked = instanceUrl(url);
+  return "url" in checked ? checked.url : String(url);
+};
+
+/**
+ * The wakeup type's operations and `wakeup.register` over `api()`, made on each call. The
+ * instance's token, `SANOMA_WAKEUP_TOKEN`, names the instance: `create` and `update` both post it
+ * with the host's URL (minted and stored first when none is, as for a data file written by hand),
+ * so a new host is the same instance moved, never a replace; `register` sends it.
+ */
+export function wakeupCalls(api: () => WakeupApi) {
+  const read = async ({ id }: { id: string }) => {
+    const found = await api().get(id);
+    return found ? { id, gone: false, state: stateOf(found) } : { id, gone: true };
+  };
+  /**
+   * The instance the stored token names, at the desired host: made or moved, its state as a new
+   * one's (a repeat after a lost reply keeps the wake the service holds, which the next read shows).
+   */
+  const put = async (desired: Record<string, unknown>, { secrets }: CallContext) => {
+    const host = normalUrl(desired.host);
+    const token = await secrets.ensure(WAKEUP_TOKEN, mintInstanceToken);
+    const { id } = await api().put(host, token);
+    const state: State = { id, host, ...UNREGISTERED };
+    return { id, state };
+  };
+  const plan = async ({ id, desired }: { id?: string; desired?: Record<string, unknown> }): Promise<Planned> => {
+    const state = id === undefined ? undefined : (await read({ id })).state;
+    const none = { unknown: [], replace: [] };
+    if (!desired) return { action: state ? "delete" : "none", state, ...none };
+    const planned = { host: normalUrl(desired.host) };
+    if (!state) return { action: "create", planned, unknown: ["id"], replace: [] };
+    if (planned.host === state.host) return { action: "none", planned: state, state, ...none };
+    // A move forgets the wake registered at the old URL, as the service does.
+    return { action: "update", planned: { ...state, ...planned, ...UNREGISTERED }, state, ...none };
+  };
+  return {
+    import: read,
+    read,
+    plan: async (input: { id?: string; desired?: Record<string, unknown> }) => {
+      const { state: _, ...out } = await plan(input);
+      return out;
+    },
+    create: ({ desired }: { desired: Record<string, unknown> }, call: CallContext) => put(desired, call),
+    update: async (
+      {
+        id,
+        desired,
+        expect,
+      }: { id: string; desired: Record<string, unknown>; expect?: { action: PlanAction; replace: string[] } },
+      call: CallContext,
+    ) => {
+      const fresh = await plan({ id, desired });
+      if (expect && (expect.action !== fresh.action || expect.replace.join() !== fresh.replace.join())) {
+        throw refused(`update: the plan changed (${expect.action}, now ${fresh.action})`, "plan_changed");
+      }
+      if (fresh.state && fresh.action === "none") return { id, state: fresh.state };
+      return put(desired, call);
+    },
+    delete: async ({ id }: { id: string }) => {
+      await api().remove(id);
+      return { id, gone: true as const };
+    },
+    register: async (registration: WakeupRegistration, { secrets }: CallContext) => {
+      const token = await secrets.get(WAKEUP_TOKEN);
+      if (!token)
+        throw refused(
+          `register: ${WAKEUP_TOKEN} is not set: connect a wakeup service in /setup, then apply the wakeup`,
+        );
+      await api().wake(registration, token);
+      return {};
+    },
+  };
+}
+
+/** The environment variables the driver reads, on every call. */
+const env = z.object({
+  SANOMA_WAKEUP_URL: z.url().optional().describe("the wakeup service's URL: Sanoma's, or your own `sanoma wakeup`"),
+  SANOMA_WAKEUP_ACCOUNT_TOKEN: z
+    .string()
+    .startsWith("swa_", "an account's token starts swa_")
+    .optional()
+    .describe("an account's token at the wakeup service (swa_…), which creates and deletes the instances"),
+  // No check of its form: a host's own wakeup (Cloudflare's alarm) takes this variable too, and
+  // the service refuses a token that is not an instance's.
+  [WAKEUP_TOKEN]: z
+    .string()
+    .optional()
+    .describe(
+      "this instance's token at the wakeup service (swi_…), which /setup mints and the wakeup's create registers",
+    ),
+});
+
+/** The variable `name`, read when an operation is called, or the driver's refusal. */
+function required(name: "SANOMA_WAKEUP_URL" | "SANOMA_WAKEUP_ACCOUNT_TOKEN"): string {
+  const value = process.env[name];
+  if (!value) throw refused(`${name} is not set (${env.shape[name].description})`);
+  return value;
+}
+
+const Posted = z.object({ id: z.string() });
+/** The service's error body. */
+const Problem = z.object({ error: z.string() });
+
+const instance = (id: string) => `/wakeup/instances/${encodeURIComponent(id)}`;
+
+/** The service at `SANOMA_WAKEUP_URL`, read when an operation is called: each request's failure a `DriverError`. */
+function serviceApi(timeoutMs: number): WakeupApi {
+  const base = required("SANOMA_WAKEUP_URL").replace(/\/+$/, "");
+  if (!URL.canParse(base)) throw refused("SANOMA_WAKEUP_URL is not a URL");
+  const account = () => required("SANOMA_WAKEUP_ACCOUNT_TOKEN");
+  /**
+   * One request: its reply parsed by `reply` (none: not read), a 404 `undefined` where `absent`
+   * says it means no such instance, and any other answer but a 2xx a `DriverError`.
+   */
+  const send = async <T>(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    token: string,
+    { reply, body, absent = false }: { reply?: z.ZodType<T>; body?: unknown; absent?: boolean } = {},
+  ): Promise<T | undefined> => {
+    const where = `${method} ${path}`;
+    let res: Response;
+    let text: string;
+    try {
+      res = await fetch(`${base}${path}`, {
+        method,
+        signal: AbortSignal.timeout(timeoutMs),
+        // A redirect is no answer of the service's, and would carry the token elsewhere.
+        redirect: "manual",
+        headers: {
+          authorization: `Bearer ${token}`,
+          accept: "application/json",
+          ...(body !== undefined && { "content-type": "application/json" }),
+        },
+        ...(body !== undefined && { body: JSON.stringify(body) }),
+      });
+      text = await res.text();
+    } catch (cause) {
+      // No answer: the request may or may not have reached the service.
+      const why = (cause as Error).name === "TimeoutError" ? `no reply in ${timeoutMs} ms` : "the request failed";
+      throw new DriverError(`sanoma.wakeup: ${where}: ${why}`, { retryable: true, cause });
+    }
+    const { status } = res;
+    let json: unknown;
+    try {
+      json = text ? JSON.parse(text) : undefined;
+    } catch {
+      // A proxy's HTML page, say: no body to read.
+    }
+    // The service's own 404 (its `{ error }`), not another server's at that URL.
+    if (status === 404 && absent && Problem.safeParse(json).success) return undefined;
+    if (status < 200 || status >= 300)
+      throw fail(`${where}: ${Problem.safeParse(json).data?.error ?? `HTTP ${status}`}`, status);
+    if (!reply) return undefined;
+    const parsed = reply.safeParse(json);
+    if (!parsed.success) {
+      throw new DriverError(
+        `sanoma.wakeup: ${where}: the reply is not a wakeup service's; is SANOMA_WAKEUP_URL right?`,
+        {
+          retryable: false,
+          status,
+          cause: parsed.error,
+        },
+      );
+    }
+    return parsed.data;
+  };
+  return {
+    put: async (url, token) => {
+      try {
+        return (await send("POST", "/wakeup/instances", account(), { reply: Posted, body: { url, token } }))!;
+      } catch (error) {
+        // Another account's instance's token: the advice is the company's, so it is here, not the service's.
+        if (!(error instanceof DriverError) || error.status !== 409) throw error;
+        throw new DriverError(
+          `${error.message}: a new account needs a new instance token (store the new account's token in /setup, which mints one)`,
+          { retryable: false, status: 409, cause: error },
+        );
+      }
+    },
+    get: (id) => send("GET", instance(id), account(), { reply: instanceSchema, absent: true }),
+    async remove(id) {
+      await send("DELETE", instance(id), account(), { absent: true });
+    },
+    async wake({ at }, token) {
+      await send("PUT", "/wakeup/wake", token, { body: { at } });
+    },
+  };
+}
+
+/**
+ * The real wakeup service at `SANOMA_WAKEUP_URL`: instances created, read and deleted with
+ * `SANOMA_WAKEUP_ACCOUNT_TOKEN`, each named by its `SANOMA_WAKEUP_TOKEN` (which `create` and
+ * `register` send). `timeoutMs` is how long one request may take: 10 s by default.
+ */
+export function sanomaWakeupDriver({ timeoutMs = 10_000 }: { timeoutMs?: number } = {}) {
+  return defineDriver(wakeupOps, { wakeup: wakeupCalls(() => serviceApi(timeoutMs)) }, { env });
+}
+
+/** The wakeup's step for Gherkin tests: an instance at the service before the run, named `wakeup` (`$wakeup.id`). */
+export const wakeupSteps = defineSteps("sanoma", ({ given }) => {
+  given("a sanoma wakeup for {string}", (host: string) => ({
+    op: wakeupOps.wakeup.create,
+    input: { desired: { host } },
+    as: "wakeup",
+  }));
+});

package/src/wakeup-service.ts

@@ -8,10 +8,10 @@ import { errorMessage } from "./shared.ts";
  * `@sanoma-ai/workflows/wakeup-service`: the service that wakes stopped instances, server-side
  * only. An account (minted by whoever runs the service) registers an instance by its URL and the
  * instance's own token, which the company mints (`mintInstanceToken`) and keeps; the instance,
- * before it stops, `PUT`s with that token when it wants waking and a
- * generation; the service then calls `GET {url}/wake?generation=N`, retrying until an answer is a
- * 2xx. It makes its two tables itself, in the database it is given (sanoma-ops's own, when it
- * hosts it): never among `db.ts`'s, which every company's database gets.
+ * before it stops, `PUT`s with that token when it wants waking, replacing what it asked before;
+ * the service then calls `GET {url}/wake`, retrying until an answer is a 2xx. It makes its two
+ * tables itself, in the database it is given (sanoma-ops's own, when it hosts it): never among
+ * `db.ts`'s, which every company's database gets.
  */
 
 /** Where the accounts live: one per party that registers instances, its token's hash alone. */
@@ -29,7 +29,7 @@ const TABLES: readonly [what: string, ddl: string][] = [
     "wakeup instances",
     `CREATE TABLE IF NOT EXISTS ${WAKEUP_INSTANCES_TABLE} (id uuid PRIMARY KEY, ` +
       `account_id uuid NOT NULL REFERENCES ${WAKEUP_ACCOUNTS_TABLE} (id), url text NOT NULL, ` +
-      "token_hash text UNIQUE NOT NULL, at timestamptz, generation bigint NOT NULL DEFAULT 0, " +
+      "token_hash text UNIQUE NOT NULL, at timestamptz, " +
       "called_at timestamptz, attempts integer NOT NULL DEFAULT 0, next_attempt_at timestamptz, " +
       "last_error text, created_at timestamptz NOT NULL DEFAULT now())",
   ],
@@ -169,7 +169,7 @@ async function jsonBody(request: Request): Promise<Record<string, unknown> | und
 
 /**
  * An instance's URL as it is stored, without a trailing slash, or why it is refused: `http(s)`, no
- * user or password, no query, no fragment (`/wake?generation=N` is added to it).
+ * user or password, no query, no fragment (`/wake` is added to it).
  */
 export function instanceUrl(value: unknown): { url: string } | { error: string } {
   const refused = { error: "url must be an http(s) URL with no user, password, query or fragment" };
@@ -184,7 +184,6 @@ interface InstanceRow {
   account_id: string;
   url: string;
   at: Date | null;
-  generation: string;
   called_at: Date | null;
   attempts: number;
   last_error: string | null;
@@ -195,7 +194,6 @@ const shownInstance = (row: InstanceRow) => ({
   id: row.id,
   url: row.url,
   at: row.at?.toISOString() ?? null,
-  generation: Number(row.generation),
   calledAt: row.called_at?.toISOString() ?? null,
   attempts: row.attempts,
   lastError: row.last_error,
@@ -249,10 +247,10 @@ export async function mintWakeupAccount(databaseUrl: string, label: string): Pro
  *   token, 200 `{ id }` for one the account registered already, its URL now the given one (a lost
  *   reply, or a host that moved; its registered wake kept only when the URL is the same), 409 for
  *   another account's
- * - `GET /wakeup/instances/{id}`, its account's token → `{ id, url, at, generation, calledAt, attempts, lastError }`
+ * - `GET /wakeup/instances/{id}`, its account's token → `{ id, url, at, calledAt, attempts, lastError }`
  * - `DELETE /wakeup/instances/{id}`, its account's token → 204
- * - `PUT /wakeup/wake { at, generation }`, an instance's own token, which names the instance → 204,
- *   applied only when `generation` is newer than the one it has, and waking the loop
+ * - `PUT /wakeup/wake { at }`, an instance's own token, which names the instance → 204, replacing
+ *   the wake it had, and waking the loop
  *
  * 401 without a token or with an unknown one, 403 for another account's instance, 400 for a bad
  * body, 404 for an unknown id or path.
@@ -303,7 +301,6 @@ export async function startWakeupService({
       `INSERT INTO ${WAKEUP_INSTANCES_TABLE} AS i (id, account_id, url, token_hash) VALUES ($1, $2, $3, $4) ` +
         "ON CONFLICT (token_hash) DO UPDATE SET url = EXCLUDED.url, " +
         "at = CASE WHEN i.url = EXCLUDED.url THEN i.at END, " +
-        "generation = CASE WHEN i.url = EXCLUDED.url THEN i.generation ELSE 0 END, " +
         "called_at = CASE WHEN i.url = EXCLUDED.url THEN i.called_at END, " +
         "attempts = CASE WHEN i.url = EXCLUDED.url THEN i.attempts ELSE 0 END, " +
         "next_attempt_at = CASE WHEN i.url = EXCLUDED.url THEN i.next_attempt_at END, " +
@@ -330,17 +327,13 @@ export async function startWakeupService({
     const given = await jsonBody(request);
     if (given instanceof Response) return given;
     const at = given?.at;
-    const generation = given?.generation;
     if (typeof at !== "string" || !ISO_DATE_TIME.test(at) || Number.isNaN(Date.parse(at)))
       return problem(400, "at must be an ISO 8601 date-time");
-    // A new instance has generation 0, so a registration counts from 1.
-    if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 1)
-      return problem(400, "generation must be an integer, 1 or more");
-    // An older or equal generation changes nothing: callers retry, at least once each.
+    // Whatever it had is replaced: a wake that arrives for an older one starts a worker with nothing to do.
     await pool.query(
-      `UPDATE ${WAKEUP_INSTANCES_TABLE} SET at = $2, generation = $3, called_at = NULL, attempts = 0, ` +
-        "next_attempt_at = NULL, last_error = NULL WHERE id = $1 AND generation < $3",
-      [id, new Date(at), generation],
+      `UPDATE ${WAKEUP_INSTANCES_TABLE} SET at = $2, called_at = NULL, attempts = 0, ` +
+        "next_attempt_at = NULL, last_error = NULL WHERE id = $1",
+      [id, new Date(at)],
     );
     loop.poke();
     return noContent();
@@ -387,7 +380,7 @@ export async function startWakeupService({
 interface Due {
   id: string;
   url: string;
-  generation: string;
+  at: Date;
 }
 
 /**
@@ -412,7 +405,7 @@ function startLoop({
 
   /** Calls `row`'s instance once, and records how it went, unless the registration changed meanwhile. */
   async function call(row: Due) {
-    const target = `${row.url}/wake?generation=${row.generation}`;
+    const target = `${row.url}/wake`;
     let error: string | undefined;
     try {
       const signal = AbortSignal.any([stopping.signal, AbortSignal.timeout(CALL_TIMEOUT_MS)]);
@@ -425,14 +418,14 @@ function startLoop({
     }
     // Stopped mid-call: nothing is known of it, so it is called again once its claim lapses.
     if (stopping.signal.aborted) return;
-    // Recorded only on the registration called: one replaced (a newer generation), or moved to
-    // another URL (its generation counted again from 0), is called again.
-    const same = "WHERE id = $1 AND generation = $2 AND url = $3";
+    // Recorded only on the registration called: one replaced (another `at`), or moved to another
+    // URL, is called again.
+    const same = "WHERE id = $1 AND at = $2 AND url = $3";
     if (error === undefined) {
       await pool.query(
         `UPDATE ${WAKEUP_INSTANCES_TABLE} SET called_at = $4, attempts = 0, next_attempt_at = NULL, ` +
           `last_error = NULL ${same}`,
-        [row.id, row.generation, row.url, now()],
+        [row.id, row.at, row.url, now()],
       );
       log.info(`wakeup: called ${target}`);
     } else {
@@ -440,7 +433,7 @@ function startLoop({
         `UPDATE ${WAKEUP_INSTANCES_TABLE} SET attempts = attempts + 1, last_error = $4, ` +
           `next_attempt_at = $5::timestamptz + least(power(2, attempts), ${MAX_BACKOFF_S}) * interval '1 second' ` +
           same,
-        [row.id, row.generation, row.url, error, now()],
+        [row.id, row.at, row.url, error, now()],
       );
       log.warn(`wakeup: calling ${target} failed (${error}); it is tried again`);
     }
@@ -453,7 +446,7 @@ function startLoop({
       `UPDATE ${WAKEUP_INSTANCES_TABLE} SET next_attempt_at = $1::timestamptz + interval '${CLAIM_S} seconds' ` +
         `WHERE id IN (SELECT i.id FROM ${WAKEUP_INSTANCES_TABLE} i ${LIVE} WHERE ${WAITING} ` +
         "AND i.at <= $1 AND (i.next_attempt_at IS NULL OR i.next_attempt_at <= $1) " +
-        `ORDER BY i.at LIMIT ${ROUND_ROWS} FOR UPDATE OF i SKIP LOCKED) RETURNING id, url, generation`,
+        `ORDER BY i.at LIMIT ${ROUND_ROWS} FOR UPDATE OF i SKIP LOCKED) RETURNING id, url, at`,
       [now()],
     );
     const queue = [...rows];

package/src/wakeup-type.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { type Connector, defineConnector, type OpSpec } from "./op.ts";
+import { SANOMA_INFO } from "./person.ts";
+import { defineResource } from "./resource.ts";
+
+// The runtime's own wakeup, `sanoma.wakeup({ host })`: an instance of a wakeup service (`sanoma
+// wakeup`, `wakeup-service.ts`: sanoma-ops's, or one of the company's own) that calls the host's
+// `GET /wake` at the time the worker registered before it stopped. The fallback for a host with no
+// clock of its own; every config with a host type has it (`resolveConfig`), so no connector is
+// needed. Its driver is `wakeup-driver.ts`, its fake `fakeSanomaWakeup` in `fake.ts`, and `config.ts`
+// puts them together as `sanomaWakeup`. The service has no SDK or OpenAPI spec, so
+// the schemas are a cut of its own JSON, by hand.
+
+/**
+ * The host types a wakeup may name: each one a data file declares a wakeup for. A new host type
+ * is added here. `testhost.app` is `@sanoma-ai/testing`'s, for the conformance kits.
+ */
+const HOSTS = ["cloudflare.container", "docker.container", "testhost.app"] as const;
+
+/** An instance of the wakeup service, as `GET /wakeup/instances/{id}` shows it. */
+const wakeupSchema = z.object({
+  host: z
+    .string()
+    .min(1)
+    .describe("The host's URL, which the service calls `/wake` under: a data file names the host's declaration"),
+  id: z.string().optional().describe("The instance's id at the service"),
+  at: z.string().nullable().optional().describe("When the instance asked to be woken last, null until it has"),
+  lastError: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Why the last call to the host's `/wake` failed, null when it answered"),
+});
+
+/**
+ * `sanoma.wakeup({ host })`: an instance of a wakeup service for the host a data file names,
+ * which it calls at the time the worker registers (`sanoma.wakeup.register`). The service names
+ * it, so a declaration has no identity: its binding is its id. Apply creates it with the
+ * account's token (`SANOMA_WAKEUP_ACCOUNT_TOKEN`) and the instance's own, `SANOMA_WAKEUP_TOKEN`,
+ * which the company minted (`/setup`) and which names the instance: a new host is the same
+ * instance moved.
+ */
+export const wakeup = defineResource({
+  vendor: "sanoma",
+  type: "wakeup",
+  title: "Wakeup",
+  schema: wakeupSchema,
+  fields: {
+    immutable: [],
+    vendorOwned: ["id", "at", "lastError"],
+    writeOnly: [],
+    references: { host: { type: HOSTS, by: ["url"] } },
+  },
+  writable: true,
+  // The service holds its registered wake: apply asks before it deletes one.
+  stateless: false,
+  wakeup: {
+    inputs: { host: "host" },
+    register: "sanoma.wakeup.register",
+    outputs: (state) => ({ healthy: typeof state.id === "string" && state.lastError == null }),
+  },
+});
+
+const types = defineConnector("sanoma", { wakeup }, SANOMA_INFO);
+
+/** `wakeup.register`, in the wakeup type's own group, beside its resource operations. */
+const registerSpec = {
+  register: {
+    effect: "write",
+    // Each replaces the wake registered before: a retry changes nothing.
+    idempotent: true,
+    description: "Ask the wakeup service to call the host's /wake at `at`, replacing the wake registered before",
+    input: z.object({ at: z.iso.datetime({ offset: true }).describe("When to wake the host, ISO 8601") }),
+    output: z.object({}),
+  },
+} satisfies Record<string, OpSpec>;
+
+const register = defineConnector("sanoma", { wakeup: registerSpec });
+
+/** The wakeup's specs: the type's operations and `register` in one group. */
+type WakeupSpecs = { wakeup: (typeof wakeup)["ops"] & typeof registerSpec };
+
+/**
+ * The wakeup's operations: the type's (`read`, `import`, `plan`, `create`, `update`, `delete`)
+ * and `sanoma.wakeup.register` in its group (Supabase's pattern).
+ */
+export const wakeupOps = {
+  ...types,
+  wakeup: { ...types.wakeup, ...register.wakeup },
+} as unknown as Connector<"sanoma", WakeupSpecs>;

package/src/wakeup.ts

@@ -7,7 +7,9 @@ import type { DeclaredResource } from "./resources.ts";
 // The `Wakeup` contract: what a resource type that wakes a stopped instance at a time declares
 // about itself, beside `Host`. Declaring one in a data file is the whole switch: the worker then
 // registers its next deadline with it before it stops, and the wakeup calls the host's
-// `GET {url}/wake?generation=N` then. The contract is here; the worker's side is `deadlines.ts`.
+// `GET {url}/wake` then: a wake is "resume if stopped", so one that arrives late, twice or for a
+// replaced registration starts a worker that finds nothing to do and stops again. The contract is
+// here; the worker's side is `deadlines.ts`.
 
 /** What a wakeup's state says of it. */
 export interface WakeupOutputs {
@@ -18,18 +20,6 @@ export interface WakeupOutputs {
 export interface WakeupRegistration {
   /** When to wake the instance, as an ISO 8601 date-time. */
   at: string;
-  /** Counts up with each registration: one with a newer generation replaces the older. */
-  generation: number;
-}
-
-/**
- * The `generation` of a `GET /wake?generation=N` request: a non-negative integer, in digits
- * alone; undefined for none or any other.
- */
-export function wakeGeneration(url: string | URL): number | undefined {
-  const given = new URL(url).searchParams.get("generation") ?? "";
-  const generation = Number(given);
-  return /^\d+$/.test(given) && Number.isSafeInteger(generation) ? generation : undefined;
 }
 
 /**
@@ -48,7 +38,7 @@ export interface WakeupSpec {
    * The id of the type's own register operation, `<vendor>.<type>.<op>`: an operation in the
    * type's own group of its connector, beside `read` and `import` (the way Supabase adds
    * `project.health` beside `project`). The runtime calls it with `WakeupRegistration`,
-   * at least once per registration; a newer `generation` replaces the older.
+   * at least once per registration; each replaces whatever the wakeup held.
    */
   register: string;
   outputs: (state: Record<string, unknown>) => WakeupOutputs;
@@ -97,7 +87,7 @@ export function checkWakeup(
 }
 
 /** A registration every register operation must take: the input `checkWakeupOps` tries. */
-const SAMPLE: WakeupRegistration = { at: new Date(0).toISOString(), generation: 1 };
+const SAMPLE: WakeupRegistration = { at: new Date(0).toISOString() };
 
 /**
  * True when `op`'s input takes `sample` and keeps each of its fields: one that strips a field
@@ -132,8 +122,7 @@ export function checkWakeupOps(types: ReadonlyMap<string, Resource>, ops: Readon
     if (notHosts.length) throw new Error(`${id}: its wakeup's host may name ${notHosts.join(", ")}, which is no host`);
     const op = ops.get(type.wakeup.register);
     if (!op) throw new Error(`${id}: its wakeup's register, ${type.wakeup.register}, is no operation of its connector`);
-    if (!keepsInput(op, { ...SAMPLE }))
-      throw new Error(`${id}: its wakeup's register, ${op.id}, must take { at, generation }`);
+    if (!keepsInput(op, { ...SAMPLE })) throw new Error(`${id}: its wakeup's register, ${op.id}, must take { at }`);
   }
 }
 

package/src/worker.ts

@@ -1,11 +1,10 @@
 import { DBOS, type ScheduledWorkflowFn } from "@dbos-inc/dbos-sdk";
-import { randomUUID } from "node:crypto";
 import { awaitApproval } from "./approvals.ts";
 import { buildCtx, decideStart, isInfrastructureError, startHoldOf } from "./call.ts";
 import { dbosStatusesOf } from "./client.ts";
 import { declaredWakeup, type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
 import { storedSecrets, watchCredentials } from "./credentials.ts";
-import { claimWakeup, DBOS_DATABASE_OPTIONS, lazyPool, prepareDatabase } from "./db.ts";
+import { DBOS_DATABASE_OPTIONS, lazyPool, prepareDatabase } from "./db.ts";
 import { deadlineRegistry, type Deadlines, idle, onOwnQueue, type SelfStop, stopWhenIdle } from "./deadlines.ts";
 import type { WorkflowDefinition } from "./define.ts";
 import { credentialsOf, unconfigured, unconfiguredSummary } from "./env.ts";
@@ -85,8 +84,8 @@ export interface WorkerOptions {
   /**
    * Given, and with a wakeup declared, the worker stops itself when idle (`stopCheckMs`); without
    * it, nobody would start another, so it never does. Called once the worker has stopped itself, with the deadline it registered with the
-   * wakeup (null for none) and that registration's generation: a supervisor starts a fresh
-   * worker on the next request or wake (`shouldWake`), since a stopped one cannot launch again.
+   * wakeup (null for none): a supervisor starts a fresh worker on the next write or wake, since a
+   * stopped one cannot launch again.
    */
   onStopped?: (stopped: SelfStop) => void;
   /**
@@ -231,13 +230,10 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
       warn(`the policies do not hold, so every call and start is refused:\n  ${resolved.policyProblems.join("\n  ")}`);
     }
     if (wakeup && options.onStopped) {
-      const owner = randomUUID();
-      await claimWakeup(await secrets.db(), owner);
       const registerId = wakeup.type.wakeup!.register;
       stopRule = stopWhenIdle({
         // The row is one more of the runtime's tables: the secrets' pool, on the same database.
         db: () => secrets.db(),
-        owner,
         wakeup: wakeup.binding ?? wakeup.id,
         // `resolveConfig` checked the operation is the config's (`checkWakeupOps`).
         register: { op: resolved.ops.get(registerId)!, fn: resolved.drivers.get(registerId) },