withruntime 0.7.1 → 0.8.0

package/dist/blaxel/preview.js

@@ -0,0 +1,228 @@
+import { guard, isNotFound, NotSupportedError, responseError } from "./errors.js";
+import { PREVIEW } from "./lookup.js";
+/** Runtime's shortest and longest token, in seconds. */
+const TOKEN_MIN = 60;
+const TOKEN_MAX = 7 * 86_400;
+function checkName(name) {
+    if (!/^[A-Za-z0-9._-]{1,48}$/.test(name))
+        throw new NotSupportedError(`The preview name "${name}"`, "Use 1 to 48 letters, digits, dots, dashes or underscores.");
+}
+function modelOf(preview, name, sandboxName, status = "DEPLOYED") {
+    return {
+        metadata: {
+            name,
+            resourceName: sandboxName,
+            resourceType: "sandbox",
+            createdAt: preview.createdAt,
+        },
+        spec: {
+            port: preview.port,
+            public: preview.visibility === "public",
+            url: preview.url.replace(/\/$/, ""),
+        },
+        status,
+    };
+}
+/** A preview token, as Blaxel's. Runtime reads it from the
+ * `x-runtime-preview-token` header or `?runtime_preview_token=`. */
+export class SandboxPreviewToken {
+    #token;
+    constructor(previewToken) {
+        this.#token = previewToken;
+    }
+    get value() {
+        return this.#token.spec.token ?? "";
+    }
+    get expiresAt() {
+        return this.#token.spec.expiresAt ?? new Date();
+    }
+    get expired() {
+        const at = this.#token.spec.expiresAt;
+        return at !== undefined && Date.parse(at) <= Date.now();
+    }
+}
+/** A preview's tokens. Runtime signs a token for a duration; it keeps no
+ * list of the tokens issued. */
+export class SandboxPreviewTokens {
+    #preview;
+    #ctx;
+    constructor(preview, ctx) {
+        this.#preview = preview;
+        this.#ctx = ctx;
+    }
+    get previewName() {
+        return this.#preview.name;
+    }
+    get resourceName() {
+        return this.#ctx.sandboxName;
+    }
+    /** A token that lasts until `expiresAt` (at least a minute, at most a week). */
+    async create(expiresAt) {
+        const seconds = Math.ceil((expiresAt.getTime() - Date.now()) / 1000);
+        if (seconds > TOKEN_MAX)
+            throw new NotSupportedError("A preview token lasting more than a week", "Create one for at most seven days, and a new one when it runs out.");
+        const port = this.#preview.spec.port;
+        const got = await this.#ctx.run((runtime) => runtime.previews.get(port, Math.max(TOKEN_MIN, seconds)));
+        return new SandboxPreviewToken({
+            metadata: { name: `token-${Date.now()}`, previewName: this.previewName },
+            spec: {
+                ...(got.token ? { token: got.token } : {}),
+                ...(got.tokenExpiresAt ? { expiresAt: got.tokenExpiresAt } : {}),
+            },
+        });
+    }
+    list() {
+        return Promise.reject(new NotSupportedError("Listing a preview's tokens", "Runtime keeps no list of issued tokens: keep the ones you create, or create a new one."));
+    }
+    /** Revokes the preview's tokens. Runtime cannot revoke one token alone, so
+     * every token issued for this preview stops working. */
+    async delete(_tokenName) {
+        const port = this.#preview.spec.port;
+        await this.#ctx.run((runtime) => runtime.previews.rotate(port));
+        return { message: "Every token of this preview was revoked" };
+    }
+}
+/** A shared port, as Blaxel's SandboxPreview. */
+export class SandboxPreview {
+    #preview;
+    tokens;
+    constructor(preview, ctx) {
+        this.#preview = preview;
+        this.tokens = new SandboxPreviewTokens(this, ctx);
+    }
+    get name() {
+        return this.#preview.metadata.name;
+    }
+    get metadata() {
+        return this.#preview.metadata;
+    }
+    get spec() {
+        return this.#preview.spec;
+    }
+}
+/** `sandbox.previews`. */
+export class SandboxPreviews {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get sandboxName() {
+        return this.#ctx.sandboxName;
+    }
+    /** Names by port, from the sandbox's labels. */
+    #names() {
+        const names = new Map();
+        for (const [key, value] of Object.entries(this.#ctx.labels()))
+            if (key.startsWith(PREVIEW))
+                names.set(Number(value), key.slice(PREVIEW.length));
+        return names;
+    }
+    #portOf(name) {
+        const label = this.#ctx.labels()[`${PREVIEW}${name}`];
+        if (label !== undefined)
+            return Number(label);
+        const plain = /^preview-(\d{1,5})$/.exec(name);
+        return plain ? Number(plain[1]) : undefined;
+    }
+    /** Every shared port. One Runtime shared without a Blaxel name is named
+     * `preview-<port>`. */
+    async list() {
+        const previews = await this.#ctx.run((runtime) => runtime.previews.list());
+        const names = this.#names();
+        return previews.map((one) => new SandboxPreview(modelOf(one, names.get(one.port) ?? `preview-${one.port}`, this.sandboxName), this.#ctx));
+    }
+    /** Shares `spec.port`: public with `spec.public`, else behind a token. */
+    async create(preview, _force) {
+        const spec = preview?.spec ?? {};
+        const name = preview?.metadata?.name;
+        const refusals = [
+            [
+                "prefixUrl",
+                "Runtime's preview address is fixed: https://<port>-<sandbox>.runtimehost.com.",
+            ],
+            [
+                "customDomain",
+                "Point your domain at the preview with runtime.domains, or keep the preview's own address.",
+            ],
+            [
+                "requestHeaders",
+                "Set the headers in your server, or in the client that calls the preview.",
+            ],
+            ["responseHeaders", "Set the headers (CORS and the rest) in your server's responses."],
+            [
+                "ttl",
+                "A Runtime preview lasts until deleted: call sandbox.previews.delete(name) when done.",
+            ],
+            [
+                "expires",
+                "A Runtime preview lasts until deleted: call sandbox.previews.delete(name) when done.",
+            ],
+        ];
+        for (const [field, alternative] of refusals)
+            if (spec[field] !== undefined &&
+                !(typeof spec[field] === "object" && !Object.keys(spec[field]).length))
+                throw new NotSupportedError(`A preview's ${field}`, alternative);
+        const port = spec.port;
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            throw responseError(400, "spec.port is required: the port your server listens on");
+        if (name !== undefined)
+            checkName(name);
+        const [made] = await Promise.all([
+            this.#ctx.run((runtime) => runtime.previews.create(port, { visibility: spec.public ? "public" : "private" })),
+            name !== undefined && this.#portOf(name) !== port
+                ? this.#ctx.setLabels({ [`${PREVIEW}${name}`]: String(port) })
+                : undefined,
+        ]);
+        return new SandboxPreview(modelOf(made, name ?? `preview-${port}`, this.sandboxName), this.#ctx);
+    }
+    /** The named preview, or a new one when there is none. */
+    async createIfNotExists(preview, force) {
+        try {
+            return await this.get(preview.metadata.name);
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            return this.create(preview, force);
+        }
+    }
+    async get(previewName) {
+        const port = this.#portOf(previewName);
+        if (port === undefined)
+            throw responseError(404, `preview ${previewName} not found`);
+        const found = await this.#ctx.run((runtime) => runtime.previews.get(port));
+        return new SandboxPreview(modelOf(found, previewName, this.sandboxName), this.#ctx);
+    }
+    /** Stops sharing the port; open connections close within seconds. */
+    async delete(previewName) {
+        const port = this.#portOf(previewName);
+        if (port === undefined)
+            throw responseError(404, `preview ${previewName} not found`);
+        await Promise.all([
+            this.#ctx.run((runtime) => runtime.previews.delete(port)),
+            `${PREVIEW}${previewName}` in this.#ctx.labels()
+                ? this.#ctx.setLabels({ [`${PREVIEW}${previewName}`]: undefined })
+                : undefined,
+        ]);
+        return {
+            metadata: { name: previewName, resourceName: this.sandboxName, resourceType: "sandbox" },
+            spec: { port },
+            status: "DELETING",
+        };
+    }
+}
+/** A private preview of `port` with a token that lasts a while, for
+ * `sandbox.fetch`: made once, then reused until its token nears its end. */
+export async function portAccess(runtime, port) {
+    let preview;
+    try {
+        preview = await guard(() => runtime.previews.get(port, 3600));
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+        preview = await guard(() => runtime.previews.create(port, { ttlSeconds: 3600 }));
+    }
+    const until = preview.tokenExpiresAt ? Date.parse(preview.tokenExpiresAt) : Infinity;
+    return { url: preview.url.replace(/\/$/, ""), token: preview.token, until };
+}

package/dist/blaxel/process.d.ts

@@ -0,0 +1,126 @@
+import type { RuntimeSandbox } from "./client.js";
+export type ProcessRequest = {
+    command: string;
+    env?: {
+        [key: string]: string;
+    };
+    /** Keeps the sandbox awake while the process runs (see BLAXEL.md). */
+    keepAlive?: boolean;
+    maxRestarts?: number;
+    name?: string;
+    restartOnFailure?: boolean;
+    /** Opens a pipe for writeStdin / closeStdin. */
+    stdin?: boolean;
+    /** Seconds. Bounds the wait of waitForCompletion and waitForPorts; with
+     * keepAlive, the process is killed after it (default 600, 0 never). */
+    timeout?: number;
+    waitForCompletion?: boolean;
+    waitForPorts?: Array<number>;
+    workingDir?: string;
+};
+export type ProcessResponse = {
+    command: string;
+    completedAt: string;
+    exitCode: number;
+    keepAlive?: boolean;
+    logs: string;
+    maxRestarts?: number;
+    name: string;
+    /** Runtime's process id. */
+    pid: string;
+    restartCount?: number;
+    restartOnFailure?: boolean;
+    startedAt: string;
+    status: "failed" | "killed" | "stopped" | "running" | "completed";
+    stderr: string;
+    stdin?: boolean;
+    stdout: string;
+    workingDir: string;
+};
+export type PostProcessResponse = ProcessResponse;
+export type GetProcessResponse = ProcessResponse[];
+export type GetProcessByIdentifierResponse = ProcessResponse;
+export type DeleteProcessByIdentifierResponse = {
+    message: string;
+};
+export type DeleteProcessByIdentifierKillResponse = {
+    message: string;
+};
+export type ProcessLogs = {
+    logs: string;
+    stderr: string;
+    stdout: string;
+};
+export type ProcessRequestWithLog = ProcessRequest & {
+    onLog?: (log: string) => void;
+    onStdout?: (stdout: string) => void;
+    onStderr?: (stderr: string) => void;
+};
+export type ProcessResponseWithLog = ProcessResponse & {
+    close: () => void;
+};
+/** What the process part needs from its sandbox. */
+export interface ProcessContext {
+    readonly id: string;
+    /** The running sandbox, woken if it was paused; throws once deleted. */
+    live(): Promise<RuntimeSandbox>;
+    /** Wakes the sandbox after a call found it paused. */
+    wake(): Promise<void>;
+    /** Keeps the sandbox from pausing for `seconds` (0: until its lease ends). */
+    keepAwake(seconds: number): Promise<void>;
+    /** A keepAlive process was seen to end: give the sandbox its idle pause
+     * back once none runs. Never throws. */
+    keepAliveEnded(): Promise<void>;
+}
+/** A command that waits until every port listens on an address other than
+ * loopback, up to `seconds`, reading whichever of the kernel's socket tables
+ * exist (a guest without IPv6 has no tcp6). Exits 0 when they all listen. */
+export declare function portWaitScript(ports: number[], seconds: number, tables?: string[]): string;
+/** Test hook: forget every process this module has seen, as a fresh client
+ * would. */
+export declare function resetProcesses(): void;
+/** `sandbox.process`: run, follow and stop processes, by pid or by name. */
+export declare class SandboxProcess {
+    #private;
+    constructor(ctx: ProcessContext);
+    /** Starts a command. Without waitForCompletion it answers at once, the
+     * process running; with it, once the process ends, with its output. */
+    exec(request: ProcessRequest | ProcessRequestWithLog): Promise<PostProcessResponse | ProcessResponseWithLog>;
+    /** The process, with the output it has written so far. */
+    get(identifier: string, _options?: {
+        signal?: AbortSignal;
+        retry?: boolean;
+    }): Promise<GetProcessByIdentifierResponse>;
+    /** Waits for the process to end (at most `maxWait` ms, -1 for no limit) and
+     * answers it with its output. The process is never stopped by the wait. */
+    wait(identifier: string, { maxWait, interval, signal, }?: {
+        maxWait?: number;
+        interval?: number;
+        signal?: AbortSignal;
+    }): Promise<GetProcessByIdentifierResponse>;
+    /** Every process started through this adapter, running or ended. Their
+     * output is left empty: read one with get() or logs(). */
+    list(): Promise<GetProcessResponse>;
+    /** SIGTERM. */
+    stop(identifier: string): Promise<DeleteProcessByIdentifierResponse>;
+    /** SIGKILL. */
+    kill(identifier: string): Promise<DeleteProcessByIdentifierKillResponse>;
+    /** Bytes to the standard input of a process started with `stdin: true`,
+     * sent as they are. */
+    writeStdin(identifier: string, data: string | Uint8Array): Promise<void>;
+    /** Closes the process's standard input (EOF). */
+    closeStdin(identifier: string): Promise<void>;
+    /** The output so far: both streams in the order written ("all"), or one. */
+    logs(identifier: string, type?: "stdout" | "stderr" | "all"): Promise<string>;
+    /** Follows the output from the start until the process ends, a line at a
+     * time, as Blaxel's streamLogs. `close()` stops following. */
+    streamLogs(identifier: string, options?: {
+        onLog?: (log: string) => void;
+        onStdout?: (stdout: string) => void;
+        onStderr?: (stderr: string) => void;
+        onError?: (error: Error) => void;
+    }): {
+        close: () => void;
+        wait: () => Promise<void>;
+    };
+}