abysshub 0.1.1 → 0.1.2-dev.2

package/README.md

@@ -58,7 +58,7 @@ const run = await abyss.run(widget, input, { maxPrice, idempotencyKey, timeout,
 
 The press holds until the run ends. When the hold ends early (a deploy cuts it, the network goes down, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
 
-A **run** has `/v1`'s fields: `id`, `widget`, `status` (`queued`, `running`, `succeeded` or `failed`), `price`, `result`, `output_files`, `error`, `created_at`, `started_at` and `ended_at`.
+A **run** has `/v1`'s fields: `id`, `widget`, `status` (`queued`, `running`, `succeeded` or `failed`), `price`, `result`, `output_files`, `files` (`ready`, `asleep` or `waking`, see [Old big runs](#old-big-runs)), `error`, `created_at`, `started_at` and `ended_at`.
 
 ## The routes
 
@@ -69,6 +69,7 @@ Under `run()` there is one method per route. Each takes `timeout` and `signal` i
 | `abyss.runs.create(widget, input, { maxPrice?, idempotencyKey? })` | `POST /v1/widgets/{widget}/runs` with `"wait": false` | the run, `queued`, at once |
 | `abyss.runs.get(id, { wait? })` | `GET /v1/runs/{id}`, with `?wait=true` when `wait` | the run |
 | `abyss.runs.list({ limit?, startingAfter? })` | `GET /v1/runs?limit=&starting_after=` | `{ data, has_more }`, newest first |
+| `abyss.runs.wake(id)` | `POST /v1/runs/{id}/wake` | the run, `waking` when it was asleep |
 | `abyss.widgets.get(widget)` | `GET /v1/widgets/{widget}` | `{ id, name, description, url, price, free_runs, input_schema }` |
 | `abyss.uploads.create(widget, { field, filename, size? })` | `POST /v1/widgets/{widget}/uploads` | `{ id, upload: { url, fields } }` |
 | `abyss.key()` | `GET /v1/key` | `{ name, key, user, spend_cap, spent_this_month, created_at }` |
@@ -105,9 +106,27 @@ const paths = await run.save("output"); // ["output/charts/a.png", "output/outpu
 - **`await run.save(dir)`** writes every output file under `dir` at its `path`, making folders, and answers the paths it wrote.
 - **Each of `run.output_files`** has `await f.save(path)` and `await f.read()`, which answers a `Uint8Array`. An expired URL is refreshed once, by reading the run again with `GET /v1/runs/{id}`. A file of 64 MiB or more downloads as 16 parallel byte ranges of its one URL.
 
+## Old big runs
+
+A big run (its files total 50 MiB or more) that nobody has opened for six months falls asleep: its larger files sleep in deep storage, and the run reads `files: "asleep"`. Its `result` reads as before, and reading the run never wakes it. Most callers never meet one.
+
+```js
+import { FilesAsleepError } from "abysshub";
+
+try {
+  await run.save("output");
+} catch (error) {
+  if (!(error instanceof FilesAsleepError)) throw error;
+  if (error.code === "files_asleep") await run.wake(); // back within 12 hours, with an email
+}
+```
+
+- **`await run.wake()`** (or `abyss.runs.wake(id)`) calls `POST /v1/runs/{id}/wake` and answers the run, `files: "waking"`. Its files are back within 12 hours, when it reads `ready`. Waking a run that is not asleep changes nothing.
+- **`await run.save(dir)`** on a run that is `asleep` or `waking` raises `FilesAsleepError`, with `code` `files_asleep` or `files_waking`, before any download.
+
 ## Errors
 
-A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`.
+A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`. Its one subclass, `FilesAsleepError`, is what `run.save()` raises on an old big run (see [Old big runs](#old-big-runs)).
 
 | Field | |
 |---|---|
@@ -122,9 +141,9 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `run_id` | the id of the run the call started or read, once the press's `Location` or a run body named it, else `null` |
 | `run` | the run, for a failed run or a timeout, else `null` |
 
-- **Refusals:** `invalid_api_key` (401), `not_found` (404), `invalid_request`, `invalid_input`, `held_input_*`, `input_unreachable` and `idempotency_key_reused` (422), `insufficient_funds` (402), `spend_cap_reached` and `price_above_max` (400), `idempotency_key_in_use` (409), `rate_limited` (429), `server_error` (500).
+- **Refusals:** `invalid_api_key` (401), `not_found` (404), `invalid_request`, `invalid_input`, `held_input_*`, `input_unreachable` and `idempotency_key_reused` (422), `insufficient_funds` (402), `spend_cap_reached` and `price_above_max` (400), `idempotency_key_in_use` and `run_files_waking` (409), `rate_limited` (429), `server_error` (500).
 - **A failed run:** `widget_fault`, `platform_fault` or `budget_exceeded`, with the run as `run`.
-- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `cause`; and `unexpected_response`, when an answer is not what the route sends.
+- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `cause`; `unexpected_response`, when an answer is not what the route sends; and `files_asleep` and `files_waking`, raised by `run.save()` as `FilesAsleepError`.
 
 ## Retries
 

package/dist/client.d.ts

@@ -47,6 +47,8 @@ export interface Runs {
     get(id: string, options?: GetRunOptions): Promise<Run>;
     /** Answers a page of runs, newest first. */
     list(options?: ListRunsOptions): Promise<RunList<Run>>;
+    /** Wakes a run whose files are asleep, and answers it, `waking`. A run that is not asleep is answered as it is. */
+    wake(id: string, options?: CallOptions): Promise<Run>;
 }
 export interface Widgets {
     /** Reads a Widget: its price, Free Runs and `input_schema`. */

package/dist/client.js

@@ -46,6 +46,10 @@ export class Abyss {
             }),
             get: (id, options = {}) => this.#call(options, async (call) => this.#run(await this.#getRun(call, id, options.wait ?? false))),
             list: (options = {}) => this.#call(options, (call) => this.#listRuns(call, options)),
+            wake: (id, options = {}) => this.#call(options, async (call) => {
+                const reply = await this.#send(call, "POST", `${this.#runURL(id)}/wake`);
+                return this.#run(expect(reply, isRun, "The wake answered without a run."));
+            }),
         };
         this.widgets = {
             get: (widget, options = {}) => this.#call(options, (call) => this.#get(call, this.#widgetURL(widget), isWidget, "The Widget answered without an id.")),
@@ -163,7 +167,7 @@ export class Abyss {
     }
     /** Reads a run with `GET /v1/runs/{id}`, holding with `?wait=true`. A cut hold is read again. */
     async #getRun(call, id, wait) {
-        const url = new URL(`${this.baseURL}/v1/runs/${encodeURIComponent(id)}`);
+        const url = new URL(this.#runURL(id));
         if (wait)
             url.searchParams.set("wait", "true");
         const reply = await this.#hold(call, url.href, (reply) => !reply.cut);
@@ -196,7 +200,10 @@ export class Abyss {
         return reply;
     }
     #run(data) {
-        return new Run(data, () => this.#getRun(newCall(null), data.id, false));
+        return new Run(data, () => this.#getRun(newCall(null), data.id, false), (options) => this.runs.wake(data.id, options));
+    }
+    #runURL(id) {
+        return `${this.baseURL}/v1/runs/${encodeURIComponent(id)}`;
     }
     #widgetURL(widget) {
         return `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}`;

package/dist/error.d.ts

@@ -40,3 +40,11 @@ export declare class AbyssError extends Error {
     readonly run: Run | null;
     constructor(fields: AbyssErrorFields);
 }
+/**
+ * What `run.save()` raises when the run's files are asleep, with `code: "files_asleep"`:
+ * `run.wake()` brings them back within 12 hours. While they come back, `files_waking`.
+ * It is an `AbyssError`, carrying the run as `run`.
+ */
+export declare class FilesAsleepError extends AbyssError {
+    constructor(fields: AbyssErrorFields);
+}

package/dist/error.js

@@ -34,3 +34,14 @@ export class AbyssError extends Error {
         this.run = fields.run ?? null;
     }
 }
+/**
+ * What `run.save()` raises when the run's files are asleep, with `code: "files_asleep"`:
+ * `run.wake()` brings them back within 12 hours. While they come back, `files_waking`.
+ * It is an `AbyssError`, carrying the run as `run`.
+ */
+export class FilesAsleepError extends AbyssError {
+    constructor(fields) {
+        super(fields);
+        this.name = "FilesAsleepError";
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Abyss, Abyss as default, type AbyssOptions, type CallOptions, type GetRunOptions, type ListRunsOptions, type RunOptions, type Runs, type UploadRequest, type Uploads, type Widgets, } from "./client.js";
-export { AbyssError, type AbyssErrorFields } from "./error.js";
+export { AbyssError, FilesAsleepError, type AbyssErrorFields } from "./error.js";
 export { file, type FileData, type FileOptions, type InputFile } from "./files.js";
 export type { Run, RunFile } from "./run.js";
-export type { Input, Key, RunError, RunList, RunStatus, Upload, Widget } from "./types.js";
+export type { Input, Key, RunError, RunFiles, RunList, RunStatus, Upload, Widget } from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { Abyss, Abyss as default, } from "./client.js";
-export { AbyssError } from "./error.js";
+export { AbyssError, FilesAsleepError } from "./error.js";
 export { file } from "./files.js";

package/dist/run.d.ts

@@ -1,6 +1,9 @@
-import type { RunData, RunError, RunFileData, RunStatus } from "./types.js";
+import type { CallOptions } from "./client.js";
+import type { RunData, RunError, RunFileData, RunFiles, RunStatus } from "./types.js";
 /** Reads the run again with `GET /v1/runs/{id}`. */
 export type Reread = () => Promise<RunData>;
+/** Wakes the run with `POST /v1/runs/{id}/wake`. */
+export type Wake = (options?: CallOptions) => Promise<Run>;
 /** A file this many bytes or larger downloads as parallel byte ranges: 64 MiB. */
 export declare const RANGED_FROM: number;
 /** How many parallel byte ranges a large file downloads as. */
@@ -14,12 +17,22 @@ export declare class Run {
     price: number;
     result: unknown;
     output_files: RunFile[];
+    files: RunFiles;
     error: RunError | null;
     created_at: string;
     started_at: string | null;
     ended_at: string | null;
-    constructor(data: RunData, reread: Reread);
-    /** Saves every output file under `dir`, at its `path`, and answers the paths it wrote. */
+    constructor(data: RunData, reread: Reread, wake: Wake);
+    /**
+     * Wakes the run's files with `POST /v1/runs/{id}/wake` and answers the run, `waking` when
+     * it was asleep: its files are back within 12 hours. A run that is not asleep is answered
+     * as it is.
+     */
+    wake(options?: CallOptions): Promise<Run>;
+    /**
+     * Saves every output file under `dir`, at its `path`, and answers the paths it wrote.
+     * A run whose files are asleep or waking raises `FilesAsleepError` before any download.
+     */
     save(dir: string): Promise<string[]>;
 }
 /** One file a run wrote. Its `url` is signed fresh on every read of the run, and expires. */

package/dist/run.js

@@ -1,4 +1,4 @@
-import { AbyssError } from "./error.js";
+import { AbyssError, FilesAsleepError } from "./error.js";
 import { nodeFS, nodePath } from "./node.js";
 /** A file this many bytes or larger downloads as parallel byte ranges: 64 MiB. */
 export const RANGED_FROM = 64 * 1024 * 1024;
@@ -22,22 +22,26 @@ export class Run {
     price;
     result;
     output_files;
+    files;
     error;
     created_at;
     started_at;
     ended_at;
     #reread;
-    constructor(data, reread) {
+    #wake;
+    constructor(data, reread, wake) {
         this.id = data.id;
         this.widget = data.widget;
         this.status = data.status;
         this.price = data.price;
         this.result = data.result;
+        this.files = data.files;
         this.error = data.error;
         this.created_at = data.created_at;
         this.started_at = data.started_at;
         this.ended_at = data.ended_at;
         this.#reread = reread;
+        this.#wake = wake;
         this.output_files = data.output_files.map((output) => new RunFile(output, () => this.#refreshURLs()));
     }
     /** Reads the run again and gives every output file its freshly signed `url`. */
@@ -49,8 +53,29 @@ export class Run {
                 output.url = url;
         }
     }
-    /** Saves every output file under `dir`, at its `path`, and answers the paths it wrote. */
+    /**
+     * Wakes the run's files with `POST /v1/runs/{id}/wake` and answers the run, `waking` when
+     * it was asleep: its files are back within 12 hours. A run that is not asleep is answered
+     * as it is.
+     */
+    wake(options) {
+        return this.#wake(options);
+    }
+    /**
+     * Saves every output file under `dir`, at its `path`, and answers the paths it wrote.
+     * A run whose files are asleep or waking raises `FilesAsleepError` before any download.
+     */
     async save(dir) {
+        if (this.files === "asleep" || this.files === "waking") {
+            throw new FilesAsleepError({
+                code: `files_${this.files}`,
+                message: this.files === "asleep"
+                    ? `The files of run ${this.id} are asleep. Call run.wake(): they are back within 12 hours.`
+                    : `The files of run ${this.id} are waking after run.wake(): they are back within 12 hours.`,
+                run_id: this.id,
+                run: this,
+            });
+        }
         const path = await nodePath();
         const saved = [];
         for (const output of this.output_files) {

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 /** A run's place: `succeeded` and `failed` are final. */
 export type RunStatus = "queued" | "running" | "succeeded" | "failed";
+/**
+ * Whether a run's files can be read now. A big run nobody has opened for six months falls
+ * asleep: its larger files sleep until `run.wake()`, then read `waking` until they are back,
+ * within 12 hours.
+ */
+export type RunFiles = "ready" | "asleep" | "waking";
 /** Why a run failed: `widget_fault`, `platform_fault` or `budget_exceeded`. */
 export interface RunError {
     code: string;
@@ -20,6 +26,7 @@ export interface RunData {
     price: number;
     result: unknown;
     output_files: RunFileData[];
+    files: RunFiles;
     error: RunError | null;
     created_at: string;
     started_at: string | null;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, written from package.json by scripts/version.js at build. */
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.1.2-dev.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This package's version, written from package.json by scripts/version.js at build. */
-export const VERSION = "0.1.1";
+export const VERSION = "0.1.2-dev.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abysshub",
-  "version": "0.1.1",
+  "version": "0.1.2-dev.2",
   "description": "The official JavaScript library for the Abyss API.",
   "license": "MIT",
   "homepage": "https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme",