@crowdedkingdoms/crowdyjs 17.10.0-dev.1 → 17.12.0-dev.1

package/dist/domains/exec.js

@@ -1,6 +1,7 @@
 import { decode, encode } from '@msgpack/msgpack';
 import { CrowdyError } from '../errors.js';
-import { ExecActivateVersionDocument, ExecAppStatusDocument, ExecConnectAsDeveloperDocument, ExecConnectDocument, ExecDeployDocument, ExecInstancesDocument, ExecLogsDocument, ExecSetEnabledDocument, ExecVersionsDocument, } from '../generated/graphql.js';
+import { ExecActivateVersionDocument, ExecAppStatusDocument, ExecBuildDocument, ExecBuildStatusDocument, ExecConnectAsDeveloperDocument, ExecConnectDocument, ExecDeployDocument, ExecInstancesDocument, ExecLogsDocument, ExecAppModsDocument, ExecModBuildDocument, ExecModBuildStatusDocument, ExecModDeleteDocument, ExecModDeployDocument, ExecModInstallDocument, ExecModListingsDocument, ExecModLogsDocument, ExecModPublishDocument, ExecModScope, ExecModSetEnabledDocument, ExecModSetSwitchDocument, ExecModStarterDocument, ExecModSwitchesDocument, ExecModUnpublishDocument, ExecModsDocument, ExecMyModsDocument, ExecSetEnabledDocument, ExecStartersDocument, ExecVersionsDocument, } from '../generated/graphql.js';
+export { ExecModScope };
 /**
  * ck-exec, the hub-and-spoke execution service (dev-tier preview).
  *
@@ -512,13 +513,22 @@ async function sha256Hex(bytes) {
     const d = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
     return Array.from(d, (x) => x.toString(16).padStart(2, '0')).join('');
 }
+/** The node type players call a mod by: `mod:<name>`, keyed by its grid id. */
+export function execModType(name) {
+    return `mod:${name}`;
+}
 function strip(v) {
     const { __typename: _, ...rest } = v;
     return rest;
 }
