@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/environment-manifests.js

@@ -1,208 +0,0 @@
-/**
- * Environment manifests (protocol 14, D63): `/v1/environment-manifests/{name}`, named and
- * versioned definitions of a kind of Environment, saved like agents.
- *
- * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged;
- *   any other writes the next version. A version is never changed or deleted alone.
- * - **No Environment changes.** Saving a version reaches no Environment: an Environment is made
- *   from one version and keeps it for life (`putEnvironment`). The plan counts those behind.
- * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
- *   changes from the latest, every reason the Runtime would refuse it (the Tenant's limits,
- *   missing artifacts), warnings, and how many Environments stay on older versions.
- *   `If-Match: <version>` refuses (`412 manifest_changed`) a save whose latest version moved
- *   since the client read it; `0` asks for a manifest that does not exist yet.
- * - **Every client is equal** (Q12): a version records who saved it (`savedBy`), and nothing is
- *   read-only by where it was saved from.
- */
-import {} from "@nylorun/core/contracts";
-import { hashManifest } from "@nylorun/core/compatibility";
-import { canonical } from "../store/canonical.js";
-import { resolveRecipe } from "../sandbox/resolve.js";
-import { limitIssues, manifestShapeIssues, readTenantLimits } from "./limits.js";
-import { readRuntimeLimits } from "./runtime-limits.js";
-import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
-import { actorOf, fileErrors } from "./environments.js";
-import { fail } from "./http.js";
-/** What an environment manifest asks of an Environment's recipe. */
-export function manifestRecipeRequest(manifest) {
-    return {
-        ...(manifest.image === undefined ? {} : { image: manifest.image }),
-        ...(manifest.resources === undefined ? {} : { resources: manifest.resources }),
-        ...(manifest.storage === undefined ? {} : { storage: manifest.storage }),
-        ...(manifest.network === undefined ? {} : { network: manifest.network }),
-        ...(manifest.harness === undefined ? {} : { harness: manifest.harness }),
-        ...(manifest.lifecycle === undefined ? {} : { lifecycle: manifest.lifecycle }),
-        ...(manifest.setup === undefined ? {} : { setup: manifest.setup }),
-        ...(manifest.files === undefined ? {} : { files: manifest.files }),
-        ...(manifest.limits === undefined ? {} : { limits: manifest.limits }),
-        ...(manifest.secrets === undefined ? {} : { secrets: manifest.secrets }),
-    };
-}
-/** The hash a manifest's version records: equal manifests hash the same. */
-export function environmentManifestHash(manifest) {
-    return hashManifest(manifest);
-}
-const notFound = (name, version) => fail(404, version === undefined ? `No environment manifest is named ${name}.` : `Environment manifest ${name} has no version ${version}.`, {
-    code: "manifest_not_found",
-});
-function viewOf(row, counts) {
-    return {
-        name: row.name,
-        version: row.version,
-        hash: row.hash,
-        manifest: row.body,
-        savedBy: row.savedBy,
-        createdAt: row.createdAt,
-        environments: counts.get(row.version) ?? 0,
-    };
-}
-/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
-export function manifestChanges(before, after, path = "") {
-    const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-    if (object(before) && object(after)) {
-        const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
-        return keys.flatMap((key) => manifestChanges(before[key], after[key], path ? `${path}.${key}` : key));
-    }
-    if (canonical(before) === canonical(after))
-        return [];
-    return [
-        {
-            path,
-            ...(before === undefined ? {} : { from: before }),
-            ...(after === undefined ? {} : { to: after }),
-        },
-    ];
-}
-/** What a save of `manifest` should tell its saver, though it would be saved. */
-function warningsOf(ctx, manifest) {
-    const warnings = [];
-    if (manifest.image !== undefined && !manifest.image.includes("@sha256:"))
-        warnings.push({
-            code: "image_tag",
-            message: `image ${manifest.image} is a tag, not a digest: each Environment pins what its first pod pulls, so two Tenants may run different bytes.`,
-        });
-    if (manifest.kind === "pod" && !ctx.pods)
-        warnings.push({
-            code: "pods_unavailable",
-            message: "kind pod needs sandbox pods, which this Tenant does not have: an Environment made from it is refused until `nylorun local sandbox enable`.",
-        });
-    return warnings;
-}
-/** Every reason the Runtime would refuse `manifest` now: the Tenant's limits and its files. */
-async function errorsOf(t, manifest) {
-    const config = effectiveSandboxConfig(await readSandboxConfig(t));
-    const resolved = resolveRecipe(manifest.kind ?? "virtual", manifestRecipeRequest(manifest), config);
-    return [
-        ...(resolved.kind === "error" ? resolved.errors : []),
-        ...limitIssues(manifest.limits, await readTenantLimits(t)),
-        ...manifestShapeIssues(manifest, await readRuntimeLimits(t)),
-        ...(await fileErrors(t, manifest.files)),
-    ];
-}
-export async function saveEnvironmentManifest(ctx, name, body, scope, options = {}) {
-    const { requestId: _, ...manifest } = body;
-    if (manifest.name !== name)
-        fail(400, `The manifest is named ${manifest.name}, and the path names ${name}: they must match.`);
-    const hash = environmentManifestHash(manifest);
-    const warnings = warningsOf(ctx, manifest);
-    return ctx.store.tx(async (t) => {
-        await t.lockEnvironmentManifest(name);
-        const latest = await t.environmentManifest(name);
-        if (options.ifMatch !== undefined && (latest?.version ?? 0) !== options.ifMatch)
-            fail(412, latest === undefined
-                ? `Environment manifest ${name} does not exist, and If-Match named version ${options.ifMatch}.`
-                : `Environment manifest ${name} is at version ${latest.version}, not ${options.ifMatch}: someone saved it since you read it. Read it again, or save without If-Match to replace it.`, { code: "manifest_changed", details: { latest: latest?.version ?? 0 } });
-        const unchanged = latest?.hash === hash;
-        const to = unchanged ? latest.version : (latest?.version ?? 0) + 1;
-        const counts = await t.environmentsOfManifest(name);
-        const errors = await errorsOf(t, manifest);
-        if (options.dryRun) {
-            let behind = 0;
-            for (const [version, n] of counts)
-                if (version < to)
-                    behind += n;
-            return {
-                name,
-                from: latest?.version ?? null,
-                to,
-                unchanged,
-                changes: unchanged ? [] : manifestChanges(latest?.body ?? {}, manifest),
-                warnings,
-                errors,
-                behind,
-            };
-        }
-        if (errors.length > 0)
-            fail(400, errors.join(" "));
-        if (unchanged)
-            return { manifest: viewOf(latest, counts), unchanged: true, warnings };
-        const row = {
-            name,
-            version: to,
-            body: manifest,
-            hash,
-            savedBy: { actor: actorOf(scope) },
-            createdAt: new Date().toISOString(),
-        };
-        await t.insertEnvironmentManifest(row);
-        // Its files by hash (Q6), recorded as a definition's are, for the sweep that deletes unused ones.
-        const shas = [...new Set((manifest.files ?? []).flatMap((file) => ("files" in file ? Object.values(file.files) : [])))];
-        if (shas.length > 0)
-            await t.insertDefinitionFileUses(`environment-manifest:${name}`, hash, shas);
-        return { manifest: viewOf(row, counts), unchanged: false, warnings };
-    });
-}
-/** `GET /v1/environment-manifests/{name}` (the latest) and `.../versions/{n}`. */
-export async function getEnvironmentManifest(ctx, name, version) {
-    return ctx.store.tx(async (t) => {
-        const row = (await t.environmentManifest(name, version)) ?? notFound(name, version);
-        return viewOf(row, await t.environmentsOfManifest(name));
-    });
-}
-/** `GET /v1/environment-manifests`: each manifest's latest version. */
-export async function listEnvironmentManifests(ctx) {
-    return ctx.store.tx(async (t) => {
-        const manifests = [];
-        for (const row of await t.listEnvironmentManifests())
-            manifests.push(viewOf(row, await t.environmentsOfManifest(row.name)));
-        return { manifests };
-    });
-}
-/** `GET /v1/environment-manifests/{name}/versions`: every version, newest first. */
-export async function environmentManifestVersions(ctx, name) {
-    return ctx.store.tx(async (t) => {
-        const rows = await t.environmentManifestVersions(name);
-        if (rows.length === 0)
-            notFound(name);
-        const counts = await t.environmentsOfManifest(name);
-        return {
-            name,
-            latest: rows[0].version,
-            versions: rows.map((row) => ({
-                version: row.version,
-                hash: row.hash,
-                savedBy: row.savedBy,
-                createdAt: row.createdAt,
-                environments: counts.get(row.version) ?? 0,
-            })),
-        };
-    });
-}
-/**
- * `DELETE /v1/environment-manifests/{name}`: deletes every version, refused while any Environment
- * was made from one (`409 manifest_in_use`): the Environment names the version it runs.
- */
-export async function deleteEnvironmentManifest(ctx, name) {
-    return ctx.store.tx(async (t) => {
-        await t.lockEnvironmentManifest(name);
-        let made = 0;
-        for (const n of (await t.environmentsOfManifest(name)).values())
-            made += n;
-        if (made > 0)
-            fail(409, `${made} Environment(s) were made from environment manifest ${name}: delete them first, or keep the manifest.`, {
-                code: "manifest_in_use",
-                details: { environments: made },
-            });
-        return { name, deleted: (await t.deleteEnvironmentManifest(name)) > 0 };
-    });
-}

