@guanjinke/artifact-client 1.10.0 → 1.12.0

package/dist/environment/update.js

@@ -40,6 +40,7 @@ const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const fast_xml_parser_1 = require("fast-xml-parser");
 const catalog_1 = require("./catalog");
+const deferred_1 = require("./deferred");
 const archive_1 = require("./archive");
 const builder_1 = require("./builder");
 const config_1 = require("./config");
@@ -57,12 +58,14 @@ const windowsPath = (value, platform) => (0, local_path_1.nativeSeparators)(valu
 /** The separator the recorded entries use on the target platform. */
 const separatorOf = (platform) => (platform === 'win32' ? '\\' : '/');
 /**
- * Every catalog module an update may refresh. The create-only modules are
- * excluded: they seed data the product imports once, when the Server starts for
- * the first time, so an update never refreshes, preserves or re-deploys them —
- * and the web update picker reads this same list.
+ * Every catalog module a user may refresh. Both the create-only modules and the
+ * internal ones are excluded: a create-only module seeds a tree the Server owns
+ * (the first-start sample data) which no update can reproduce, and an internal
+ * module (the built-in 3D scene and map resources) is maintained by the updater
+ * itself — so an update never refreshes, preserves or re-deploys either on
+ * request. The web update picker reads this same list.
  */
-exports.updatableModules = Object.keys(catalog_1.catalog).filter(module => !catalog_1.catalog[module].createOnly).sort();
+exports.updatableModules = Object.keys(catalog_1.catalog).filter(module => !catalog_1.catalog[module].createOnly && !catalog_1.catalog[module].internal).sort();
 /**
  * Server-root settings the environment owns.
  *
@@ -91,7 +94,49 @@ const requiredPackageFiles = {
  */
 const excludedCopyNames = (mapping) => mapping.role === 'server' ? [...serverOwnedFiles] : mapping.role === 'monitor' ? ['conf'] : [];
 /**
- * The modules a selection may name, from the same table `create-env` and the web
+ * Download the payload of a deferred module.
+ *
+ * It is published as files, not as an archive: the provider keeps the relative
+ * sub-path and the file is deployed exactly as downloaded, so nothing is
+ * extracted. Exactly one object is downloaded for `patch`. The public label is
+ * the only name in progress output or in errors.
+ */
+async function stageReplacement(client, module, version, payloads, workspace, onProgress) {
+    const entry = catalog_1.catalog[module];
+    const label = (0, catalog_1.moduleLabel)(entry);
+    const download = path.join(workspace, 'download', label);
+    try {
+        await fs.mkdir(download, { recursive: true });
+        onProgress?.(`[${label}] ${label}/${version}: Downloading replacement`);
+        const files = [];
+        for (const payload of payloads) {
+            await client.downloadArtifact(entry.plugin, version, payload.name, download);
+            const source = path.join(download, ...payload.name.split('/'));
+            await (0, builder_1.regularFile)(source);
+            files.push({ name: payload.name, source, sha256: await (0, builder_1.hashFile)(source) });
+        }
+        onProgress?.(`[${label}] ${label}/${version}: Download complete; replacement ready`);
+        return { version, files };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`Module ${label} could not be applied:`))
+            throw error;
+        throw new Error(`Module update failed for ${label}/${version} (download or layout).`);
+    }
+}
+/** One environment-relative Server path inside a staged Server package. */
+function stagedServerPath(staged, relative) {
+    const server = catalog_1.catalog.server.mappings.find(mapping => mapping.role === 'server');
+    const prefix = server ? `${server.destination}/` : '';
+    const inner = prefix && relative.startsWith(prefix) ? relative.slice(prefix.length) : relative;
+    return path.join(staged.expanded, ...(server?.source ? server.source.split('/') : []), ...inner.split('/'));
+}
+/** The version file inside a staged Server package, before it is laid out. */
+function stagedServerFile(staged, module) {
+    const descriptor = catalog_1.catalog[module].deferred;
+    return stagedServerPath(staged, descriptor.versionFile);
+}
+/** The modules a selection may name, from the same table `create-env` and the web
  * interface read.
  *
  * Reading it through the call keeps this module loadable on its own: the policy
@@ -109,9 +154,14 @@ function validateUpdatableModule(module) {
     // `hasOwnProperty` keeps prototype names (`constructor`) out of the catalog.
     if (!Object.prototype.hasOwnProperty.call(catalog_1.catalog, module))
         throw new Error(`Unsupported module "${module}": supported modules are ${exports.updatableModules.join(', ')}.`);
-    // A create-only module is refused before anything else happens — before the
-    // registry, the manifest or the configuration is read — because no update can
-    // produce it: it is deployed only while the environment is created.
+    // An internal module is refused before anything else happens — before the
+    // registry, the manifest or the configuration is read — because the user never
+    // selects it: the updater deploys it with the environment and re-deploys it
+    // together with the package whose directory holds its files.
+    if (catalog_1.catalog[module].internal)
+        throw new Error(`Module ${module} is internal: it is deployed with the environment and refreshed automatically with the Server package, so it cannot be selected or updated directly.`);
+    // A create-only module is refused for the same reason: no update can produce
+    // it, because it is deployed only while the environment is created.
     if (catalog_1.catalog[module].createOnly)
         throw new Error(`Module ${module} is create-only: it is deployed only when the environment is created and is never refreshed, preserved or re-deployed by update-env. Recreate the environment with create-env to get it again.`);
 }
@@ -178,6 +228,11 @@ function pushSpec(specs, seen, spec) {
     }
     else {
         validateUpdatableModule(spec.module);
+        // A deferred module's version is always the one recorded by the deployed (or
+        // newly staged) Server package. Pinning a different one would either be
+        // ignored or produce a mismatched environment, so it is refused.
+        if (catalog_1.catalog[spec.module].deferred && spec.version !== undefined)
+            throw new Error(`Module ${spec.module} takes its version from the deployed Server package: a pinned version is not supported.`);
         if (seen.has(allModules))
             throw new Error('Module spec all cannot be combined with individual modules.');
         const previous = seen.get(spec.module);
@@ -553,14 +608,17 @@ function environmentSchema(manifest, configuration) {
  * that policy. Returns the warning text, or undefined when the package is
  * complete.
  */