+function build(b) {
+    const { __typename: _, artifacts, ...rest } = b;
+    return { ...rest, artifacts: artifacts.map(strip) };
+}
 /**
- * `client.exec`: connecting players to ck-exec, deploying an app's nodes, and operating
- * them (logs, instances, versions, rollback, the kill switch, developer connections).
+ * `client.exec`: connecting players to ck-exec, building and deploying an app's nodes (and
+ * the starter packs), and operating them (logs, instances, versions, rollback, the kill
+ * switch, developer connections).
  */
 export class ExecAPI {
     constructor(graphql) {
@@ -585,6 +595,179 @@ export class ExecAPI {
         const data = await this.graphql.request(ExecSetEnabledDocument, { appId, enabled, nodeType });
         return strip(data.execSetEnabled);
     }
+    /**
+     * The starter packs, which replace the compute templates: a world tick (the root hub), a
+     * matchmaker, game sessions and an NPC and mob engine. Build them with {@link build} and
+     * deploy the build with `manifest`. Requires `manage_compute`.
+     */
+    async starters(appId) {
+        const data = await this.graphql.request(ExecStartersDocument, { appId });
+        return {
+            manifest: JSON.parse(data.execStarters.manifestJson),
+            starters: data.execStarters.starters.map((s) => ({
+                crate: s.crate,
+                nodeType: s.nodeType,
+                description: s.description,
+                files: s.files.map(strip),
+            })),
+        };
+    }
+    /**
+     * Builds crates into modules on the platform (`ckx-sdk`, `wasm32-unknown-unknown`), so you
+     * need no Rust toolchain. Returns at once with the build queued; wait with
+     * {@link waitForBuild}, then {@link deploy} with its `buildId`. Requires `manage_compute`.
+     */
+    async build(appId, crates) {
+        const data = await this.graphql.request(ExecBuildDocument, {
+            input: {
+                appId,
+                crates: crates.map((c) => ({
+                    name: c.name,
+                    files: Array.isArray(c.files)
+                        ? c.files
+                        : Object.entries(c.files).map(([path, content]) => ({ path, content })),
+                })),
+            },
+        });
+        return build(data.execBuild);
+    }
+    /** A build's status, log and modules, or null. Requires `view_compute_diagnostics`. */
+    async buildStatus(appId, buildId) {
+        const data = await this.graphql.request(ExecBuildStatusDocument, { appId, buildId });
+        return data.execBuildStatus ? build(data.execBuildStatus) : null;
+    }
+    /**
+     * Polls a build until it succeeds or fails, and returns it either way; a failed build's
+     * `log` says why. Throws when it is not done in `timeoutMs` (default 10 minutes).
+     */
+    async waitForBuild(appId, buildId, options = {}) {
+        const until = Date.now() + (options.timeoutMs ?? 600000);
+        for (;;) {
+            const b = await this.buildStatus(appId, buildId);
+            if (!b)
+                throw new CrowdyError({ message: `no build ${buildId} in app ${appId}` });
+            if (b.status === 'succeeded' || b.status === 'failed')
+                return b;
+            if (Date.now() > until)
+                throw new CrowdyError({ message: `build ${buildId} is still ${b.status}` });
+            await new Promise((r) => setTimeout(r, options.intervalMs ?? 2000));
+        }
+    }
+    // ---- mods: players' code on grids they own ----
+    /** The mod starter (`grid-mod`), a crate to build with {@link modBuild}. Requires access to the app. */
+    async modStarter(appId) {
+        const data = await this.graphql.request(ExecModStarterDocument, { appId });
+        const s = data.execModStarter;
+        return { crate: s.crate, nodeType: s.nodeType, description: s.description, files: s.files.map(strip) };
+    }
+    /**
+     * Builds a mod from one `ckx-sdk` crate, as {@link build} does a developer's. Returns at
+     * once; wait with {@link waitForModBuild}, then {@link modDeploy}. One build at a time per
+     * player. Requires `write_server_code` in the app.
+     */
+    async modBuild(appId, crate) {
+        const files = Array.isArray(crate.files)
+            ? crate.files
+            : Object.entries(crate.files).map(([path, content]) => ({ path, content }));
+        const data = await this.graphql.request(ExecModBuildDocument, {
+            appId,
+            crate: { name: crate.name, files },
+        });
+        return build(data.execModBuild);
+    }
+    /** A mod build of yours. */
+    async modBuildStatus(appId, buildId) {
+        const data = await this.graphql.request(ExecModBuildStatusDocument, { appId, buildId });
+        return build(data.execModBuildStatus);
+    }
+    /** Polls a mod build until it succeeds or fails, like {@link waitForBuild}. */
+    async waitForModBuild(appId, buildId, options = {}) {
+        const until = Date.now() + (options.timeoutMs ?? 600000);
+        for (;;) {
+            const b = await this.modBuildStatus(appId, buildId);
+            if (b.status === 'succeeded' || b.status === 'failed')
+                return b;
+            if (Date.now() > until)
+                throw new CrowdyError({ message: `build ${buildId} is still ${b.status}` });
+            await new Promise((r) => setTimeout(r, options.intervalMs ?? 2000));
+        }
+    }
+    /**
+     * Deploys a mod build of yours to a grid you own: a new mod starts switched off, and a
+     * running one restarts on the new version. Requires being the grid's owner and
+     * `write_server_code` on the app tier and the grid.
+     */
+    async modDeploy(appId, gridId, name, buildId) {
+        const data = await this.graphql.request(ExecModDeployDocument, { appId, gridId, name, buildId });
+        return strip(data.execModDeploy);
+    }
+    /**
+     * Switches a mod on your grid on or off. On, it runs as you once the app's code admission
+     * admits it. Requires `run_server_code` on the app tier and the grid.
+     */
+    async modSetEnabled(appId, gridId, name, enabled) {
+        const data = await this.graphql.request(ExecModSetEnabledDocument, { appId, gridId, name, enabled });
+        return strip(data.execModSetEnabled);
+    }
+    /** Stops and removes a mod on your grid, with its state. */
+    async modDelete(appId, gridId, name) {
+        const data = await this.graphql.request(ExecModDeleteDocument, { appId, gridId, name });
+        return data.execModDelete;
+    }
+    /** A grid's mods, which players in it call as `mod:<name>` with the grid id as key. */
+    async mods(appId, gridId) {
+        const data = await this.graphql.request(ExecModsDocument, { appId, gridId });
+        return data.execMods.map(strip);
+    }
+    /** Your mods in the app, on every grid. */
+    async myMods(appId) {
+        const data = await this.graphql.request(ExecMyModsDocument, { appId });
+        return data.execMyMods.map(strip);
+    }
+    /** A mod of yours' guest log lines, newest first. */
+    async modLogs(appId, gridId, name, options = {}) {
+        const data = await this.graphql.request(ExecModLogsDocument, { appId, gridId, name, ...options });
+        return data.execModLogs.map(strip);
+    }
+    /** Publishes a mod of yours, at its current version, for other grid owners to install. */
+    async modPublish(appId, gridId, name, title, description) {
+        const data = await this.graphql.request(ExecModPublishDocument, { appId, gridId, name, title, description });
+        return strip(data.execModPublish);
+    }
+    /** The app's listed mods, most installed first. */
+    async modListings(appId) {
+        const data = await this.graphql.request(ExecModListingsDocument, { appId });
+        return data.execModListings.map(strip);
+    }
+    /** Delists a listing you published; installed copies keep running. */
+    async modUnpublish(appId, listingId) {
+        const data = await this.graphql.request(ExecModUnpublishDocument, { appId, listingId });
+        return data.execModUnpublish;
+    }
+    /** Installs a listing onto a grid you own as your own mod, switched off. */
+    async modInstall(appId, gridId, name, listingId) {
+        const data = await this.graphql.request(ExecModInstallDocument, { appId, gridId, name, listingId });
+        return strip(data.execModInstall);
+    }
+    /** The app's mods by grid or owner, or all of them. Requires `view_compute_diagnostics`. */
+    async appMods(appId, options = {}) {
+        const data = await this.graphql.request(ExecAppModsDocument, { appId, ...options });
+        return data.execAppMods.map(strip);
+    }
+    /** The app's mod switches that are off. Requires `view_compute_diagnostics`. */
+    async modSwitches(appId) {
+        const data = await this.graphql.request(ExecModSwitchesDocument, { appId });
+        return data.execModSwitches.map(strip);
+    }
+    /**
+     * The mods kill ladder: switch off (or on) one mod (`target`: its mod id), a player's mods
+     * (their user id), a grid's (its id), a listing's installs (its id), or every mod in the
+     * app (no target). Returns the switches that are off. Requires `manage_compute`.
+     */
+    async modSetSwitch(appId, scope, off, options = {}) {
+        const data = await this.graphql.request(ExecModSetSwitchDocument, { appId, scope, off, ...options });
+        return data.execModSetSwitch.map(strip);
+    }
     /** A host for this player and its connect token (valid for about a minute). */
     async endpoint(appId, options = {}) {
         const data = await this.graphql.request(ExecConnectDocument, {
@@ -606,14 +789,22 @@ export class ExecAPI {
     }
     /**
      * Deploys a new version of the app's nodes and makes it active: the manifest, and
-     * each distinct module once. Running instances pick it up when they next start.
-     * Requires the org `manage_compute` permission.
+     * each distinct module once. A type gives its module as `wasm`, or names a `crate` of
+     * `buildId`, whose modules the platform already holds. Running instances pick it up
+     * when they next start. Requires the org `manage_compute` permission.
      */
     async deploy(options) {
         const types = {};
         const artifacts = new Map();
         for (const [name, t] of Object.entries(options.types)) {
             const { wasm, ...spec } = t;
+            if (!wasm) {
+                if (!spec.crate || !options.buildId) {
+                    throw new CrowdyError({ message: `type '${name}' needs its wasm, or a crate of the deploy's buildId` });
+                }
+                types[name] = spec;
+                continue;
+            }
             const digest = await sha256Hex(wasm);
             if (!artifacts.has(digest))
                 artifacts.set(digest, base64(wasm));
@@ -624,6 +815,7 @@ export class ExecAPI {
                 appId: options.appId,
                 manifestJson: JSON.stringify({ root: options.root, types }),
                 artifacts: [...artifacts].map(([digest, wasmBase64]) => ({ digest, wasmBase64 })),
+                buildId: options.buildId,
             },
         });
         return data.execDeploy;