palbase 0.4.0 → 0.5.1

package/types/internal/src/modules/machines.d.ts

@@ -580,62 +580,6 @@ export type DatabaseCredentials = {
     owner: DatabaseLogin;
     app: DatabaseLogin;
 };
-/**
- * A job the machine's program says it runs on a schedule. The platform calls it when it is due — POST /_palbase/jobs/<name> on the machine's own port, with {"job","run_id","scheduled_at","attempt"}, signed as a webhook is (Palbase-Signature) with the key in the machine's PALBASE_PLATFORM_SECRET — waking the machine for it; of a machine's copies one is called. A program says its jobs at GET /_palbase/jobs (asked once each version comes up); nothing from outside reaches /_palbase/ on a machine. One run of a job at a time: a job due again while its last run is not over is skipped. A 2xx answer is done, 404 is no such job in this version, anything else — or no answer within its timeout — is an attempt that failed, made again after 10 s, 20 s, … five minutes at most.
- */
-export type Job = {
-    name: string;
-    /**
-     * Five fields, as cron's: minute hour day-of-month month day-of-week, in UTC.
-     */
-    schedule: string;
-    /**
-     * How long an attempt has, in seconds.
-     */
-    timeout: number;
-    /**
-     * How many more attempts a run has after its first fails.
-     */
-    retries: number;
-    /**
-     * When it is next due.
-     */
-    next_at: string;
-    last_run?: JobRun;
-};
-/**
- * One run of a job: the same run (id, the program's run_id) through every attempt it took.
- */
-export type JobRun = {
-    id: string;
-    /**
-     * When it was due.
-     */
-    scheduled_at: string;
-    /**
-     * running: an attempt is with the machine; waiting: its last attempt failed and another is due; succeeded; failed: no attempt left; skipped: not run — its last run was not over, or the machine's version has no such job (reason).
-     */
-    state: "running" | "waiting" | "succeeded" | "failed" | "skipped";
-    attempt: number;
-    /**
-     * Why an attempt failed, or why the run was skipped.
-     */
-    reason?: string;
-    started_at: string;
-    finished_at?: string;
-};
-/**
- * A machine's jobs, as its running version said them, by name.
- */
-export type JobList = {
-    jobs: Job[];
-};
-/**
- * A job's latest runs (50 at most), newest first; runs are kept for 7 days.
- */
-export type JobRunList = {
-    runs: JobRun[];
-};
 /**
  * One line a machine wrote — a line of the NDJSON answer of GET /machines/{name}/logs.
  */
@@ -1169,6 +1113,191 @@ export type DatabaseSizeList = {
      */
     sizes: DatabaseSize[];
 };