-async function verifyStagedPackage(module, staged, schema) {
+async function verifyStagedPackage(module, staged, schema, required = requiredPackageFiles[module] ?? []) {
     const label = `${staged.plugin}/${staged.version}/${staged.name}`;
-    for (const name of requiredPackageFiles[module] ?? []) {
+    for (const name of required) {
         try {
             await (0, builder_1.regularFile)(path.join(staged.expanded, name));
         }
+        // The Server's required file is the one the selectable patch replaces, so the
+        // message stays generic: its name must not be user-visible. Every other
+        // module's required file name is public and useful.
         catch {
-            throw new Error(`Module update failed for ${label}: the package is missing ${name}.`);
+            throw new Error(`Module update failed for ${label}: the package is missing ${module === 'server' ? 'a required runtime file' : name}.`);
         }
     }
     const relative = `xsd/${schema}/Wyn.conf.xsd`;
@@ -636,10 +694,17 @@ function mappingForAssembly(module, assembly) {
  * explicitly, for a build whose file name matches no assembly at all.
  */
 async function resolveLocalSource(entry, module, assembly, input) {
-    // The built-in resource module is never a developer-build target: it ships a
-    // static asset tree that no local DLL could stand in for, so a local source is
-    // refused on its own terms before any path is even looked at. Remote specs
-    // (latest, pinned and `all`) keep working.
+    // A deferred module is a published replacement for one file the Server package
+    // owns; a developer build has no mapping the configuration could point at, so
+    // a local source is refused on its own terms before any path is looked at.
+    // The message names the module only.
+    if (catalog_1.catalog[module].deferred)
+        throw new Error(`Module ${module} is refreshed from its published artifact only and has no local source.`);
+    // Any built-in trailing module is never a developer-build target either: it
+    // ships a static asset tree no local DLL could stand in for. Both are refused
+    // as explicit specs before this point (one internal, one create-only); this
+    // guard is the safety net for a trailing module a user could select, whose
+    // remote specs would keep working.
     if (plan_1.trailingModules.includes(module))
         throw new Error(`Module ${module} is built in and has no local source: it ships the 3D scene and map assets and is always deployed from its published artifact. Refresh it from the cloud (\`${module}\`, \`${module}:<version>\` or \`all\`).`);
     const mappings = localMappings(module);
@@ -789,12 +854,15 @@ class EnvironmentUpdater {
             localOverrides.set(spec.module, targets);
         }
         const remote = parsed.filter(spec => spec.localPath === undefined);
-        // The built-in resource module deploys its trees *inside* the Server
-        // directory, and a Server refresh replaces that whole directory. An
-        // environment that has it therefore re-deploys it from its own artifact
-        // whenever the Server is refreshed in the same call: a remote-only module has
-        // no local copy to restore the trees from. A create-only trailing module is
-        // never re-deployed: the Server refresh simply drops what it had seeded.
+        // Internal modules are never named by a spec (they are refused while the
+        // module specs are parsed) and `all` never selects them, but the updater
+        // still deploys them on its own. `dashboard-resource` ships the 3D scene and
+        // map trees *inside* the Server directory, and a Server refresh replaces that
+        // whole directory: an environment that has it therefore re-deploys it from
+        // its own artifact whenever the Server is refreshed in the same call, because
+        // there is no other copy to restore the trees from. A create-only trailing
+        // module is different: it seeds data the product imported once, so a Server
+        // refresh simply drops what it had seeded.
         const autoRefreshed = [];
         if (remote.some(spec => spec.module === 'server')) {
             for (const module of plan_1.trailingModules) {
@@ -806,6 +874,21 @@ class EnvironmentUpdater {
                 onProgress?.(`${module} is refreshed with the Server package: its trees deploy inside the Server directory`);
             }
         }
+        // A Server refresh restores the unpatched file the Server package ships, so
+        // an installed deferred module is re-applied in the same call. Its version is
+        // resolved from the *new* package below, never from the old tree. Without a
+        // Server refresh it is only applied when the caller names it explicitly.
+        const autoReplaced = [];
+        if (remote.some(spec => spec.module === 'server')) {
+            for (const module of Object.keys(catalog_1.catalog)) {
+                if (!catalog_1.catalog[module].deferred || !installed.has(module) || parsed.some(spec => spec.module === module))
+                    continue;
+                parsed.push({ module });
+                remote.push({ module });
+                autoReplaced.push(module);
+                onProgress?.(`${module} is re-applied with the Server package: the new package replaces the file it patches`);
+            }
+        }
         // Smart documents cannot run without the collaboration service, which
         // create-env deploys and declares in the Server configuration alongside
         // documents. Installing documents into an environment with no collaboration
@@ -836,15 +919,57 @@ class EnvironmentUpdater {
         try {
             const resolved = new Map();
             const staged = new Map();
+            const replacements = new Map();
             if (remote.length) {
                 const client = clientFactory();
-                for (const spec of remote) {
+                const direct = remote.filter(spec => !catalog_1.catalog[spec.module].deferred);
+                for (const spec of direct) {
                     onProgress?.(`Resolving ${catalog_1.catalog[spec.module].plugin}`);
                     resolved.set(spec.module, await resolveRemoteArtifact(client, entry, spec));
                 }
                 if (!dryRun)
-                    for (const spec of remote)
+                    for (const spec of direct)
                         staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), editionOf(entry), workspace, onProgress));
+                // A deferred module resolves after the direct artifacts are staged, so a
+                // Server refresh contributes the *new* package's version. Without a
+                // Server refresh the already deployed tree is the authority. A dry-run
+                // that refreshes the Server cannot know that version without downloading
+                // the package, so it reports the deferred resolution and stops there.
+                for (const spec of remote.filter(candidate => catalog_1.catalog[candidate.module].deferred)) {
+                    const module = spec.module;
+                    const source = catalog_1.catalog[module];
+                    const label = (0, catalog_1.moduleLabel)(source);
+                    const server = staged.get('server');
+                    let version;
+                    if (server) {
+                        version = await (0, deferred_1.deferredVersionAt)(source, stagedServerFile(server, module));
+                        // The replacement must overwrite an existing regular file in the new
+                        // package; checking the staged tree catches a package that no longer
+                        // ships it before anything has been written.
+                        for (const mapping of (0, deferred_1.replacementMappings)(source)) {
+                            const file = stagedServerPath(server, mapping.destination);
+                            const stat = await lstatOrUndefined(file);
+                            if (!stat)
+                                throw new Error(`Module ${label} could not be applied: the Server package holds no file to replace.`);
+                            if (!stat.isFile() || stat.isSymbolicLink())
+                                throw new Error(`Module ${label} could not be applied: the Server package holds no regular file to replace.`);
+                        }
+                    }
+                    else if (remote.some(candidate => candidate.module === 'server')) {
+                        onProgress?.(`${label}: version resolves from the refreshed Server package at execution time`);
+                        replacements.set(module, { version: '' });
+                        continue;
+                    }
+                    else
+                        version = await (0, deferred_1.deferredVersion)(source, entry.root);
+                    const payloads = await (0, deferred_1.deferredPayload)(source, version, client);
+                    if (dryRun) {
+                        onProgress?.(`${label}/${version}: resolved from the deployed Server package; nothing downloaded`);
+                        replacements.set(module, { version });
+                        continue;
+                    }
+                    replacements.set(module, await stageReplacement(client, module, version, payloads, workspace, onProgress));
+                }
             }
             const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
             // A Server or Monitor package is only usable when it still serves the
@@ -856,11 +981,16 @@ class EnvironmentUpdater {
             if (remote.some(spec => spec.module === 'server' || spec.module === 'monitoring') && !schema) {
                 throw new Error(`Module update for ${remote.filter(spec => spec.module === 'server' || spec.module === 'monitoring').map(spec => spec.module).join(' and ')} needs the configuration schema of ${entry.name}, which neither its manifest nor its conf/Wyn.conf records. Recreate the environment with create-env.`);
             }
+            // A planned deferred module validates the exact Server file it replaces,
+            // with a message that names only the module; the Server's own required-file
+            // check would otherwise report the same missing file by its internal name.
+            const deferredPlanned = remote.some(spec => catalog_1.catalog[spec.module].deferred);
             for (const spec of remote) {
                 const stagedArtifact = staged.get(spec.module);
                 if (!stagedArtifact || !schema || !(spec.module in requiredPackageFiles))
                     continue;
-                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema);
+                const required = spec.module === 'server' && deferredPlanned ? [] : requiredPackageFiles[spec.module];
+                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema, required);
                 if (warning)
                     warnings.push(warning);
             }
@@ -868,9 +998,11 @@ class EnvironmentUpdater {
             // A module may carry several local specs: plan it once, for all its targets.
             // The built-in trailing modules are planned last, in the same order
             // `create-env` assembles: their trees live inside other modules'
-            // directories, so a Server replacement must not wipe them again.
-            const planOrder = [...new Set(parsed.map(spec => spec.module))]
-                .sort((left, right) => Number(plan_1.trailingModules.includes(left)) - Number(plan_1.trailingModules.includes(right)));
+            // directories, so a Server replacement must not wipe them again. A deferred
+            // module runs after `server` even when the caller wrote it first: the Server
+            // directory must hold the new package before it is patched.
+            const rank = (module) => plan_1.trailingModules.includes(module) ? 2 : catalog_1.catalog[module].deferred ? 1 : 0;
+            const planOrder = [...new Set(parsed.map(spec => spec.module))].sort((left, right) => rank(left) - rank(right));
             for (const module of planOrder) {
                 const artifact = artifacts.find(candidate => candidate.module === module);
                 const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
@@ -900,6 +1032,37 @@ class EnvironmentUpdater {
                     });
                     continue;
                 }
+                // A deferred module replaces one existing regular file and contributes
+                // no directory, plugin, worker, service or runtime requirement. Its
+                // version and payload were resolved above; nothing about the provider is
+                // recorded, and the target is checked before any write.
+                if (catalog_1.catalog[module].deferred) {
+                    const replacement = replacements.get(module);
+                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[module]);
+                    const version = replacement?.version || undefined;
+                    const files = [];
+                    if (replacement?.files?.length) {
+                        const mappings = (0, deferred_1.replacementMappings)(catalog_1.catalog[module]);
+                        for (const file of replacement.files) {
+                            const matches = mappings.filter(mapping => mapping.source === file.name);
+                            if (matches.length !== 1)
+                                throw new Error(`Module ${label} could not be applied: the replacement target is not configured.`);
+                            const destination = installationDirectory(entry.root, matches[0].destination);
+                            const stat = await lstatOrUndefined(destination);
+                            if (!stat)
+                                throw new Error(`Module ${label} could not be applied: the Server tree holds no file to replace.`);
+                            if (!stat.isFile() || stat.isSymbolicLink())
+                                throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                            files.push({ source: file.source, destination, sha256: file.sha256 });
+                        }
+                    }
+                    plans.push({
+                        module, previous, next: version ? { version } : {},
+                        ...(files.length ? { replacement: { version: version, files } } : {}),
+                        entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
+                    });
+                    continue;
+                }
                 const remoteArtifact = resolved.get(module);
                 const stagedArtifact = staged.get(module);
                 const copies = [];
@@ -1018,6 +1181,28 @@ class EnvironmentUpdater {
                     }
                     delete moduleSources[plan.module];
                 }
+                if (plan.replacement) {
+                    // The record keeps the public label, the resolved version and the
+                    // payload's SHA256. No remote path and no mapping are written: both
+                    // would expose a name the module hides.
+                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                    const replacement = { module: plan.module, plugin: label, version: plan.replacement.version, name: label };
+                    const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
+                    if (index < 0)
+                        nextArtifacts.push(replacement);
+                    else
+                        nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
+                    for (const file of plan.replacement.files) {
+                        const download = { plugin: label, version: plan.replacement.version, name: label, sha256: file.sha256 };
+                        const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === label);
+                        if (downloadIndex < 0)
+                            nextDownloads.push(download);
+                        else
+                            nextDownloads[downloadIndex] = download;
+                    }
+                    requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
+                    delete moduleSources[plan.module];
+                }
                 if (plan.local)
                     moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
                 // First installing a module records it the way `create-env` would: a
@@ -1097,6 +1282,8 @@ class EnvironmentUpdater {
             }
             if (autoRefreshed.length)
                 warnings.push(`${autoRefreshed.join(', ')} was refreshed with the Server package: its trees live inside the Server directory and would otherwise be lost.`);
+            if (autoReplaced.length)
+                warnings.push(`${autoReplaced.join(', ')} was re-applied with the Server package: the new package ships the file it replaces, so it was applied again.`);
             if (removedCreateOnly.length)
                 warnings.push(`${removedCreateOnly.join(', ')} was removed with the Server package: it is deployed only when an environment is created.`);
             if (!dryRun) {
@@ -1121,6 +1308,25 @@ class EnvironmentUpdater {
                         await (0, builder_1.copyTree)(copy.source, copy.destination, copy.exclude);
                     for (const file of plan.preserved)
                         await fs.copyFile(file.source, path.join(file.directory, file.name));
+                    // The replacement is applied after the directory it lives in has been
+                    // copied, so a Server refresh cannot overwrite it again. The target is
+                    // re-checked here and every error names the module only.
+                    if (plan.replacement) {
+                        const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                        try {
+                            for (const file of plan.replacement.files) {
+                                const stat = await fs.lstat(file.destination).catch(() => undefined);
+                                if (!stat)
+                                    throw new Error('missing');
+                                if (!stat.isFile() || stat.isSymbolicLink())
+                                    throw new Error('not a regular file');
+                                await fs.copyFile(file.source, file.destination);
+                            }
+                        }
+                        catch {
+                            throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                        }
+                    }
                     if (plan.configurationAssets) {
                         onProgress?.(`Refreshing Monitor configuration assets in ${path.relative(entry.root, plan.configurationAssets.destination)}`);
                         await mergeConfigurationAssets(plan.configurationAssets.source, plan.configurationAssets.destination);
@@ -1129,9 +1335,10 @@ class EnvironmentUpdater {
                         await fs.symlink(path.join(entry.root, 'conf'), plan.configurationLink, 'junction');
                 }
                 // Only a plan that really contributes something to the configuration
-                // rewrites it: the built-in dashboard-resource module adds no plugin,
-                // worker or service entry, so refreshing it alone leaves `conf/Wyn.conf`
-                // exactly as it is instead of round-tripping it through the XML builder.
+                // rewrites it: a module that adds no plugin, worker or service entry
+                // leaves `conf/Wyn.conf` exactly as it is instead of round-tripping it
+                // through the XML builder. (The built-in modules are create-only, so an
+                // update never plans one.)
                 const configurationChanged = plans.some(plan => plan.entries.length > 0 || plan.configurationAssets !== undefined || plan.configurationLink !== undefined);
                 onProgress?.(configurationChanged ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
                 if (configurationChanged)