@_linked/server 3.6.0 → 3.6.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @\_linked/server
 
+## 3.6.1
+
+### Patch Changes
+
+- [#200](https://github.com/linked-fw/server/pull/200) [`935d0ca`](https://github.com/linked-fw/server/commit/935d0caf014cae8c71ae3b40963305ac8d43792c) Thanks [@flyon](https://github.com/flyon)! - `POST /admin/sync-shapes` now answers which packages it reloaded (`reloaded`) and the node shapes registered afterwards (`shapes`), refuses (400) package names that are not valid npm names, `@_linked/*` packages, or neither the app nor one of its direct dependencies, and times out a hung sync (`LINKED_SHAPE_SYNC_TIMEOUT_MS`, default 120 s) or source reload (`LINKED_SOURCE_RELOAD_TIMEOUT_MS`, default 60 s) so the queue is released. The README documents the control channel and the side effects of a reload and a restart.
+
 ## 3.6.0
 
 ### Minor Changes

package/lib/esm/shapes/LinkedServer.d.ts

@@ -135,16 +135,25 @@ export declare class LinkedServer extends Shape {
      * changed the app's shape code, so the app — the only process that loads that
      * code — writes its own shapes and their hashes.
      *
-     * `packages` names the packages whose source changed. In dev (Vite) their
-     * modules are invalidated and their backends reloaded first
-     * ({@link onSourceChange}), so a shape added since the boot is registered
-     * before the sync; without Vite (a built app) the sync covers the shapes the
-     * process loaded. Runs as the system, never as the caller of a request.
+     * `packages` names the packages whose source changed: the app itself or its
+     * direct dependencies, never `@_linked/*` ({@link assertReloadablePackages}). In
+     * dev (Vite) their modules are invalidated and their backends reloaded first
+     * ({@link onSourceChange}), so a shape added since the boot is registered before
+     * the sync; without Vite (a built app) nothing is reloaded. The answer names the
+     * packages reloaded and the node shapes registered after it, so the host can check
+     * that the shape it wrote is there. Runs as the system, never as the caller of a
+     * request, one at a time; a run that takes longer than
+     * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) fails and releases the queue.
      */
     resyncShapes({ packages }?: {
         packages?: string[];
     }): Promise<ShapeSyncResult>;
-    /** Re-read one package's source from disk (dev only); see {@link resyncShapes}. */
+    /** The packages a host may ask to reload: the app itself and its direct dependencies. */
+    private reloadablePackages;
+    /**
+     * Re-read one package's source from disk (dev only); see {@link resyncShapes}.
+     * Resolves whether it reloaded anything.
+     */
     private reloadPackageFromDisk;
     /**
      * Boot the server and listen. Rejects — and makes the process exit non-zero —
@@ -257,7 +266,8 @@ export declare class LinkedServer extends Shape {
      * don't accumulate), drops them from the registry, and re-runs
      * indexPackageBackendProviders to pick up the freshly-imported module.
      * Reloads run one at a time: each re-registers routes on the shared express
-     * stack.
+     * stack. One that takes longer than `LINKED_SOURCE_RELOAD_TIMEOUT_MS` (default
+     * 60 s) rejects and releases the queue.
      *
      * Dispose calls have a 5 s soft timeout. A hanging dispose logs a
      * warning and is abandoned so HMR doesn't stall the whole dev loop.

package/lib/esm/shapes/LinkedServer.js

@@ -37,7 +37,7 @@ import { nativeImport } from '../utils/nativeImport.js';
 import { createJsonBodyParser } from '../utils/jsonBodyParser.js';
 import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
 import { autoLoadOntologyData } from '@_linked/core/utils/Package';
-import { getShapeClass, getSuperShapesClasses, } from '@_linked/core/utils/ShapeClass';
+import { getAllShapeClasses, getShapeClass, getSuperShapesClasses, } from '@_linked/core/utils/ShapeClass';
 import path from 'path';
 import { pathToFileURL } from 'node:url';
 import { isFatalError } from '../utils/fatalError.js';
@@ -139,7 +139,8 @@ import { resolveBootstrapEntry, resolveViteMainEntry, resolveViteServingMode, }
 import { resolveRouteAssets } from '../utils/routeAssets.js';
 import { resolveRouteComponent, ssrCssInlineUrls, ssrCssScope, } from '../utils/ssrCss.js';
 import { materializeShapes } from '../utils/syncShapes.js';
-import { AdminRequestError, registerAdminRoutes, } from '../utils/adminChannel.js';
+import { AdminRequestError, assertReloadablePackages, registerAdminRoutes, } from '../utils/adminChannel.js';
+import { envMs, withTimeout } from '../utils/withTimeout.js';
 import { invalidateSourceUnder } from '../utils/reloadSource.js';
 import { installSpaFallback, repinSpaFallback, } from '../utils/spaFallback.js';
 import { LincdAPI } from './LincdAPI.js';
@@ -415,22 +416,53 @@ let LinkedServer = class LinkedServer extends Shape {
      * changed the app's shape code, so the app — the only process that loads that
      * code — writes its own shapes and their hashes.
      *
-     * `packages` names the packages whose source changed. In dev (Vite) their
-     * modules are invalidated and their backends reloaded first
-     * ({@link onSourceChange}), so a shape added since the boot is registered
-     * before the sync; without Vite (a built app) the sync covers the shapes the
-     * process loaded. Runs as the system, never as the caller of a request.
+     * `packages` names the packages whose source changed: the app itself or its
+     * direct dependencies, never `@_linked/*` ({@link assertReloadablePackages}). In
+     * dev (Vite) their modules are invalidated and their backends reloaded first
+     * ({@link onSourceChange}), so a shape added since the boot is registered before
+     * the sync; without Vite (a built app) nothing is reloaded. The answer names the
+     * packages reloaded and the node shapes registered after it, so the host can check
+     * that the shape it wrote is there. Runs as the system, never as the caller of a
+     * request, one at a time; a run that takes longer than
+     * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) fails and releases the queue.
      */
     async resyncShapes({ packages = [] } = {}) {
-        const run = this.shapeSyncQueue.then(() => runAsSystem(async () => {
-            for (const pkg of packages)
-                await this.reloadPackageFromDisk(pkg);
-            return this.syncRegisteredShapes();
-        }, 'shape sync requested by the host'));
+        assertReloadablePackages(packages, this.reloadablePackages());
+        const timeoutMs = envMs('LINKED_SHAPE_SYNC_TIMEOUT_MS', 120000);
+        const run = this.shapeSyncQueue.then(() => withTimeout(runAsSystem(async () => {
+            const reloaded = [];
+            for (const pkg of packages) {
+                if (await this.reloadPackageFromDisk(pkg))
+                    reloaded.push(pkg);
+            }
+            const result = await this.syncRegisteredShapes();
+            return { ...result, reloaded, shapes: [...getAllShapeClasses().keys()].sort() };
+        }, 'shape sync requested by the host'), timeoutMs, `the shape sync did not finish within ${timeoutMs} ms`));
         this.shapeSyncQueue = run.catch(() => undefined);
         return run;
     }
-    /** Re-read one package's source from disk (dev only); see {@link resyncShapes}. */
+    /** The packages a host may ask to reload: the app itself and its direct dependencies. */
+    reloadablePackages() {
+        var _a, _b;
+        const names = new Set();
+        if ((_a = this.package) === null || _a === void 0 ? void 0 : _a.name)
+            names.add(this.package.name);
+        try {
+            const json = JSON.parse(fsNative.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+            if (json.name)
+                names.add(json.name);
+            for (const field of ['dependencies', 'devDependencies']) {
+                for (const name of Object.keys((_b = json[field]) !== null && _b !== void 0 ? _b : {}))
+                    names.add(name);
+            }
+        }
+        catch (_c) { }
+        return names;
+    }
+    /**
+     * Re-read one package's source from disk (dev only); see {@link resyncShapes}.
+     * Resolves whether it reloaded anything.
+     */
     async reloadPackageFromDisk(pkg) {
         var _a, _b, _c;
         const root = pkg === ((_a = this.package) === null || _a === void 0 ? void 0 : _a.name) ? process.cwd() : this.packageDirFor(pkg);
@@ -438,7 +470,7 @@ let LinkedServer = class LinkedServer extends Shape {
             throw new AdminRequestError(`unknown package: ${pkg}`);
         const graph = (_c = (_b = this.config.server) === null || _b === void 0 ? void 0 : _b.vite) === null || _c === void 0 ? void 0 : _c.moduleGraph;
         if (!graph)
-            return; // a built app: there is no source to reload
+            return false; // a built app: there is no source to reload
         const roots = [root];
         try {
             roots.push(fsNative.realpathSync(root));
@@ -446,6 +478,7 @@ let LinkedServer = class LinkedServer extends Shape {
         catch (_d) { }
         invalidateSourceUnder(graph, roots);
         await this.onSourceChange(pkg);
+        return true;
     }
     // async serveData(req,res) {
     //   let nodeURI = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
@@ -1416,13 +1449,15 @@ let LinkedServer = class LinkedServer extends Shape {
      * don't accumulate), drops them from the registry, and re-runs
      * indexPackageBackendProviders to pick up the freshly-imported module.
      * Reloads run one at a time: each re-registers routes on the shared express
-     * stack.
+     * stack. One that takes longer than `LINKED_SOURCE_RELOAD_TIMEOUT_MS` (default
+     * 60 s) rejects and releases the queue.
      *
      * Dispose calls have a 5 s soft timeout. A hanging dispose logs a
      * warning and is abandoned so HMR doesn't stall the whole dev loop.
      */
     async onSourceChange(pkg) {
-        const run = this.sourceReloadQueue.then(() => this.reloadPackageSource(pkg));
+        const timeoutMs = envMs('LINKED_SOURCE_RELOAD_TIMEOUT_MS', 60000);
+        const run = this.sourceReloadQueue.then(() => withTimeout(this.reloadPackageSource(pkg), timeoutMs, `the reload of ${pkg} did not finish within ${timeoutMs} ms`));
         this.sourceReloadQueue = run.catch(() => undefined);
         return run;
     }