+/**
+ * One run of a cron: the same run (id, the program's run_id) through every attempt it took.
+ */
+export type CronRun = {
+    id: string;
+    /**
+     * When it was due.
+     */
+    scheduled_at: string;
+    /**
+     * running: an attempt is with the machine; waiting: its next attempt is due (a run asked for now waits for its first); succeeded; failed: no attempt left; skipped: not run — its last run was not over, the project runs no machine now, or the machine's version has no such cron (reason).
+     */
+    state: "running" | "waiting" | "succeeded" | "failed" | "skipped";
+    attempt: number;
+    /**
+     * Why an attempt failed, or why the run was skipped.
+     */
+    reason?: string;
+    /**
+     * Asked for there and then (run now), not made by the schedule.
+     */
+    manual: boolean;
+    started_at: string;
+    finished_at?: string;
+};
+/**
+ * A cron the machine's program says it runs on a schedule (an @Cron of its app). The platform calls it when it is due — POST /_palbase/crons/<name> on the machine's own port, with {"cron","run_id","scheduled_at","attempt"}, signed as a webhook is (Palbase-Signature) with the key in the machine's PALBASE_PLATFORM_SECRET — waking the machine for it; of a machine's copies one is called. A program says its crons at GET /_palbase/crons (asked once each version comes up); nothing from outside reaches /_palbase/ on a machine. One run of a cron at a time: a cron due again while its last run is not over is skipped. A 2xx answer is done, 404 is no such cron in this version, anything else — or no answer within its timeout — is an attempt that failed, made again after 10 s, 20 s, … five minutes at most.
+ */
+export type Cron = {
+    name: string;
+    /**
+     * Five fields, as cron's: minute hour day-of-month month day-of-week, on the clocks of time_zone. Where they change, a time they skip is not run and a time they show twice is run the first time only.
+     */
+    schedule: string;
+    /**
+     * The IANA time zone whose clocks the schedule is on (UTC unless the cron names one).
+     */
+    time_zone: string;
+    /**
+     * How long an attempt has, in seconds.
+     */
+    timeout: number;
+    /**
+     * How many more attempts a run has after its first fails.
+     */
+    retries: number;
+    /**
+     * When it is next due (while paused: when it was, before it was paused).
+     */
+    next_at: string;
+    /**
+     * Not run until it is resumed, whatever version of the machine comes up meanwhile.
+     */
+    paused: boolean;
+    /**
+     * When it was paused.
+     */
+    paused_at?: string;
+    last_run?: CronRun;
+};
+/**
+ * A machine's crons, as its running version said them, by name.
+ */
+export type CronList = {
+    crons: Cron[];
+};
+/**
+ * A cron's latest runs (50 at most), newest first; runs are kept for 7 days.
+ */
+export type CronRunList = {
+    runs: CronRun[];
+};
+/**
+ * A task on a machine's queue: the same task (id) through every attempt it takes.
+ */
+export type Task = {
+    id: string;
+    /**
+     * Its task type: the @Task of the machine's app that does it.
+     */
+    task: string;
+    /**
+     * waiting: due at run_at (its first attempt, or the next after one that failed); running: an attempt is with the machine; succeeded; failed: no attempt left, or the program said it can never be done (reason); cancelled: taken off the queue before it ran.
+     */
+    state: "waiting" | "running" | "succeeded" | "failed" | "cancelled";
+    /**
+     * The attempts made — counted on, not from zero, when the task is tried again by hand.
+     */
+    attempt: number;
+    /**
+     * The attempt after which it has none left (its type's retries, more when tried again by hand).
+     */
+    retries: number;
+    /**
+     * How long an attempt has, in seconds.
+     */
+    timeout: number;
+    /**
+     * When it is due (waiting), or was last.
+     */
+    run_at: string;
+    /**
+     * What it was put under: no second task of its type is put under it until a day after it is over.
+     */
+    key?: string;
+    /**
+     * Why its last attempt failed, or why it is over without succeeding.
+     */
+    reason?: string;
+    created_at: string;
+    /**
+     * When its first attempt was made.
+     */
+    started_at?: string;
+    finished_at?: string;
+    /**
+     * What it carries (any JSON value, the bytes it was given): in a task read by its id, and in the answer to putting it — none once it succeeded or was cancelled (only a task that may be tried again keeps it).
+     */
+    payload?: unknown;
+};
+/**
+ * A page of a machine's tasks, newest first.
+ */
+export type TaskPage = {
+    tasks: Task[];
+    /**
+     * The cursor of the next page; none on the last.
+     */
+    next_cursor?: string;
+};
+/**
+ * A task to put on the machine's queue.
+ */
+export type TaskWrite = {
+    /**
+     * The task type: one the machine's running version declares.
+     */
+    task: string;
+    /**
+     * What it carries (any JSON value, 64 KiB at most, with no NUL in its strings): name what it works on, and read it where it runs.
+     */
+    payload?: unknown;
+    /**
+     * Due this many seconds from now (30 days at most). Not with run_at.
+     */
+    delay?: number;
+    /**
+     * Due at this time (30 days from now at most; a time past is now). Not with delay.
+     */
+    run_at?: string;
+    /**
+     * Put once under this key: another task of its type under the same key, while the first is held (until a day after it is over), is not put — the answer is the first.
+     */
+    key?: string;
+};
+/**
+ * A task type the machine's running version declares, with what its queue holds.
+ */
+export type TaskType = {
+    name: string;
+    /**
+     * How long an attempt has, in seconds.
+     */
+    timeout: number;
+    /**
+     * How many more attempts a task has after its first fails.
+     */
+    retries: number;
+    /**
+     * How many of its tasks are with the machine at once, whatever the number of its copies.
+     */
+    concurrency: number;
+    waiting: number;
+    running: number;
+    /**
+     * Its tasks that failed and are kept (30 days).
+     */
+    failed: number;
+};
+/**
+ * A machine's task types, by name.
+ */
+export type TaskTypeList = {
+    types: TaskType[];
+};
 /** Palbase Machines */
 export declare function client(t: Transport): {
     /**
@@ -1459,29 +1588,6 @@ export declare function client(t: Transport): {
         body: PasswordChange; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, DatabaseCredentials>>;
-    /**
-     * List a machine's jobs
-     *
-     * The jobs the machine's running version says it runs on a schedule, each with when it is next due and its latest run.
-     */
-    listJobs(input: {
-        path: {
-            name: string;
-        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
-        signal?: AbortSignal;
-    }): Promise<Reply<200, JobList>>;
-    /**
-     * List a job's runs
-     *
-     * A job's latest runs, newest first, with the attempts each took and why one failed or was skipped.
-     */
-    listJobRuns(input: {
-        path: {
-            name: string; /** The job's name. */
-            job: string;
-        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
-        signal?: AbortSignal;
-    }): Promise<Reply<200, JobRunList>>;
     /**
      * Read what a machine wrote
      *
@@ -1580,5 +1686,140 @@ export declare function client(t: Transport): {
         body: DatabaseQuery; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, DatabaseQueryResult>>;
+    /**
+     * List a machine's crons
+     *
+     * The crons the machine's running version says it runs on a schedule (its app's @Cron classes), each with when it is next due, whether it is paused, and its latest run.
+     */
+    listCrons(input: {
+        path: {
+            name: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CronList>>;
+    /**
+     * List a cron's runs
+     *
+     * A cron's latest runs, newest first.
+     */
+    listCronRuns(input: {
+        path: {
+            name: string; /** The cron's name, as the machine's program declares it: letters, digits, ., _ and -, 64 at most. */
+            cron: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CronRunList>>;
+    /**
+     * Run a cron now
+     *
+     * Runs the cron now, apart from its schedule: a run of it (manual) that waits for its first attempt, made within seconds — the machine woken for it if asleep. 409 while a run of it is not over; 429 when the project's machine time for the period is used up.
+     */
+    runCron(input: {
+        path: {
+            name: string; /** The cron's name, as the machine's program declares it: letters, digits, ., _ and -, 64 at most. */
+            cron: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, CronRun>>;
+    /**
+     * Pause a cron
+     *
+     * Pauses the cron: it is not run until it is resumed, whatever version of the machine comes up meanwhile. A run of it already begun goes on. Pausing one paused changes nothing.
+     */
+    pauseCron(input: {
+        path: {
+            name: string; /** The cron's name, as the machine's program declares it: letters, digits, ., _ and -, 64 at most. */
+            cron: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Cron>>;
+    /**
+     * Resume a cron
+     *
+     * Resumes a paused cron: it is due at its next time from now — the times it missed while paused are not made up. Resuming one not paused changes nothing.
+     */
+    resumeCron(input: {
+        path: {
+            name: string; /** The cron's name, as the machine's program declares it: letters, digits, ., _ and -, 64 at most. */
+            cron: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Cron>>;
+    /**
+     * List a machine's tasks
+     *
+     * A page of the machine's tasks, newest first: of one state and one task type, or all. A task that succeeded or was cancelled is kept a day, one that failed 30.
+     */
+    listTasks(input: {
+        path: {
+            name: string;
+        };
+        query?: {
+            state?: "waiting" | "running" | "succeeded" | "failed" | "cancelled"; /** Only tasks of this task type. */
+            task?: string; /** The most tasks a page holds (50 when not given). */
+            limit?: number; /** The next_cursor of the page before. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, TaskPage>>;
+    /**
+     * Put a task on a machine's queue
+     *
+     * Puts a task of one of the machine's task types (its app's @Task classes, as its running version declares them) on its queue, due now, after a delay or at a time — 30 days ahead at most. The platform calls the machine's program for it when it is due — POST /_palbase/tasks/<task> on the machine's own port, with {"task","id","attempt","payload","created_at"}, signed as a cron's call is — waking the machine for it; a 2xx is the task done, 422 is the program saying it can never be done (it fails, with no attempt more), anything else — or no answer within its timeout — an attempt that failed, made again after 10 s, 20 s, … an hour at most, as often as its type's retries allow. A task is delivered at least once: its id is the same through its attempts. A key puts it once: another under the same key, while the first is held (until a day after it is over), answers 200 with the first. 404 when the machine's running version has no task of that name; 413 when the payload is over 64 KiB; 429 when the project's machine time for the period is used up (quota_exceeded) or its queues hold 100,000 tasks not yet done or 256 MiB of what the tasks kept carry (queue_full). The payload is kept as the bytes it was given, and sent to the machine as they are.
+     */
+    enqueueTask(input: {
+        path: {
+            name: string;
+        };
+        body: TaskWrite; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Task> | Reply<201, Task>>;
+    /**
+     * Read a task
+     *
+     * One of the machine's tasks, with its payload.
+     */
+    getTask(input: {
+        path: {
+            name: string; /** The task's id. */
+            task: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Task>>;
+    /**
+     * Cancel a task
+     *
+     * Takes a task that is waiting off the queue, letting go of what it carries: it is not run, nor tried again (cancelled). 409 for one with the machine, or over.
+     */
+    cancelTask(input: {
+        path: {
+            name: string; /** The task's id. */
+            task: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Task>>;
+    /**
+     * Try a task again
+     *
+     * Puts a task that failed back on the queue, due now, with as many attempts again as its type gives a task — counted on from its last, so no attempt of it is numbered twice. 409 for a task that has not failed; 429 when the project's machine time for the period is used up, or its queues are full.
+     */
+    retryTask(input: {
+        path: {
+            name: string; /** The task's id. */
+            task: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Task>>;
+    /**
+     * List a machine's task types
+     *
+     * The task types the machine's running version declares (its app's @Task classes), each with what its queue holds.
+     */
+    listTaskTypes(input: {
+        path: {
+            name: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, TaskTypeList>>;
 };
 export type Client = ReturnType<typeof client>;

package/types/internal/src/modules/notify.d.ts

@@ -192,12 +192,12 @@ export type EmailTemplateSummary = {
     variables: string[];
 };
 /**
- * A template override.
+ * A template override. Its subject, and an HTML body, a text body or both: a template with neither is refused (422).
  */
 export type EmailTemplateWrite = {
-    html_body: string;
+    html_body?: string;
     subject: string;
-    text_body: string;
+    text_body?: string;
 };
 export type ErrorResponse = {
     /**