withruntime 0.11.2 → 0.14.0

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type ClientExtensions } from "./products/index.js";
+import { type RenamedProducts } from "./renamed-products.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
 import { Machines } from "./machine.js";
 import { Sandbox } from "./sandbox.js";
@@ -34,14 +35,11 @@ export type RuntimeOptions = {
 };
 /** One client for every Runtime Cloud product. Create it once and reuse it:
  * it keeps its connections open. */
-export interface Runtime extends ClientExtensions {
+export interface Runtime extends ClientExtensions, RenamedProducts {
 }
 export declare class Runtime {
     readonly transport: Transport;
-    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
-    readonly sandbox: Sandboxes;
     readonly sandboxes: Sandboxes;
-    readonly snapshot: Snapshots;
     readonly snapshots: Snapshots;
     readonly feedback: FeedbackApi;
     readonly support: SupportApi;

package/dist/client.js

@@ -1,9 +1,12 @@
-import { clientFactories, clientProductAliases } from "./products/index.js";
+import { clientFactories } from "./products/index.js";
+import { installRenamedProducts } from "./renamed-products.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
 import { Machines } from "./machine.js";
 import { SANDBOXES, Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
-import { DEFAULT_BASE_URL, Transport, missingKey } from "./transport.js";
+import { DEFAULT_BASE_URL, Transport, missingKey, sayRenamed, } from "./transport.js";
+import { RuntimeError } from "./errors.js";
+import { RENAMED_FIELDS, fieldUse } from "./product-renames.js";
 /** The key `runtime login` saved for this machine and this API origin, found
  * on first use. A constructor override must never receive another API's key. */
 const savedKey = async (apiOrigin) => {
@@ -18,10 +21,7 @@ const env = (name) => typeof process === "undefined"
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Runtime {
     transport;
-    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
-    sandbox;
     sandboxes;
-    snapshot;
     snapshots;
     feedback;
     support;
@@ -48,17 +48,14 @@ export class Runtime {
                 : {}),
         });
         this.sandboxes = new Sandboxes(this.transport);
-        this.sandbox = this.sandboxes;
         this.snapshots = new Snapshots(this.transport);
-        this.snapshot = this.snapshots;
         this.feedback = new FeedbackApi(this.transport);
         this.support = new SupportApi(this.transport);
         this.account = new AccountApi(this.transport);
         this.usageExport = makeUsageExport(this.transport);
         for (const [name, make] of clientFactories())
             Object.defineProperty(this, name, { value: make(this.transport), enumerable: true });
-        for (const [alias, name] of Object.entries(clientProductAliases))
-            Object.defineProperty(this, alias, { value: this[name], enumerable: true });
+        installRenamedProducts(this);
     }
     /** Who this key is: organization, agent and credential. */
     me(options = {}) {
@@ -70,12 +67,31 @@ export class Runtime {
     }
     /** Balance, holds, free time and per-resource charges, in integer microdollars. */
     /** Credit, holds, free time and per-resource charges. */
-    usage(options = {}) {
-        return this.transport.json({
+    async usage(options = {}) {
+        const value = await this.transport.json({
             method: "GET",
             path: "/v1/usage",
             ...options,
         });
+        const fields = value;
+        for (const field of RENAMED_FIELDS) {
+            // An older server only sends the old name. Preserve its value before
+            // replacing that property with the warning getter.
+            if (!(field.now in fields) && field.name in fields)
+                fields[field.now] = fields[field.name];
+            Object.defineProperty(value, field.name, {
+                configurable: true,
+                enumerable: false,
+                get() {
+                    const use = fieldUse(field.name);
+                    if (use.kind === "retired")
+                        throw new RuntimeError({ ...use.error });
+                    sayRenamed(`299 runtime "${use.warning.replaceAll('"', "'")}"`);
+                    return fields[field.now];
+                },
+            });
+        }
+        return value;
     }
     /** This account's authenticated API answers, in hourly windows. Counts are
      * exact decimal strings, and an empty window has a null error percentage.

package/dist/cloudflare/errors.d.ts

@@ -0,0 +1,143 @@
+/** Cloudflare's exported error classes, with its fields, so a caller's
+ * `instanceof` and `error.code` keep working. The adapter throws them where
+ * Cloudflare would: a process that never becomes ready, a bucket that will
+ * not mount or unmount. */
+export type ErrorResponse<TContext = Record<string, unknown>> = {
+    code: string;
+    message: string;
+    operation?: string;
+    context: TContext;
+    httpStatus: number;
+    timestamp: string;
+    suggestion?: string;
+    documentation?: string;
+};
+declare class SandboxError<TContext = Record<string, unknown>> extends Error {
+    readonly errorResponse: ErrorResponse<TContext>;
+    constructor(errorResponse: ErrorResponse<TContext>, options?: {
+        cause?: unknown;
+    });
+    get code(): string;
+    get context(): TContext;
+    get httpStatus(): number;
+    get operation(): string | undefined;
+    get suggestion(): string | undefined;
+    get timestamp(): string;
+    get documentation(): string | undefined;
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        context: TContext;
+        httpStatus: number;
+        operation: string | undefined;
+        suggestion: string | undefined;
+        timestamp: string;
+        documentation: string | undefined;
+        stack: string | undefined;
+    };
+}
+export { SandboxError };
+export declare class SessionTerminatedError extends SandboxError<{
+    sessionId: string;
+    exitCode: number | null;
+}> {
+    get sessionId(): string;
+    get exitCode(): number | null;
+}
+type ReadyContext = {
+    processId: string;
+    command: string;
+    condition: string;
+};
+export declare class ProcessReadyTimeoutError extends SandboxError<ReadyContext & {
+    timeout: number;
+}> {
+    get processId(): string;
+    get command(): string;
+    get condition(): string;
+    get timeout(): number;
+}
+export declare class ProcessExitedBeforeReadyError extends SandboxError<ReadyContext & {
+    exitCode: number;
+}> {
+    get processId(): string;
+    get command(): string;
+    get condition(): string;
+    get exitCode(): number;
+}
+export declare class BackupNotFoundError extends SandboxError<{
+    backupId: string;
+}> {
+    get backupId(): string;
+}
+export declare class BackupExpiredError extends SandboxError<{
+    backupId: string;
+    expiredAt?: string;
+}> {
+    get backupId(): string;
+    get expiredAt(): string | undefined;
+}
+export declare class InvalidBackupConfigError extends SandboxError<{
+    reason: string;
+}> {
+    get reason(): string;
+}
+export declare class BackupCreateError extends SandboxError<{
+    dir: string;
+    backupId?: string;
+    stderr?: string;
+    exitCode?: number;
+}> {
+    get dir(): string;
+    get backupId(): string | undefined;
+}
+export declare class BackupRestoreError extends SandboxError<{
+    dir: string;
+    backupId: string;
+    stderr?: string;
+    exitCode?: number;
+}> {
+    get dir(): string;
+    get backupId(): string;
+}
+export declare class ContainerUnavailableError extends SandboxError<{
+    reason: string;
+    retryable: true;
+    retryAfterMs?: number;
+    originalMessage?: string;
+}> {
+    get reason(): string;
+    get retryAfterMs(): number | undefined;
+}
+export declare class OperationInterruptedError extends SandboxError<{
+    reason: string;
+    operation: string;
+    phase: string;
+    admitted: boolean | "unknown";
+    retryable: boolean;
+}> {
+    get reason(): string;
+}
+export declare class BucketMountError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export declare class S3FSMountError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class BucketUnmountError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class MissingCredentialsError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class InvalidMountConfigError extends BucketMountError {
+    constructor(message: string);
+}
+/** An ErrorResponse as the container would send it. */
+export declare function response<TContext>(code: string, message: string, context: TContext, extra?: {
+    httpStatus?: number;
+    operation?: string;
+    suggestion?: string;
+}): ErrorResponse<TContext>;

package/dist/cloudflare/errors.js

@@ -0,0 +1,167 @@
+class SandboxError extends Error {
+    errorResponse;
+    constructor(errorResponse, options) {
+        super(errorResponse.message, options);
+        this.name = new.target.name;
+        this.errorResponse = errorResponse;
+    }
+    get code() {
+        return this.errorResponse.code;
+    }
+    get context() {
+        return this.errorResponse.context;
+    }
+    get httpStatus() {
+        return this.errorResponse.httpStatus;
+    }
+    get operation() {
+        return this.errorResponse.operation;
+    }
+    get suggestion() {
+        return this.errorResponse.suggestion;
+    }
+    get timestamp() {
+        return this.errorResponse.timestamp;
+    }
+    get documentation() {
+        return this.errorResponse.documentation;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            httpStatus: this.httpStatus,
+            operation: this.operation,
+            suggestion: this.suggestion,
+            timestamp: this.timestamp,
+            documentation: this.documentation,
+            stack: this.stack,
+        };
+    }
+}
+export { SandboxError };
+export class SessionTerminatedError extends SandboxError {
+    get sessionId() {
+        return this.context.sessionId;
+    }
+    get exitCode() {
+        return this.context.exitCode;
+    }
+}
+export class ProcessReadyTimeoutError extends SandboxError {
+    get processId() {
+        return this.context.processId;
+    }
+    get command() {
+        return this.context.command;
+    }
+    get condition() {
+        return this.context.condition;
+    }
+    get timeout() {
+        return this.context.timeout;
+    }
+}
+export class ProcessExitedBeforeReadyError extends SandboxError {
+    get processId() {
+        return this.context.processId;
+    }
+    get command() {
+        return this.context.command;
+    }
+    get condition() {
+        return this.context.condition;
+    }
+    get exitCode() {
+        return this.context.exitCode;
+    }
+}
+export class BackupNotFoundError extends SandboxError {
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class BackupExpiredError extends SandboxError {
+    get backupId() {
+        return this.context.backupId;
+    }
+    get expiredAt() {
+        return this.context.expiredAt;
+    }
+}
+export class InvalidBackupConfigError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+}
+export class BackupCreateError extends SandboxError {
+    get dir() {
+        return this.context.dir;
+    }
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class BackupRestoreError extends SandboxError {
+    get dir() {
+        return this.context.dir;
+    }
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class ContainerUnavailableError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+    get retryAfterMs() {
+        return this.context.retryAfterMs;
+    }
+}
+export class OperationInterruptedError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+}
+export class BucketMountError extends Error {
+    code;
+    constructor(message, code = "BUCKET_MOUNT_ERROR") {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+export class S3FSMountError extends BucketMountError {
+    constructor(message) {
+        super(message, "S3FS_MOUNT_ERROR");
+    }
+}
+export class BucketUnmountError extends BucketMountError {
+    constructor(message) {
+        super(message, "BUCKET_UNMOUNT_ERROR");
+    }
+}
+export class MissingCredentialsError extends BucketMountError {
+    constructor(message) {
+        super(message, "MISSING_CREDENTIALS");
+    }
+}
+export class InvalidMountConfigError extends BucketMountError {
+    constructor(message) {
+        super(message, "INVALID_MOUNT_CONFIG");
+    }
+}
+/** An ErrorResponse as the container would send it. */
+export function response(code, message, context, extra = {}) {
+    return {
+        code,
+        message,
+        context,
+        httpStatus: extra.httpStatus ?? 500,
+        timestamp: new Date().toISOString(),
+        ...(extra.operation ? { operation: extra.operation } : {}),
+        ...(extra.suggestion ? { suggestion: extra.suggestion } : {}),
+    };
+}