@watasu/sdk 0.1.30 → 0.1.50

package/dist/template.js

@@ -1,8 +1,45 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConnectionConfig } from './connectionConfig.js';
-import { InvalidArgumentError, NotFoundError, SandboxError, unsupported } from './errors.js';
+import { InvalidArgumentError, NotFoundError, SandboxError, TemplateError } from './errors.js';
 import { ControlClient, withQuery } from './transport.js';
+export class LogEntry {
+    timestamp;
+    level;
+    message;
+    constructor(timestamp = new Date(), level = 'info', message = '') {
+        this.timestamp = timestamp;
+        this.level = level;
+        this.message = message;
+    }
+    toString() {
+        return `[${this.timestamp.toISOString()}] ${this.level}: ${this.message}`;
+    }
+}
+export class LogEntryStart extends LogEntry {
+    constructor(timestamp = new Date(), message = 'Build started') {
+        super(timestamp, 'info', message);
+    }
+}
+export class LogEntryEnd extends LogEntry {
+    constructor(timestamp = new Date(), message = 'Build finished') {
+        super(timestamp, 'info', message);
+    }
+}
+export function defaultBuildLogger(options = {}) {
+    const order = { debug: 10, info: 20, warn: 30, error: 40 };
+    const minLevel = options.minLevel ?? 'info';
+    return (entry) => {
+        if (order[entry.level] < order[minLevel])
+            return;
+        if (entry.level === 'error')
+            console.error(entry.toString());
+        else if (entry.level === 'warn')
+            console.warn(entry.toString());
+        else
+            console.log(entry.toString());
+    };
+}
 /** Ready-check command wrapper accepted by template builders. */
 export class ReadyCmd {
     cmd;
@@ -22,8 +59,6 @@ export function waitForPort(port) {
 export function waitForURL(url, statusCode = 200) {
     return new ReadyCmd(`curl -s -o /dev/null -w "%{http_code}" ${url} | grep -q "${statusCode}"`);
 }
-/** Alias for `waitForURL`. */
-export const waitForUrl = waitForURL;
 /** Return a ready check that waits for a process name. */
 export function waitForProcess(processName) {
     return new ReadyCmd(`pgrep ${processName} > /dev/null`);
@@ -40,6 +75,8 @@ export function waitForTimeout(timeout) {
 /** Chainable template builder for Watasu package-spec template builds. */
 export class TemplateBase {
     base;
+    fromImageReference;
+    fromImageRegistry;
     packages = {};
     files = [];
     setup = [];
@@ -57,10 +94,10 @@ export class TemplateBase {
     }
     static async build(template, nameOrOptions, options = {}) {
         const { name, buildOptions } = normalizeBuildArguments(nameOrOptions, options);
-        buildOptions.onBuildLogs?.({ timestamp: new Date(), level: 'info', message: 'Build started' });
+        buildOptions.onBuildLogs?.(new LogEntryStart());
         const data = await TemplateBase.buildInBackground(template, name, buildOptions);
         await waitForBuildFinish(data, buildOptions);
-        buildOptions.onBuildLogs?.({ timestamp: new Date(), level: 'info', message: 'Build finished' });
+        buildOptions.onBuildLogs?.(new LogEntryEnd());
         return data;
     }
     static async buildInBackground(template, nameOrOptions, options = {}) {
@@ -135,42 +172,73 @@ export class TemplateBase {
     static toDockerfile(template) {
         return template.toDockerfile();
     }
+    /** Request a Debian public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromDebianImage(_variant = 'stable') {
-        this.base = 'base';
-        return this;
+        return this.fromImage(`debian:${_variant}`);
     }
+    /** Request an Ubuntu public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromUbuntuImage(_variant = 'latest') {
-        this.base = 'base';
-        return this;
+        return this.fromImage(`ubuntu:${_variant}`);
     }
+    /** Request a Python public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromPythonImage(_version = '3') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`python:${_version}`);
     }
+    /** Request a Node.js public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromNodeImage(_variant = 'lts') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`node:${_variant}`);
     }
+    /** Request a Bun public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromBunImage(_variant = 'latest') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`oven/bun:${_variant}`);
     }
+    /** Start from the Watasu platform base template. */
     fromBaseImage() {
-        this.base = 'base';
-        return this;
+        return this.fromTemplate('base');
     }
-    fromImage(_baseImage, _credentials) {
-        this.base = this.base ?? 'base';
+    /** Request a public container image base. The Watasu API fails closed until OCI image import is enabled. */
+    fromImage(baseImage, credentials) {
+        if (credentials && (!credentials.username || !credentials.password)) {
+            throw new InvalidArgumentError('Both username and password are required when providing registry credentials');
+        }
+        this.fromImageReference = baseImage;
+        this.base = undefined;
+        this.fromImageRegistry = credentials
+            ? {
+                type: 'registry',
+                username: credentials.username,
+                password: credentials.password,
+            }
+            : undefined;
         return this;
     }
-    fromAWSRegistry(_image, _credentials) {
-        unsupported('Template.fromAWSRegistry');
+    /** Request an AWS registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromAWSRegistry(image, credentials) {
+        this.fromImageReference = image;
+        this.base = undefined;
+        this.fromImageRegistry = {
+            type: 'aws',
+            aws_access_key_id: credentials.accessKeyId,
+            aws_secret_access_key: credentials.secretAccessKey,
+            aws_region: credentials.region,
+        };
+        return this;
     }
-    fromGCPRegistry(_image, _credentials) {
-        unsupported('Template.fromGCPRegistry');
+    /** Request a GCP registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromGCPRegistry(image, credentials) {
+        this.fromImageReference = image;
+        this.base = undefined;
+        this.fromImageRegistry = {
+            type: 'gcp',
+            service_account_json: credentials.serviceAccountJSON,
+        };
+        return this;
     }
+    /** Start from a ready Watasu template slug, tag, or version id. */
     fromTemplate(template) {
         this.base = template;
+        this.fromImageReference = undefined;
+        this.fromImageRegistry = undefined;
         return this;
     }
     fromDockerfile(dockerfileContentOrPath) {
@@ -286,6 +354,14 @@ export class TemplateBase {
         this.readyCmd = readyCommandText(readyCommand);
         return this;
     }
+    betaDevContainerPrebuild(devcontainerDirectory) {
+        this.requireDevContainerTemplate('betaDevContainerPrebuild');
+        return this.runCmd(`devcontainer build --workspace-folder ${devcontainerDirectory}`, { user: 'root' });
+    }
+    betaSetDevContainerStart(devcontainerDirectory) {
+        this.requireDevContainerTemplate('betaSetDevContainerStart');
+        return this.setStartCmd(`sudo devcontainer up --workspace-folder ${devcontainerDirectory} && sudo /prepare-exec.sh ${devcontainerDirectory} | sudo tee /devcontainer.sh > /dev/null && sudo chmod +x /devcontainer.sh && sudo touch /devcontainer.up`, waitForFile('/devcontainer.up'));
+    }
     setEnvs(envs) {
         Object.assign(this.env, envs);
         return this;
@@ -297,7 +373,11 @@ export class TemplateBase {
     toBuildSpec() {
         const spec = {};
         if (this.base)
-            spec.base = this.base;
+            spec.from_template = this.base;
+        if (this.fromImageReference)
+            spec.from_image = this.fromImageReference;
+        if (this.fromImageRegistry)
+            spec.from_image_registry = this.fromImageRegistry;
         if (Object.keys(this.packages).length > 0)
             spec.packages = this.packages;
         if (this.files.length > 0)
@@ -315,6 +395,11 @@ export class TemplateBase {
     addPackages(manager, packages) {
         this.packages[manager] = [...(this.packages[manager] ?? []), ...packages];
     }
+    requireDevContainerTemplate(method) {
+        if (this.base !== 'devcontainer') {
+            throw new SandboxError(`${method} can only be used with the devcontainer template`);
+        }
+    }
     addCopySource(source, dest, options, multipleSources) {
         const sourcePath = this.resolveContextPath(source);
         const stat = fs.statSync(sourcePath);
@@ -368,7 +453,7 @@ export class TemplateBase {
             : commandText;
     }
     toDockerfile() {
-        const lines = ['FROM base'];
+        const lines = [`FROM ${this.fromImageReference ?? this.base ?? 'base'}`];
         for (const packageName of this.packages.apt ?? [])
             lines.push(`RUN apt-get update && apt-get install -y ${packageName}`);
         for (const packageName of this.packages.pip ?? [])
@@ -542,7 +627,7 @@ async function waitForBuildFinish(data, options) {
         if (status === 'ready')
             return;
         if (status === 'error')
-            throw new SandboxError(buildStatus.reason?.message ?? 'Template build failed');
+            throw new TemplateError(buildStatus.reason?.message ?? 'Template build failed');
         await new Promise((resolve) => setTimeout(resolve, 200));
     }
 }
@@ -589,11 +674,12 @@ function buildStatusReason(payload) {
 }
 function logEntry(payload) {
     const timestamp = stringValue(payload.timestamp);
-    return {
-        timestamp: timestamp ? new Date(timestamp) : undefined,
-        level: stringValue(payload.level) ?? 'info',
-        message: stringValue(payload.message) ?? '',
-    };
+    return new LogEntry(timestamp ? new Date(timestamp) : new Date(), logEntryLevel(stringValue(payload.level)), stringValue(payload.message) ?? '');
+}
+function logEntryLevel(value) {
+    if (value === 'debug' || value === 'info' || value === 'warn' || value === 'error')
+        return value;
+    return 'info';
 }
 function templateTag(payload) {
     return {

package/dist/terminal.d.ts

@@ -13,9 +13,9 @@ export type TerminalOpts = {
     terminalID?: string;
     cmd?: string;
     cwd?: string;
-    rootDir?: string;
-    envVars?: Record<string, string>;
-    timeout?: number;
+    envs?: Record<string, string>;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
 };
 /** A running terminal session in a sandbox. */
 export declare class Terminal {

package/dist/terminal.js

@@ -32,7 +32,10 @@ export class Terminal {
         return this.waitPromise;
     }
     async waitOnce() {
-        await this.handle.wait().catch((error) => {
+        await this.handle.wait().then((result) => {
+            if (this.output.data.length === 0 && result.stdout)
+                this.output.addData(result.stdout);
+        }).catch((error) => {
             if (typeof error?.stdout === 'string')
                 this.output.addData(error.stdout);
             else
@@ -59,10 +62,10 @@ export class TerminalManager {
         const handle = await this.pty.create({
             cmd: opts.cmd,
             cwd: opts.cwd,
-            rootDir: opts.rootDir,
-            envVars: opts.envVars,
+            envs: opts.envs,
             size: opts.size,
-            timeout: opts.timeout,
+            timeoutMs: opts.timeoutMs,
+            requestTimeoutMs: opts.requestTimeoutMs,
             onData: async (bytes) => {
                 const data = new TextDecoder().decode(bytes);
                 output.addData(data);

package/dist/transport.d.ts

@@ -15,6 +15,7 @@ export declare class DataPlaneClient {
     readonly token: string;
     private readonly config;
     constructor(baseUrl: string, token: string, config: ConnectionConfig);
+    get headers(): Record<string, string>;
     getJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
     postJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
     deleteJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
@@ -29,6 +30,7 @@ export interface RequestOpts {
     body?: BodyInit | Uint8Array;
     headers?: Record<string, string>;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 export declare function withQuery(path: string, params: Record<string, string | number | boolean | undefined>): string;
 export {};

package/dist/transport.js

@@ -28,9 +28,10 @@ export class ControlClient {
             headers: {
                 ...this.config.authHeaders,
                 ...(opts.json ? { 'content-type': 'application/json' } : {}),
+                ...(opts.headers ?? {}),
             },
             body: opts.json ? JSON.stringify(opts.json) : undefined,
-        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, opts.signal ?? this.config.signal);
         return parseJsonResponse(response);
     }
 }
@@ -43,6 +44,9 @@ export class DataPlaneClient {
         this.token = token;
         this.config = config;
     }
+    get headers() {
+        return this.config.headers;
+    }
     getJson(path, opts = {}) {
         return this.request(path, { ...opts, method: 'GET' });
     }
@@ -68,12 +72,13 @@ export class DataPlaneClient {
         const response = await fetchWithTimeout(joinUrl(this.baseUrl, path), {
             method: opts.method,
             headers: {
+                ...this.config.headers,
                 Authorization: `Bearer ${this.token}`,
                 ...(opts.json ? { 'content-type': 'application/json' } : {}),
                 ...(opts.headers ?? {}),
             },
             body: opts.json ? JSON.stringify(opts.json) : opts.body,
-        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, opts.signal ?? this.config.signal);
         if (!response.ok) {
             throw errorFromResponse(response.status, await readJsonOrText(response));
         }
@@ -109,14 +114,26 @@ async function readJsonOrText(response) {
         return { message: text };
     }
 }
-function fetchWithTimeout(url, init, timeoutMs) {
+function fetchWithTimeout(url, init, timeoutMs, signal) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let timedOut = false;
+    const abortFromCaller = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener('abort', abortFromCaller, { once: true });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
     return fetch(url, { ...init, signal: controller.signal }).catch((error) => {
-        if (error?.name === 'AbortError')
+        if (error?.name === 'AbortError' && timedOut)
             throw new TimeoutError();
         throw error;
-    }).finally(() => clearTimeout(timeout));
+    }).finally(() => {
+        clearTimeout(timeout);
+        signal?.removeEventListener('abort', abortFromCaller);
+    });
 }
 function joinUrl(base, path) {
     const normalizedBase = base.replace(/\/+$/, '');

package/dist/volume.d.ts

@@ -1,7 +1,12 @@
 import { Blob } from 'node:buffer';
 import { ConnectionConfig, type ConnectionOpts } from './connectionConfig.js';
 import { ControlClient } from './transport.js';
-export type VolumeFileType = 'file' | 'directory' | 'symlink' | string;
+export declare enum VolumeFileType {
+    UNKNOWN = "unknown",
+    FILE = "file",
+    DIRECTORY = "directory",
+    SYMLINK = "symlink"
+}
 export type VolumeReadFormat = 'text' | 'bytes' | 'blob' | 'stream';
 export type VolumeWriteData = string | Uint8Array | ArrayBuffer | Blob;
 /** Control-plane metadata for a persistent Watasu volume. */
@@ -23,7 +28,7 @@ export interface VolumeInfo {
 export interface VolumeEntryStat {
     path: string;
     name: string;
-    type: VolumeFileType;
+    type: VolumeFileType | string;
     size?: number;
     mode?: number;
     uid?: number;
@@ -36,8 +41,8 @@ export interface VolumeEntryStat {
 export interface VolumeApiParams extends ConnectionOpts {
     team?: string;
 }
-export interface VolumeConnectionConfig extends ConnectionOpts {
-}
+export type VolumeConnectionConfig = ConnectionOpts;
+export declare const VolumeConnectionConfig: typeof ConnectionConfig;
 export interface VolumeListOpts extends ConnectionOpts {
     team?: string;
 }
@@ -58,6 +63,12 @@ export interface VolumeMetadataOpts extends ConnectionOpts {
     gid?: number;
     mode?: number | string;
 }
+export type VolumeAndToken = VolumeInfo & {
+    token: string;
+};
+export type VolumeApiOpts = ConnectionOpts;
+export type VolumeMetadataOptions = Omit<VolumeMetadataOpts, keyof ConnectionOpts>;
+export type VolumeWriteOptions = Omit<VolumeWriteFileOpts, keyof ConnectionOpts>;
 /** Persistent volume that can be mounted into sandboxes and edited while detached. */
 export declare class Volume {
     readonly volumeId: string;
@@ -83,8 +94,6 @@ export declare class Volume {
     static list(opts?: VolumeListOpts): Promise<VolumeInfo[]>;
     /** Destroy a volume by id or name. Returns false when it does not exist. */
     static destroy(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
-    /** Alias for `destroy`. */
-    static delete(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
     /** Fetch this volume's latest metadata. */
     getInfo(): Promise<VolumeInfo>;
     /** Fetch metadata for a path inside this volume. */
@@ -114,7 +123,5 @@ export declare class Volume {
     remove(path: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this volume. Returns false when it no longer exists. */
     destroy(opts?: ConnectionOpts): Promise<boolean>;
-    /** Alias for `destroy`. */
-    delete(opts?: ConnectionOpts): Promise<boolean>;
     private configOptions;
 }

package/dist/volume.js

@@ -3,6 +3,14 @@ import { ConnectionConfig } from './connectionConfig.js';
 import { NotFoundError, SandboxError } from './errors.js';
 import { base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
 import { ControlClient, withQuery } from './transport.js';
+export var VolumeFileType;
+(function (VolumeFileType) {
+    VolumeFileType["UNKNOWN"] = "unknown";
+    VolumeFileType["FILE"] = "file";
+    VolumeFileType["DIRECTORY"] = "directory";
+    VolumeFileType["SYMLINK"] = "symlink";
+})(VolumeFileType || (VolumeFileType = {}));
+export const VolumeConnectionConfig = ConnectionConfig;
 /** Persistent volume that can be mounted into sandboxes and edited while detached. */
 export class Volume {
     volumeId;
@@ -26,6 +34,7 @@ export class Volume {
         const payload = await control.post('/volumes', {
             json: compactRecord({ name, team: opts.team }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeFromPayload(payload, config, control);
     }
@@ -35,6 +44,7 @@ export class Volume {
         const control = new ControlClient(config);
         const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeFromPayload(payload, config, control);
     }
@@ -44,6 +54,7 @@ export class Volume {
         const control = new ControlClient(config);
         const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeInfo(record(payload.volume ?? payload));
     }
@@ -52,7 +63,10 @@ export class Volume {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
         const path = withQuery('/volumes', { team: opts.team });
-        const payload = await control.get(path, { requestTimeoutMs: opts.requestTimeoutMs });
+        const payload = await control.get(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         const volumes = Array.isArray(payload.volumes) ? payload.volumes : [];
         return volumes.map((item) => volumeInfo(record(item)));
     }
@@ -63,6 +77,7 @@ export class Volume {
         try {
             await control.delete(`/volumes/${encodeURIComponent(volumeId)}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             return true;
         }
@@ -72,16 +87,13 @@ export class Volume {
             throw error;
         }
     }
-    /** Alias for `destroy`. */
-    static async delete(volumeId, opts = {}) {
-        return this.destroy(volumeId, opts);
-    }
     async getInfo(path, opts = {}) {
         if (path === undefined) {
             return Volume.getInfo(this.volumeId, this.configOptions(opts));
         }
         const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeEntry(record(payload.file ?? payload));
     }
@@ -92,6 +104,7 @@ export class Volume {
             depth: opts.depth,
         }), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         const entries = Array.isArray(payload.entries) ? payload.entries : [];
         return entries.map((item) => volumeEntry(record(item)));
@@ -101,6 +114,7 @@ export class Volume {
         const payload = await this.control.post(`/volumes/${this.volumeId}/directories`, {
             json: compactRecord({ path, ...metadataPayload(opts) }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeEntry(record(payload.file ?? payload));
     }
@@ -121,12 +135,14 @@ export class Volume {
         const payload = await this.control.patch(`/volumes/${this.volumeId}/path`, {
             json: compactRecord({ path, ...metadataPayload(opts) }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeEntry(record(payload.file ?? payload));
     }
     async readFile(path, opts = {}) {
         const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/files`, { path }), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         const file = record(payload.file ?? payload);
         const content = file.content_b64 ?? file.contentBase64 ?? file.content ?? '';
@@ -154,6 +170,7 @@ export class Volume {
                 force: opts.force,
             }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return volumeEntry(record(payload.file ?? payload));
     }
@@ -161,6 +178,7 @@ export class Volume {
     async remove(path, opts = {}) {
         await this.control.delete(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return true;
     }
@@ -168,16 +186,17 @@ export class Volume {
     async destroy(opts = {}) {
         return Volume.destroy(this.volumeId, this.configOptions(opts));
     }
-    /** Alias for `destroy`. */
-    async delete(opts = {}) {
-        return this.destroy(opts);
-    }
     configOptions(opts = {}) {
         return {
             apiKey: this.config.apiKey,
             apiUrl: this.config.apiUrl,
             dataPlaneDomain: this.config.dataPlaneDomain,
             requestTimeoutMs: this.config.requestTimeoutMs,
+            headers: this.config.headers,
+            apiHeaders: this.config.apiHeaders,
+            debug: this.config.debug,
+            signal: this.config.signal,
+            proxy: this.config.proxy,
             ...opts,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.30",
+  "version": "0.1.50",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test test/*.mjs"
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test test/*.mjs"
   },
   "dependencies": {
     "ws": "^8.18.3"