package/dist/tenant/environments.d.ts

@@ -1,172 +0,0 @@
-import { type EnvironmentRecipe, type EnvironmentView, type ForkEnvironmentRequest, type ForkEnvironmentResponse, type PutEnvironmentRequest, type PutEnvironmentSecretRequest } from "@nylorun/core/contracts";
-import type { Environment, EnvironmentEventsQuery, Tx } from "../store/types.js";
-import type { SandboxRouteDeps } from "../core/sandbox-routes.js";
-import { type AuthScope, type Session, type TenantContext } from "./context.js";
-import type { SealedSecretCopies } from "../vault/service.js";
-/** The Environment grants that limit `scope`, or undefined when it reaches every Environment. */
-export declare function environmentGrantsOf(scope: AuthScope): readonly string[] | undefined;
-/** Who the vault's audit rows name for a request: the subject, else the application. */
-export declare function actorOf(scope: AuthScope): string;
-/** Refuses (the 404 of a missing one) Environment `id` when the caller's grants miss it. */
-export declare function assertReaches(scope: AuthScope, id: string): void;
-/** An Environment, unless it is gone or being deleted. */
-export declare function liveEnvironment(t: Tx, id: string, options?: {
-    lock?: boolean;
-}): Promise<Environment | undefined>;
-/**
- * Why input files cannot be used: each that is not a version of a Tenant-wide artifact (a
- * session's artifacts go with the session). Pins nothing else: the version is the one named.
- */
-export declare function fileErrors(t: Tx, files: EnvironmentRecipe["files"]): Promise<string[]>;
-/**
- * `PUT /v1/environments/{id}`: creates the Environment and its vault (within the Tenant's limit
- * on their number) from an environment manifest's version or from the inline fields, or finds
- * the one with this id, so "get or create" is one call. An existing one never changes what it
- * runs (D63): its labels and owner guard may change, fields that match are accepted, and any
- * other difference is `409 environment_immutable`. Every `PUT` counts as the Environment's use.
- */
-export declare function putEnvironment(ctx: TenantContext, id: string, body: PutEnvironmentRequest, scope: AuthScope, options?: {
-    fork?: Fork;
-}): Promise<EnvironmentView>;
-/**
- * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
- * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
- * `{ headers }` for a `headers` slot) with the binding from the slot; a full typed body is
- * accepted only when its binding is the slot's. Without slots, today's typed body.
- */
-export declare function secretRequestFor(ctx: TenantContext, id: string, name: string, raw: unknown): Promise<PutEnvironmentSecretRequest>;
-/** What a create does for a fork (`POST .../fork`); `copied` is filled in by the create. */
-interface Fork {
-    source: string;
-    setup: boolean;
-    /**
-     * The source's secrets sealed by keys for the new vault `vaultId` (F4.2), before the create's
-     * transaction, which inserts them; absent with `secrets: none`.
-     */
-    sealed?: {
-        vaultId: string;
-        copies: SealedSecretCopies;
-    };
-    copied?: {
-        copied: string[];
-        dropped: string[];
-    };
-}
-/**
- * `POST /v1/environments/{id}/fork` (Q15): how an Environment gets a new manifest version. A new
- * Environment `body.id` is made from the manifest version (default the source's manifest at its
- * latest), its disk started from a version of the source's (`latest` takes a snapshot first,
- * refused during a turn), and its secrets copied inside the Runtime. A fork onto other setup
- * runs that setup on the copied disk before its first turn (Q17). The source keeps what it runs,
- * its disk and its sessions. With `dryRun`, the plan only.
- */
-export declare function forkEnvironment(ctx: TenantContext, sourceId: string, body: ForkEnvironmentRequest, scope: AuthScope): Promise<ForkEnvironmentResponse>;
-/** `GET /v1/environments/{id}`. */
-export declare function getEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
-/** `GET /v1/environments?label=k=v`: every Environment with all the labels, that the caller reaches. */
-export declare function listEnvironments(ctx: TenantContext, labels: Record<string, string>, scope: AuthScope): Promise<{
-    environments: EnvironmentView[];
-}>;
-/**
- * Asks pod Environment `id` to run when it is stopped or failed (a disk copy needs its engine),
- * with its recipe applied, as a turn start would.
- */
-export declare function wakePod(ctx: TenantContext, id: string): Promise<void>;
-/** Whether a disk lease (R2d step 3) holds `environment` now. */
-export declare function diskHeld(environment: Environment, now?: number): boolean;
-/** Refused while a snapshot or restore copies the disk (a pending seed does not count). */
-export declare function refuseDiskCopy(environment: Environment): void;
-/**
- * `DELETE /v1/environments/{id}`: deletes the Environment, its vault and its workspace. Refused
- * while a session that names it has an active turn. Sessions keep its id: their next turn is
- * refused (`environment_unavailable`) unless an Environment with this id exists again.
- */
-export declare function deleteEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<{
-    id: string;
-    deleted: boolean;
-}>;
-/**
- * Deletes every Environment unused for its `lifecycle.deleteAfter` (Q13): no turn, recipe
- * change, secret write, stop or reset since. One with a turn running waits for the next sweep.
- * Run by the Tenant sweep.
- */
-export declare function sweepUnusedEnvironments(ctx: TenantContext, now?: number): Promise<void>;
-/**
- * `POST /v1/environments/{id}/stop`: suspends a pod Environment. Its volume is kept, and the next
- * turn of a session that names it starts it again. Refused during a turn.
- */
-export declare function stopEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
-/**
- * `POST /v1/environments/{id}/reset`: a new pod on a new, empty volume (the next volume
- * generation), with a new join token and the recipe applied; the old Sandbox and volume are
- * deleted. Leaves `lost` and `failed`. Refused during a turn, and while an earlier reset's
- * Sandbox is still being deleted.
- */
-export declare function resetEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
-/**
- * Gives pod Environment `environment` (locked) a new pod on a new, empty volume, the next volume
- * generation, with its recipe applied: the old Sandbox and volume are retired. With `seed`, the
- * new volume starts from that disk version before any turn (R2d step 3): a restore, or the
- * recovery of a lost volume.
- */
-export declare function newVolume(ctx: TenantContext, t: Tx, environment: Environment, options?: {
-    seed?: {
-        artifactId: string;
-        version: number;
-    };
-    reason?: "restore" | "lost";
-}): Promise<number>;
-/** `GET /v1/environments/{id}/events`: the Environment's lifecycle stream. */
-export declare function environmentEventsOf(ctx: TenantContext, id: string, scope: AuthScope, query?: EnvironmentEventsQuery): Promise<{
-    events: {
-        schema: "nylorun.environment-event/1";
-        eventId: string;
-        tenantId: string;
-        environmentId: string;
-        seq: number;
-        time: string;
-        type: "environment.attached" | "environment.created" | "environment.deleted" | "environment.detached" | "environment.egress" | "environment.failed" | "environment.forked" | "environment.lost" | "environment.relaunched" | "environment.reset" | "environment.running" | "environment.suspended";
-        payload: Record<string, unknown>;
-    }[];
-}>;
-/**
- * Opens a new session on Environment `id` (`PutSessionRequest.environment`): it must exist, be
- * reachable with `grants` and pass its owner guard. Runs in the session's transaction, after
- * its session row lock; holds the Environment's row lock.
- */
-export declare function openEnvironment(t: Tx, id: string, options: {
-    grants?: readonly string[];
-    ownerUserId: string;
-    opaque: boolean;
-}): Promise<Environment>;
-/** Records the attachment on the session's log and on the Environment's stream. */
-export declare function recordAttachment(t: Tx, sessionId: string, environmentId: string): Promise<void>;
-/**
- * Checks a turn start on a session that names an Environment, in the command's transaction
- * after the session row lock: the Environment still exists, a token caller's grants reach it,
- * its owner guard admits the session's owner, and no disk copy holds it. Other sessions' turns
- * do not stop it (D66). Holds the Environment row's lock until the transaction ends, so a turn
- * start and disk work on one Environment are decided one after the other.
- *
- * A pod Environment must also be usable: not lost (`environment_lost`), on a Runtime with
- * sandbox pods (`environment_unavailable`). A stopped or failed pod is asked to run again, with
- * its recipe applied, after the commit.
- */
-export declare function checkEnvironmentTurn(t: Tx, session: Session, scope: AuthScope, ctx?: TenantContext): Promise<void>;
-/** A sessions reset detaches every session from its Environment: each one's stream says so. */
-export declare function detachAllSessions(t: Tx): Promise<void>;
-/**
- * Marks the end of a turn's segment on Environment `id`: it was used now (`deleteAfter` counts
- * from here), and for a running pod idle counts from now and the idle timer is armed (D34).
- * Best effort.
- */
-export declare function touchEnvironment(ctx: TenantContext, id: string): Promise<void>;
-/**
- * Re-arms the idle timer of every running pod after the Tenant's settings change, so a shorter
- * `limits.idle` applies to pods already idle (D36: the settings are read whenever a timer is
- * set). Best effort.
- */
-export declare function rearmPodTimers(ctx: TenantContext): Promise<void>;
-/** Session lookups for the sandbox route handlers (`core/sandbox-routes.ts`). */
-export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;
-export {};