withruntime 0.11.2 → 0.14.0

package/dist/cloudflare/index.d.ts

@@ -1,7 +1,13 @@
 import { Runtime } from "../client.js";
 import type { Process as NativeProcess, Sandbox as NativeSandbox } from "../sandbox.js";
-import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+import { CompatibilityError, type Refused, type RefusedAsync, type ClientOptions } from "../compat/core.js";
+import { type CodeContext, type CreateContextOptions, type RunCodeOptions } from "./interpreter.js";
 export { CompatibilityError };
+export * from "./errors.js";
+export { CodeInterpreter } from "./interpreter.js";
+export type { CodeContext, CreateContextOptions, ExecutionError, OutputMessage, RunCodeOptions, } from "./interpreter.js";
+export { collectFile, isExecResult, isProcess, isProcessStatus, parseSSEStream, streamFile, } from "./streams.js";
+export type { FileChunk, FileMetadata, FileStreamEvent } from "./streams.js";
 export declare class SandboxSecurityError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -23,6 +29,56 @@ export interface ExecOptions {
     onComplete?: (result: ExecResult) => void;
     onError?: (error: Error) => void;
     signal?: AbortSignal;
+    /** Cloudflare's log level for the command; it changes nothing else. */
+    origin?: "user" | "internal";
+}
+export interface StreamOptions extends Omit<ExecOptions, "stream" | "onOutput" | "onComplete" | "onError"> {
+    sessionId?: string;
+    /** Accepted as Cloudflare accepts it: its SDK does not use it either. */
+    bufferSize?: number;
+}
+export interface WatchOptions {
+    recursive?: boolean;
+    include?: string[];
+    exclude?: string[];
+    sessionId?: string;
+}
+export interface CheckChangesOptions extends WatchOptions {
+    since?: string;
+}
+export type CheckChangesResult = {
+    success: true;
+    status: "unchanged" | "changed";
+    version: string;
+    timestamp: string;
+} | {
+    success: true;
+    status: "resync";
+    reason: "expired" | "restarted";
+    version: string;
+    timestamp: string;
+};
+export interface GitCheckoutResult {
+    success: boolean;
+    repoUrl: string;
+    branch: string;
+    targetDir: string;
+    timestamp: string;
+    exitCode?: number;
+}
+export type BucketProvider = "r2" | "s3" | "gcs";
+export interface MountBucketOptions {
+    endpoint?: string;
+    provider?: BucketProvider;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    readOnly?: boolean;
+    s3fsOptions?: string[];
+    prefix?: string;
+    credentialProxy?: boolean;
+    localBucket?: boolean;
 }
 export interface ExecResult {
     success: boolean;
@@ -65,6 +121,8 @@ export interface ProcessOptions {
     cwd?: string;
     encoding?: string;
     sessionId?: string;
+    processId?: string;
+    autoCleanup?: boolean;
     onOutput?: (stream: "stdout" | "stderr", data: string) => void;
     onExit?: (code: number | null) => void;
     onStart?: (process: Process) => void;
@@ -75,12 +133,39 @@ export declare function validateSandboxConfiguration(options: Pick<SandboxOption
  * through options.runtime in Workers; Node also supports RUNTIME_API_KEY/login. */
 export declare function getSandbox(namespace: unknown, id: string, options?: SandboxOptions): Sandbox;
 export declare class Sandbox {
+    #private;
     readonly runtime: Runtime;
     private readonly options;
     private pending?;
     private existing?;
     readonly id: string;
+    /** The port Cloudflare's container serves on; Runtime previews any port. */
+    readonly defaultPort = 3000;
+    /** What setEnvVars gave this handle; the sandbox keeps them for every command. */
+    envVars: Record<string, string>;
+    readonly client: Refused;
+    readonly tunnels: Refused;
+    readonly callTunnels: RefusedAsync;
+    readonly setSandboxName: RefusedAsync;
+    readonly setContainerTimeouts: RefusedAsync;
+    readonly setTransport: RefusedAsync;
+    readonly onStart: RefusedAsync;
+    readonly onStop: RefusedAsync;
+    readonly onError: Refused;
+    readonly onActivityExpired: RefusedAsync;
+    readonly fetch: RefusedAsync;
+    readonly containerFetch: RefusedAsync;
+    readonly wsConnect: RefusedAsync;
+    readonly getContainerPlacementId: RefusedAsync;
+    readonly validatePortToken: RefusedAsync;
+    readonly createBackup: RefusedAsync;
+    readonly restoreBackup: RefusedAsync;
     constructor(runtime: Runtime, id: string, options?: SandboxOptions);
+    get sleepAfter(): string | number;
+    setSleepAfter(sleepAfter: string | number): Promise<void>;
+    setKeepAlive(keepAlive: boolean): Promise<void>;
+    /** Replaces the sandbox's labels, as Cloudflare's does. */
+    setLabels(labels: Record<string, string>): Promise<void>;
     configure(options: Pick<SandboxOptions, "sleepAfter" | "keepAlive">): Promise<void>;
     /** Only a successfully initialized native handle can supply a recovery id. */
     existingNativeId(): string | undefined;
@@ -91,8 +176,13 @@ export declare class Sandbox {
     }>;
     native(): Promise<NativeSandbox>;
     private session;
+    /** A session by id: its saved settings, or a fresh session of that id, as
+     * Cloudflare starts one again after its shell ended. */
+    private sessionFor;
     exec(command: string, options?: ExecOptions): Promise<ExecResult>;
-    execStream(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    execWithSessionToken(command: string, sessionId: string, options?: ExecOptions): Promise<ExecResult>;
+    execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    execStreamWithSessionToken(command: string, sessionId: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     startProcess(command: string, options?: ProcessOptions): Promise<Process>;
     createSession(options?: SessionOptions): Promise<ExecutionSession>;
     getSession(id: string): Promise<ExecutionSession>;
@@ -103,8 +193,11 @@ export declare class Sandbox {
     }>;
     destroy(): Promise<void>;
     setEnvVars(env: Record<string, string | undefined>): Promise<void>;
+    /** Stops the sandbox; its files stay, and the next call starts it again. */
+    stop(signal?: unknown): Promise<void>;
     writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
         encoding?: string;
+        sessionId?: string;
     }): Promise<{
         success: boolean;
         path: string;
@@ -113,29 +206,38 @@ export declare class Sandbox {
     }>;
     readFile(path: string, options: {
         encoding: "none";
+        sessionId?: string;
     }): Promise<ReadFileStreamResult>;
     readFile(path: string, options?: {
         encoding?: "utf8" | "utf-8" | "base64";
+        sessionId?: string;
     }): Promise<ReadFileResult>;
+    /** The file as Cloudflare streams it: `data:` lines of a metadata event,
+     * chunks (base64 for a binary file) and a complete event; read it with
+     * streamFile() or collectFile(). */
+    readFileStream(path: string, options?: {
+        sessionId?: string;
+    }): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     mkdir(path: string, options?: {
         recursive?: boolean;
+        sessionId?: string;
     }): Promise<{
         success: boolean;
         path: string;
         timestamp: string;
     }>;
-    deleteFile(path: string): Promise<{
+    deleteFile(path: string, sessionId?: string): Promise<{
         success: boolean;
         path: string;
         timestamp: string;
     }>;
-    renameFile(from: string, to: string): Promise<{
+    renameFile(from: string, to: string, sessionId?: string): Promise<{
         success: boolean;
         path: string;
         newPath: string;
         timestamp: string;
     }>;
-    moveFile(from: string, to: string): Promise<{
+    moveFile(from: string, to: string, sessionId?: string): Promise<{
         success: boolean;
         path: string;
         newPath: string;
@@ -144,6 +246,7 @@ export declare class Sandbox {
     listFiles(path: string, options?: {
         recursive?: boolean;
         includeHidden?: boolean;
+        sessionId?: string;
     }): Promise<{
         success: boolean;
         path: string;
@@ -170,7 +273,7 @@ export declare class Sandbox {
         count: number;
         timestamp: string;
     }>;
-    exists(path: string): Promise<{
+    exists(path: string, sessionId?: string): Promise<{
         success: boolean;
         path: string;
         exists: boolean;
@@ -195,7 +298,70 @@ export declare class Sandbox {
         name: string | undefined;
     }>;
     unexposePort(port: number): Promise<void>;
+    /** Runtime's previews have their own addresses: hostname is not used to build them. */
+    getExposedPorts(_hostname: string): Promise<{
+        url: string;
+        port: number;
+        status: "active";
+    }[]>;
+    isPortExposed(port: number): Promise<boolean>;
+    /** Cloudflare's returns 0 too: a process's record outlives it on both. */
+    cleanupCompletedProcesses(_sessionId?: string): Promise<number>;
+    /** The process's output as `data:` lines of stdout, stderr and exit events. */
+    streamProcessLogs(processId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    /** Clones with git in the sandbox, as Cloudflare's container does. */
+    gitCheckout(repoUrl: string, options?: {
+        branch?: string;
+        targetDir?: string;
+        sessionId?: string;
+        depth?: number;
+        cloneTimeoutMs?: number;
+    }): Promise<GitCheckoutResult>;
+    /** Changes under a directory as `data:` lines of Cloudflare's watch events,
+     * once the watch is established, until the stream is cancelled. */
+    watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
+    /** Whether anything under a path changed since a version this returned:
+     * the version is a digest of every entry's path, size, time and mode, tied
+     * to this boot of the sandbox. */
+    checkChanges(path: string, options?: CheckChangesOptions): Promise<CheckChangesResult>;
+    /** Mounts an S3, R2 or Google Cloud Storage bucket with Runtime's mounts. A
+     * private bucket needs a Runtime secret: store its keys with
+     * runtime.secrets.set and mount with sandbox.mounts.add({ secret }). */
+    mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+    unmountBucket(mountPath: string): Promise<void>;
+    createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+    runCode(code: string, options?: RunCodeOptions): Promise<{
+        code: string;
+        logs: {
+            stdout: string[];
+            stderr: string[];
+        };
+        error: import("./interpreter.js").ExecutionError | undefined;
+        executionCount: number | undefined;
+        results: {
+            text: string | undefined;
+            html: string | undefined;
+            png: string | undefined;
+            jpeg: string | undefined;
+            svg: string | undefined;
+            latex: string | undefined;
+            markdown: string | undefined;
+            javascript: string | undefined;
+            json: unknown;
+            chart: undefined;
+            data: Record<string, unknown> | undefined;
+        }[];
+    }>;
+    runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream<any>>;
+    listCodeContexts(): Promise<CodeContext[]>;
+    deleteCodeContext(contextId: string): Promise<void>;
 }
+/** Cloudflare's Worker-side terminal proxy has no Runtime counterpart. */
+export declare function proxyTerminal(..._args: unknown[]): Promise<Response>;
+/** Runtime previews are served by Runtime, not through your Worker. */
+export declare function proxyToSandbox(..._args: unknown[]): Promise<Response | null>;
 export declare class ExecutionSession {
     private readonly sandbox;
     readonly id: string;
@@ -205,6 +371,8 @@ export declare class ExecutionSession {
     exec(command: string, options?: ExecOptions): Promise<ExecResult>;
     execStream(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+    /** A path as this session sees it: relative paths from its working directory. */
+    resolve(path: string): Promise<string>;
     private path;
     writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
         encoding?: string;
@@ -276,6 +444,7 @@ export declare class ExecutionSession {
     setEnvVars(env: Record<string, string | undefined>): Promise<void>;
 }
 export declare class Process {
+    #private;
     private readonly sandbox;
     private readonly native;
     readonly sessionId?: string | undefined;