@decocms/sandbox-controller 0.5.0 → 0.6.0

package/README.md

@@ -38,6 +38,9 @@ which are private, and bundles it into one module with declarations.
   `tenantPoolRepoSchema`), `normalizeRepoUrl`, and
   `renderTenantPoolWarmPools`, which builds a pool's `SandboxWarmPool`
   objects for the host to apply.
+- Export `FreestyleSandboxProvider` (sandboxes as Freestyle VMs) and
+  `SandboxProviderRouter`, which serves Kubernetes and Freestyle behind one
+  provider; see [`packages/sandbox`](../sandbox/README.md).
 - Export the wire contract in `sandbox-api`: tool names and schemas, and the
   watch route.
 - Export host helpers: `sandboxTools` (framework-free tool definitions),

package/dist/chunk-QGM4M3NI.js

@@ -0,0 +1,37 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __require,
+  __commonJS,
+  __toESM
+};

package/dist/index.d.ts

@@ -58,6 +58,8 @@ interface Sandbox {
      * expensive (a needless cold start, or minutes polling a dead port).
      */
     warmPoolAdopted: boolean;
+    /** Where the sandbox runs. */
+    provider: SandboxProviderKind;
 }
 /** When omitted, no dev server is started; the default tool image is used. */
 interface Workload {
@@ -142,7 +144,15 @@ interface EnsureRepo {
      */
     credentialExpiresAt?: number;
 }
+/** Where a sandbox runs. See `SandboxProviderRouter`. */
+type SandboxProviderKind = "kubernetes" | "freestyle";
 interface EnsureOptions {
+    /**
+     * Where a NEW sandbox should run, when that provider is configured and can
+     * serve the request. An existing sandbox stays where it is. Consumed by
+     * `SandboxProviderRouter`; the providers themselves ignore it.
+     */
+    provider?: SandboxProviderKind;
     /**
      * Defaults to `interactive` when absent. AgentSandboxProvider uses this to
      * decide the SandboxTemplate (memory ceiling) and the warm pool, so it has
@@ -455,7 +465,6 @@ declare const sandboxIdSchema: z.ZodObject<{
     userId: z.ZodString;
     projectRef: z.ZodString;
 }, z.core.$strip>;
-/** `image` is left out: the host's template pins it. */
 declare const ensureOptionsSchema: z.ZodType<Omit<EnsureOptions, "image">>;
 declare const daemonSchema: z.ZodObject<{
     url: z.ZodURL;
@@ -477,6 +486,10 @@ declare const ensureOutputSchema: z.ZodObject<{
     workdir: z.ZodString;
     previewUrl: z.ZodNullable<z.ZodString>;
     warmPoolAdopted: z.ZodBoolean;
+    provider: z.ZodDefault<z.ZodEnum<{
+        kubernetes: "kubernetes";
+        freestyle: "freestyle";
+    }>>;
     daemon: z.ZodObject<{
         url: z.ZodURL;
         token: z.ZodString;
@@ -497,6 +510,10 @@ declare const statusOutputSchema: z.ZodObject<{
         token: z.ZodString;
     }, z.core.$strip>>;
     lastTermination: z.ZodNullable<z.ZodType<PodTermination, unknown, z.core.$ZodTypeInternals<PodTermination, unknown>>>;
+    provider: z.ZodDefault<z.ZodEnum<{
+        kubernetes: "kubernetes";
+        freestyle: "freestyle";
+    }>>;
 }, z.core.$strip>;
 /** `graceMs` releases the sandbox after it; without it, the idle TTL is renewed. */
 declare const lifetimeInputSchema: z.ZodObject<{
@@ -522,6 +539,10 @@ declare const toolErrorSchema: z.ZodObject<{
     }>;
     error: z.ZodString;
     status: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodOptional<z.ZodEnum<{
+        kubernetes: "kubernetes";
+        freestyle: "freestyle";
+    }>>;
 }, z.core.$strip>;
 type ToolError = z.infer<typeof toolErrorSchema>;
 declare const claimPhaseSchema: z.ZodType<ClaimPhase>;
@@ -1226,6 +1247,9 @@ declare class AgentSandboxProvider {
     close(): void;
 }
 
+/** What Studio calls, served in-process or by `RemoteSandboxProvider`. */
+type SandboxProvider = Pick<AgentSandboxProvider, "ensure" | "delete" | "lastTermination" | "alive" | "watchClaimLifecycle" | "hasSchedulableCapacity" | "getPreviewUrl" | "proxyDaemonRequest" | "adoptLiveClaim" | "resolvePreviewUpstreamUrl" | "proxyPreviewRequest" | "markTenantPoolsDirty" | "releaseAfter" | "renewTtl" | "close">;
+
 interface PostgresRunnerStateStoreOptions {
     url: string;
     /** Keeps one host's rows apart from another's sharing the database, e.g. one per Studio env. Default `""`. */
@@ -1286,6 +1310,153 @@ interface TenantPoolReader {
 /** A cached pool list for `AgentSandboxProvider`'s `tenantPools`; a failed load keeps the last one. */
 declare function tenantPoolReader(store: Pick<TenantPoolStore, "list">, cluster: string, { refreshMs }?: TenantPoolReaderOptions): TenantPoolReader;
 
+interface DaemonAddress {
+    url: string;
+    token: string;
+}
+
+/**
+ * `SandboxProvider` on Freestyle VMs (https://freestyle.sh). Each sandbox is
+ * one VM running the same `studio-sandbox-go` image a pod runs, under Docker,
+ * with the daemon's port published at `https://<handle>.<domainSuffix>`.
+ *
+ * The VM is the whole state: its slug is the handle and its metadata holds the
+ * daemon bearer, so any Studio replica can find a sandbox without a database.
+ * An idle VM is paused, not deleted, and traffic to its domain resumes it.
+ */
+
+interface FreestyleSandboxProviderOptions {
+    apiKey: string;
+    /** The sandbox image. Default: the release built from this package's version. */
+    image?: string;
+    /** Pause a VM after this long without network activity. Default 15 min. */
+    idleTimeoutSeconds?: number;
+    /** Where daemon ports are published. Default `style.dev`, free on every account. */
+    domainSuffix?: string;
+    /** Records daemon request latency; see `daemonProxyTimer`. */
+    meter?: Meter;
+}
+declare class FreestyleSandboxProvider implements SandboxProvider {
+    private readonly freestyle;
+    private readonly image;
+    private readonly idleTimeoutSeconds;
+    private readonly domainSuffix;
+    private readonly timeDaemonRequest;
+    private readonly inflight;
+    private readonly snapshotInflight;
+    private readonly lookups;
+    private readonly releaseTimers;
+    constructor(opts: FreestyleSandboxProviderOptions);
+    /** Whether this handle is a Freestyle sandbox. Cached; see `MISS_TTL_MS`. */
+    owns(handle: string): Promise<boolean>;
+    private daemonUrl;
+    private find;
+    private remember;
+    /**
+     * A snapshot of a VM with the image already pulled, so a sandbox boots in
+     * seconds instead of pulling ~2GB. One per image; built on first use.
+     */
+    private baseSnapshot;
+    private snapshotExists;
+    private run;
+    ensure(id: SandboxId, opts?: EnsureOptions): Promise<Sandbox>;
+    private resume;
+    private create;
+    private configPayload;
+    private waitForDaemon;
+    delete(handle: string): Promise<void>;
+    lastTermination(_handle: string): Promise<PodTermination | null>;
+    /** A paused VM is alive: the next request resumes it. */
+    alive(handle: string): Promise<boolean>;
+    /** `ensure` only returns once the daemon answers, so this only has to see that. */
+    watchClaimLifecycle(handle: string, signal?: AbortSignal): AsyncGenerator<ClaimPhase, void, unknown>;
+    hasSchedulableCapacity(): Promise<boolean>;
+    getPreviewUrl(handle: string): Promise<string | null>;
+    proxyDaemonRequest(handle: string, path: string, init: ProxyRequestInit): Promise<Response>;
+    /** The daemon's public address and bearer, for a host serving `sandbox-api`. */
+    daemonEndpoint(handle: string): Promise<DaemonAddress | null>;
+    adoptLiveClaim(_id: SandboxId, handle: string): Promise<boolean>;
+    resolvePreviewUpstreamUrl(handle: string): Promise<string | null>;
+    proxyPreviewRequest(handle: string, request: Request): Promise<Response>;
+    markTenantPoolsDirty(_repoUrl: string, _ref: string): Promise<string[]>;
+    /**
+     * Pause after `graceMs`. Pausing keeps memory and disk, so this costs the
+     * sandbox nothing but a resume.
+     *
+     * ponytail: in-process timer, lost on restart; the idle timeout pauses the
+     * VM anyway, only later.
+     */
+    releaseAfter(handle: string, graceMs: number): Promise<void>;
+    /** The VM's idle timeout already counts every request as activity. */
+    renewTtl(handle: string): Promise<void>;
+    private cancelRelease;
+    close(): void;
+}
+
+/**
+ * One `SandboxProvider` over the configured providers. A new sandbox goes
+ * where `EnsureOptions.provider` asks, when that provider is configured and
+ * can run it; else `freestyleShare` of new sandboxes go to Freestyle, and the
+ * rest to Kubernetes while it has room. An existing one stays where it is.
+ * Handle-only calls go to the provider that owns the handle, because a handle
+ * carries no provider tag.
+ */
+
+/** What a host serving `sandbox-api` needs beyond `SandboxProvider`. */
+type HostMethods = Pick<AgentSandboxProvider, "daemonEndpoint" | "listSandboxes" | "listTenantPools">;
+/** A provider that can answer whether a handle is its own without a claim. */
+type OwningSandboxProvider = SandboxProvider & Partial<Pick<HostMethods, "daemonEndpoint">> & {
+    owns(handle: string): Promise<boolean>;
+};
+interface SandboxProviders {
+    kubernetes?: SandboxProvider & Partial<HostMethods>;
+    freestyle?: OwningSandboxProvider;
+}
+interface SandboxProviderRouterOptions {
+    /**
+     * Share of new sandboxes, 0 to 1, placed on Freestyle when the caller names
+     * no provider. Decided by the handle, so a retry lands where the first try
+     * did. Default 0.
+     */
+    freestyleShare?: number;
+}
+declare class SandboxProviderRouter implements SandboxProvider {
+    readonly providers: SandboxProviders;
+    private readonly picked;
+    private readonly freestyleShare;
+    constructor(providers: SandboxProviders, opts?: SandboxProviderRouterOptions);
+    private get;
+    private remember;
+    /** Who serves an existing handle. Kubernetes is the fallback: it has no cheap ownership check. */
+    providerOf(handle: string): Promise<SandboxProviderKind>;
+    private owner;
+    /** Where `ensure` puts this sandbox. */
+    place(handle: string, opts: EnsureOptions): Promise<SandboxProviderKind>;
+    ensure(id: SandboxId, opts?: EnsureOptions): Promise<Sandbox>;
+    delete(handle: string): Promise<void>;
+    lastTermination(handle: string): Promise<PodTermination | null>;
+    alive(handle: string): Promise<boolean>;
+    watchClaimLifecycle(handle: string, signal?: AbortSignal): AsyncGenerator<ClaimPhase, void, unknown>;
+    /** Room anywhere: an ensure without room on Kubernetes lands on Freestyle. */
+    hasSchedulableCapacity(): Promise<boolean>;
+    getPreviewUrl(handle: string): Promise<string | null>;
+    proxyDaemonRequest(handle: string, path: string, init: ProxyRequestInit): Promise<Response>;
+    adoptLiveClaim(id: SandboxId, handle: string): Promise<boolean>;
+    resolvePreviewUpstreamUrl(handle: string): Promise<string | null>;
+    proxyPreviewRequest(handle: string, request: Request): Promise<Response>;
+    markTenantPoolsDirty(repoUrl: string, ref: string): Promise<string[]>;
+    releaseAfter(handle: string, graceMs: number): Promise<void>;
+    renewTtl(handle: string): Promise<void>;
+    daemonEndpoint(handle: string): Promise<{
+        url: string;
+        token: string;
+    } | null>;
+    /** Only Kubernetes sandboxes take pushed credentials. */
+    listSandboxes(): ReturnType<HostMethods["listSandboxes"]>;
+    listTenantPools(): ReturnType<HostMethods["listTenantPools"]>;
+    close(): void;
+}
+
 /**
  * The credentials a host outside Studio holds for its sandboxes. The host
  * never calls Studio: each `SANDBOX_ENSURE` brings the ones it was minted
@@ -1360,7 +1531,10 @@ interface SandboxToolDefinition<I extends z.ZodType = z.ZodType, O extends z.Zod
     outputSchema: O;
     execute(input: z.infer<I>): Promise<z.infer<O>>;
 }
-type Provider = Pick<AgentSandboxProvider, "ensure" | "delete" | "alive" | "getPreviewUrl" | "lastTermination" | "daemonEndpoint" | "renewTtl" | "releaseAfter" | "hasSchedulableCapacity" | "markTenantPoolsDirty" | "listSandboxes" | "listTenantPools">;
+type Provider = {
+    /** Absent on a Kubernetes-only host. */
+    providerOf?(handle: string): Promise<SandboxProviderKind>;
+} & Pick<AgentSandboxProvider, "ensure" | "delete" | "alive" | "getPreviewUrl" | "lastTermination" | "daemonEndpoint" | "renewTtl" | "releaseAfter" | "hasSchedulableCapacity" | "markTenantPoolsDirty" | "listSandboxes" | "listTenantPools">;
 
 /**
  * `provider` is read per call, so a host can build it lazily. `credentials`
@@ -1381,4 +1555,4 @@ declare function sandboxWatchResponse(provider: Pick<AgentSandboxProvider, "watc
  */
 declare function kubeConfigForServer(server: string): KubeConfig;
 
-export { AgentSandboxProvider, CREDENTIALS_PUSH_MAX, type ClaimPhase, type CredentialsPush, type Daemon, type EnsureOptions, type ListedTenantPool, type PortForwarder, type PostgresRunnerStateStore, type PostgresRunnerStateStoreOptions, type PostgresTenantPoolStore, type PostgresTenantPoolStoreOptions, PushedCredentials, type RepoIdentity, type RunnerStatePut, type RunnerStateRecord, type RunnerStateRecordWithId, type RunnerStateStore, type RunnerStateStoreOps, SANDBOX_LIST_MAX, SANDBOX_LIST_POOLS_MAX, SANDBOX_LIST_POOL_REPOS_MAX, SANDBOX_TOOLS, SANDBOX_WATCH_KEEPALIVE_MS, SANDBOX_WATCH_PATH, type Sandbox, type SandboxId, type SandboxList, type SandboxListing, type SandboxToolDefinition, type SandboxWarmPoolObject, type StoredTenantPool, type TenantPool, TenantPoolCapacityError, TenantPoolConflictError, type TenantPoolFieldsInput, type TenantPoolInput, type TenantPoolReader, type TenantPoolReaderOptions, type TenantPoolRepo, type TenantPoolRepoInput, type TenantPoolStore, type ToolError, capacityOutputSchema, claimPhaseSchema, credentialsPushInputSchema, credentialsPushOutputSchema, daemonSchema, emptySchema, ensureInputSchema, ensureOptionsSchema, ensureOutputSchema, handleInputSchema, kubeConfigForServer, lifetimeInputSchema, listOutputSchema, migrateSandboxControllerSchema, normalizeRepoUrl, postgresRunnerStateStore, postgresTenantPoolStore, pushedCredentialOptions, renderTenantPoolWarmPools, repoIdentitySchema, sandboxIdSchema, sandboxTools, sandboxWatchResponse, statusInputSchema, statusOutputSchema, tenantPoolFieldsSchema, tenantPoolReader, tenantPoolRepoSchema, tenantPoolSchema, tenantPoolsPushInputSchema, tenantPoolsPushOutputSchema, toolErrorSchema };
+export { AgentSandboxProvider, CREDENTIALS_PUSH_MAX, type ClaimPhase, type CredentialsPush, type Daemon, type EnsureOptions, FreestyleSandboxProvider, type FreestyleSandboxProviderOptions, type ListedTenantPool, type OwningSandboxProvider, type PortForwarder, type PostgresRunnerStateStore, type PostgresRunnerStateStoreOptions, type PostgresTenantPoolStore, type PostgresTenantPoolStoreOptions, PushedCredentials, type RepoIdentity, type RunnerStatePut, type RunnerStateRecord, type RunnerStateRecordWithId, type RunnerStateStore, type RunnerStateStoreOps, SANDBOX_LIST_MAX, SANDBOX_LIST_POOLS_MAX, SANDBOX_LIST_POOL_REPOS_MAX, SANDBOX_TOOLS, SANDBOX_WATCH_KEEPALIVE_MS, SANDBOX_WATCH_PATH, type Sandbox, type SandboxId, type SandboxList, type SandboxListing, type SandboxProviderKind, SandboxProviderRouter, type SandboxProviders, type SandboxToolDefinition, type SandboxWarmPoolObject, type StoredTenantPool, type TenantPool, TenantPoolCapacityError, TenantPoolConflictError, type TenantPoolFieldsInput, type TenantPoolInput, type TenantPoolReader, type TenantPoolReaderOptions, type TenantPoolRepo, type TenantPoolRepoInput, type TenantPoolStore, type ToolError, capacityOutputSchema, claimPhaseSchema, credentialsPushInputSchema, credentialsPushOutputSchema, daemonSchema, emptySchema, ensureInputSchema, ensureOptionsSchema, ensureOutputSchema, handleInputSchema, kubeConfigForServer, lifetimeInputSchema, listOutputSchema, migrateSandboxControllerSchema, normalizeRepoUrl, postgresRunnerStateStore, postgresTenantPoolStore, pushedCredentialOptions, renderTenantPoolWarmPools, repoIdentitySchema, sandboxIdSchema, sandboxTools, sandboxWatchResponse, statusInputSchema, statusOutputSchema, tenantPoolFieldsSchema, tenantPoolReader, tenantPoolRepoSchema, tenantPoolSchema, tenantPoolsPushInputSchema, tenantPoolsPushOutputSchema, toolErrorSchema };