@_linked/server 3.6.0 → 3.6.1

package/lib/esm/utils/adminChannel.d.ts

@@ -7,7 +7,22 @@ export interface ShapeSyncResult {
     orphanScope?: 'all' | 'none';
     /** Set when no sync ran: shape sync is turned off, or there is no default dataset. */
     skipped?: 'disabled' | 'no-default-dataset';
+    /**
+     * The requested packages whose source was reloaded before the sync (dev only: a built
+     * app reloads nothing). Set by `POST /admin/sync-shapes`.
+     */
+    reloaded?: string[];
+    /** The node shape IRIs registered in the process after the reload. Set by `POST /admin/sync-shapes`. */
+    shapes?: string[];
 }
+/** Whether `name` is a valid npm package name (and so can never be a path like `..`). */
+export declare function isValidPackageName(name: string): boolean;
+/**
+ * Refuse a package a host may not ask to reload: not a valid npm name, a framework
+ * (`@_linked/*`) package, or not in `allowed` (the app's own name and its direct
+ * dependencies). Throws {@link AdminRequestError}.
+ */
+export declare function assertReloadablePackages(packages: string[], allowed: ReadonlySet<string>): void;
 /** Thrown by a handler for a request the channel refuses with 400. */
 export declare class AdminRequestError extends Error {
 }

package/lib/esm/utils/adminChannel.js

@@ -11,10 +11,34 @@
  * - `POST /admin/sync-shapes` → re-syncs the app's shapes into its app data, as
  *   the boot does, and answers 200 with {@link ShapeSyncResult}. Body (optional):
  *   `{packages: string[]}`, packages whose source changed on disk: in dev they are
- *   reloaded first, so the sync sees shapes added or changed since the boot. A
- *   failed sync answers 500 `{error}`; an unknown package 400 `{error}`.
+ *   reloaded first, so the sync sees shapes added or changed since the boot. Each
+ *   name must be a valid npm package name and the app itself or one of its direct
+ *   dependencies, never an `@_linked/*` framework package; anything else answers
+ *   400 `{error}`. A failed or timed-out sync answers 500 `{error}`.
  */
 import { timingSafeEqual } from 'crypto';
+/** npm's package-name rule: optional `@scope/`, lower case, URL-safe, no leading `.` or `_` (a scope may start with `_`, as `@_linked` does). */
+const NPM_NAME = /^(?:@[a-z0-9-~_][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/** Whether `name` is a valid npm package name (and so can never be a path like `..`). */
+export function isValidPackageName(name) {
+    return name.length <= 214 && NPM_NAME.test(name) && !name.split('/').some((part) => part === '.' || part === '..');
+}
+/**
+ * Refuse a package a host may not ask to reload: not a valid npm name, a framework
+ * (`@_linked/*`) package, or not in `allowed` (the app's own name and its direct
+ * dependencies). Throws {@link AdminRequestError}.
+ */
+export function assertReloadablePackages(packages, allowed) {
+    for (const pkg of packages) {
+        if (!isValidPackageName(pkg))
+            throw new AdminRequestError(`not a package name: ${JSON.stringify(pkg)}`);
+        if (pkg.startsWith('@_linked/'))
+            throw new AdminRequestError(`framework packages are not reloaded: ${pkg}`);
+        if (!allowed.has(pkg)) {
+            throw new AdminRequestError(`unknown package: ${pkg} is neither the app nor one of its direct dependencies`);
+        }
+    }
+}
 /** Thrown by a handler for a request the channel refuses with 400. */
 export class AdminRequestError extends Error {
 }
@@ -39,6 +63,10 @@ export function parseSyncShapesBody(body) {
     if (!Array.isArray(packages) || packages.some((p) => typeof p !== 'string' || !p)) {
         throw new AdminRequestError('packages must be a list of package names');
     }
+    for (const p of packages) {
+        if (!isValidPackageName(p))
+            throw new AdminRequestError(`not a package name: ${JSON.stringify(p)}`);
+    }
     return { packages: [...new Set(packages)] };
 }
 /** Mount the control channel's routes on `app`. */

package/lib/esm/utils/adminChannel.js.map

@@ -1 +1 @@
-{"version":3,"file":"adminChannel.js","sourceRoot":"","sources":["../../../src/utils/adminChannel.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The host→app control channel: `/admin/*` routes a host (Create Now) uses on an\n * app process it started. Present only when the process was started with a\n * shared secret in `CN_APP_ADMIN_SECRET`; without it every route answers 404, so\n * a standalone app has no control channel. Every request carries the secret in\n * the `x-cn-admin-secret` header.\n *\n * - `GET /admin/health` → 200 `{status: 'ok'}` once the server listens (the boot\n *   shape sync has finished by then).\n * - `POST /admin/restart` → 202, then the process exits; the host starts it again.\n * - `POST /admin/sync-shapes` → re-syncs the app's shapes into its app data, as\n *   the boot does, and answers 200 with {@link ShapeSyncResult}. Body (optional):\n *   `{packages: string[]}`, packages whose source changed on disk: in dev they are\n *   reloaded first, so the sync sees shapes added or changed since the boot. A\n *   failed sync answers 500 `{error}`; an unknown package 400 `{error}`.\n */\nimport { timingSafeEqual } from 'crypto';\nimport type express from 'express';\n\n/** What one shape sync did. */\nexport interface ShapeSyncResult {\n  /** Shapes written: those whose stored hash differed from the registered shape. */\n  written: number;\n  /** The orphan policy the sync ran with (see utils/syncShapes). */\n  orphanScope?: 'all' | 'none';\n  /** Set when no sync ran: shape sync is turned off, or there is no default dataset. */\n  skipped?: 'disabled' | 'no-default-dataset';\n}\n\n/** Thrown by a handler for a request the channel refuses with 400. */\nexport class AdminRequestError extends Error {}\n\nexport interface AdminChannelHandlers {\n  /** Exit the process (the host restarts it). Called after the 202 is sent. */\n  exit: () => void;\n  /** Reload `packages` (when given) and sync the registered shapes into app data. */\n  syncShapes: (request: { packages: string[] }) => Promise<ShapeSyncResult>;\n}\n\n/** Compare the provided secret with the configured one in constant time. */\nexport function adminSecretMatches(\n  secret: string | undefined,\n  provided: string | undefined\n): boolean {\n  if (!secret || !provided) return false;\n  const a = Buffer.from(provided);\n  const b = Buffer.from(secret);\n  return a.length === b.length && timingSafeEqual(a, b);\n}\n\n/** The `packages` of a sync-shapes body: a list of package names, or none. */\nexport function parseSyncShapesBody(body: unknown): { packages: string[] } {\n  if (body === undefined || body === null || body === '') return { packages: [] };\n  if (typeof body !== 'object') {\n    throw new AdminRequestError('the body must be a JSON object');\n  }\n  const packages = (body as { packages?: unknown }).packages;\n  if (packages === undefined) return { packages: [] };\n  if (!Array.isArray(packages) || packages.some((p) => typeof p !== 'string' || !p)) {\n    throw new AdminRequestError('packages must be a list of package names');\n  }\n  return { packages: [...new Set(packages as string[])] };\n}\n\n/** Mount the control channel's routes on `app`. */\nexport function registerAdminRoutes(\n  app: express.Express,\n  secret: string | undefined,\n  handlers: AdminChannelHandlers\n): void {\n  const requireAdmin = (req: express.Request, res: express.Response): boolean => {\n    if (!secret) {\n      res.sendStatus(404); // no control channel in this mode\n      return false;\n    }\n    if (!adminSecretMatches(secret, req.get('x-cn-admin-secret'))) {\n      res.sendStatus(401);\n      return false;\n    }\n    return true;\n  };\n\n  app.get('/admin/health', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    res.status(200).json({ status: 'ok' });\n  });\n\n  app.post('/admin/restart', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    res.sendStatus(202);\n    setTimeout(handlers.exit, 50);\n  });\n\n  app.post('/admin/sync-shapes', async (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    let request: { packages: string[] };\n    try {\n      request = parseSyncShapesBody(req.body);\n    } catch (err) {\n      res.status(400).json({ error: (err as Error).message });\n      return;\n    }\n    try {\n      res.status(200).json(await handlers.syncShapes(request));\n    } catch (err) {\n      const status = err instanceof AdminRequestError ? 400 : 500;\n      res.status(status).json({ error: err instanceof Error ? err.message : String(err) });\n    }\n  });\n}\n"]}
+{"version":3,"file":"adminChannel.js","sourceRoot":"","sources":["../../../src/utils/adminChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAoBzC,iJAAiJ;AACjJ,MAAM,QAAQ,GAAG,2DAA2D,CAAC;AAE7E,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC;AACrH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAkB,EAAE,OAA4B;IACvF,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,iBAAiB,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxG,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,MAAM,IAAI,iBAAiB,CAAC,wCAAwC,GAAG,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,iBAAiB,CAAC,oBAAoB,GAAG,wDAAwD,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;CAAG;AAS/C,4EAA4E;AAC5E,MAAM,UAAU,kBAAkB,CAChC,MAA0B,EAC1B,QAA4B;IAE5B,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAChF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,iBAAiB,CAAC,gCAAgC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,QAAQ,GAAI,IAA+B,CAAC,QAAQ,CAAC;IAC3D,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,iBAAiB,CAAC,0CAA0C,CAAC,CAAC;IAC1E,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,QAAoB,EAAE,CAAC;QACrC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,iBAAiB,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAoB,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,mBAAmB,CACjC,GAAoB,EACpB,MAA0B,EAC1B,QAA8B;IAE9B,MAAM,YAAY,GAAG,CAAC,GAAoB,EAAE,GAAqB,EAAW,EAAE;QAC5E,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,kCAAkC;YACvD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACpC,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QACpC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACtC,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QACpC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACpB,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAChD,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QACpC,IAAI,OAA+B,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAC5D,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * The host→app control channel: `/admin/*` routes a host (Create Now) uses on an\n * app process it started. Present only when the process was started with a\n * shared secret in `CN_APP_ADMIN_SECRET`; without it every route answers 404, so\n * a standalone app has no control channel. Every request carries the secret in\n * the `x-cn-admin-secret` header.\n *\n * - `GET /admin/health` → 200 `{status: 'ok'}` once the server listens (the boot\n *   shape sync has finished by then).\n * - `POST /admin/restart` → 202, then the process exits; the host starts it again.\n * - `POST /admin/sync-shapes` → re-syncs the app's shapes into its app data, as\n *   the boot does, and answers 200 with {@link ShapeSyncResult}. Body (optional):\n *   `{packages: string[]}`, packages whose source changed on disk: in dev they are\n *   reloaded first, so the sync sees shapes added or changed since the boot. Each\n *   name must be a valid npm package name and the app itself or one of its direct\n *   dependencies, never an `@_linked/*` framework package; anything else answers\n *   400 `{error}`. A failed or timed-out sync answers 500 `{error}`.\n */\nimport { timingSafeEqual } from 'crypto';\nimport type express from 'express';\n\n/** What one shape sync did. */\nexport interface ShapeSyncResult {\n  /** Shapes written: those whose stored hash differed from the registered shape. */\n  written: number;\n  /** The orphan policy the sync ran with (see utils/syncShapes). */\n  orphanScope?: 'all' | 'none';\n  /** Set when no sync ran: shape sync is turned off, or there is no default dataset. */\n  skipped?: 'disabled' | 'no-default-dataset';\n  /**\n   * The requested packages whose source was reloaded before the sync (dev only: a built\n   * app reloads nothing). Set by `POST /admin/sync-shapes`.\n   */\n  reloaded?: string[];\n  /** The node shape IRIs registered in the process after the reload. Set by `POST /admin/sync-shapes`. */\n  shapes?: string[];\n}\n\n/** npm's package-name rule: optional `@scope/`, lower case, URL-safe, no leading `.` or `_` (a scope may start with `_`, as `@_linked` does). */\nconst NPM_NAME = /^(?:@[a-z0-9-~_][a-z0-9-._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$/;\n\n/** Whether `name` is a valid npm package name (and so can never be a path like `..`). */\nexport function isValidPackageName(name: string): boolean {\n  return name.length <= 214 && NPM_NAME.test(name) && !name.split('/').some((part) => part === '.' || part === '..');\n}\n\n/**\n * Refuse a package a host may not ask to reload: not a valid npm name, a framework\n * (`@_linked/*`) package, or not in `allowed` (the app's own name and its direct\n * dependencies). Throws {@link AdminRequestError}.\n */\nexport function assertReloadablePackages(packages: string[], allowed: ReadonlySet<string>): void {\n  for (const pkg of packages) {\n    if (!isValidPackageName(pkg)) throw new AdminRequestError(`not a package name: ${JSON.stringify(pkg)}`);\n    if (pkg.startsWith('@_linked/')) throw new AdminRequestError(`framework packages are not reloaded: ${pkg}`);\n    if (!allowed.has(pkg)) {\n      throw new AdminRequestError(`unknown package: ${pkg} is neither the app nor one of its direct dependencies`);\n    }\n  }\n}\n\n/** Thrown by a handler for a request the channel refuses with 400. */\nexport class AdminRequestError extends Error {}\n\nexport interface AdminChannelHandlers {\n  /** Exit the process (the host restarts it). Called after the 202 is sent. */\n  exit: () => void;\n  /** Reload `packages` (when given) and sync the registered shapes into app data. */\n  syncShapes: (request: { packages: string[] }) => Promise<ShapeSyncResult>;\n}\n\n/** Compare the provided secret with the configured one in constant time. */\nexport function adminSecretMatches(\n  secret: string | undefined,\n  provided: string | undefined\n): boolean {\n  if (!secret || !provided) return false;\n  const a = Buffer.from(provided);\n  const b = Buffer.from(secret);\n  return a.length === b.length && timingSafeEqual(a, b);\n}\n\n/** The `packages` of a sync-shapes body: a list of package names, or none. */\nexport function parseSyncShapesBody(body: unknown): { packages: string[] } {\n  if (body === undefined || body === null || body === '') return { packages: [] };\n  if (typeof body !== 'object') {\n    throw new AdminRequestError('the body must be a JSON object');\n  }\n  const packages = (body as { packages?: unknown }).packages;\n  if (packages === undefined) return { packages: [] };\n  if (!Array.isArray(packages) || packages.some((p) => typeof p !== 'string' || !p)) {\n    throw new AdminRequestError('packages must be a list of package names');\n  }\n  for (const p of packages as string[]) {\n    if (!isValidPackageName(p)) throw new AdminRequestError(`not a package name: ${JSON.stringify(p)}`);\n  }\n  return { packages: [...new Set(packages as string[])] };\n}\n\n/** Mount the control channel's routes on `app`. */\nexport function registerAdminRoutes(\n  app: express.Express,\n  secret: string | undefined,\n  handlers: AdminChannelHandlers\n): void {\n  const requireAdmin = (req: express.Request, res: express.Response): boolean => {\n    if (!secret) {\n      res.sendStatus(404); // no control channel in this mode\n      return false;\n    }\n    if (!adminSecretMatches(secret, req.get('x-cn-admin-secret'))) {\n      res.sendStatus(401);\n      return false;\n    }\n    return true;\n  };\n\n  app.get('/admin/health', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    res.status(200).json({ status: 'ok' });\n  });\n\n  app.post('/admin/restart', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    res.sendStatus(202);\n    setTimeout(handlers.exit, 50);\n  });\n\n  app.post('/admin/sync-shapes', async (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    let request: { packages: string[] };\n    try {\n      request = parseSyncShapesBody(req.body);\n    } catch (err) {\n      res.status(400).json({ error: (err as Error).message });\n      return;\n    }\n    try {\n      res.status(200).json(await handlers.syncShapes(request));\n    } catch (err) {\n      const status = err instanceof AdminRequestError ? 400 : 500;\n      res.status(status).json({ error: err instanceof Error ? err.message : String(err) });\n    }\n  });\n}\n"]}

package/lib/esm/utils/withTimeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Settle with `promise`, or reject with `message` after `ms`. The operation is not
+ * cancelled; the timeout only stops a caller (or a queue) from waiting on it forever.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;
+/** A positive integer from the environment, else `fallback`. */
+export declare function envMs(name: string, fallback: number, env?: Record<string, string | undefined>): number;

package/lib/esm/utils/withTimeout.js

@@ -0,0 +1,17 @@
+/**
+ * Settle with `promise`, or reject with `message` after `ms`. The operation is not
+ * cancelled; the timeout only stops a caller (or a queue) from waiting on it forever.
+ */
+export function withTimeout(promise, ms, message) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/** A positive integer from the environment, else `fallback`. */
+export function envMs(name, fallback, env = process.env) {
+    const n = Number(env[name]);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+//# sourceMappingURL=withTimeout.js.map

package/lib/esm/utils/withTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTimeout.js","sourceRoot":"","sources":["../../../src/utils/withTimeout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAI,OAAmB,EAAE,EAAU,EAAE,OAAe;IAC7E,IAAI,KAAgD,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC/C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,QAAgB,EAAE,MAA0C,OAAO,CAAC,GAAG;IACzG,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpD,CAAC","sourcesContent":["/**\n * Settle with `promise`, or reject with `message` after `ms`. The operation is not\n * cancelled; the timeout only stops a caller (or a queue) from waiting on it forever.\n */\nexport function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const timeout = new Promise<never>((_, reject) => {\n    timer = setTimeout(() => reject(new Error(message)), ms);\n  });\n  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));\n}\n\n/** A positive integer from the environment, else `fallback`. */\nexport function envMs(name: string, fallback: number, env: Record<string, string | undefined> = process.env): number {\n  const n = Number(env[name]);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n"]}

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "3.6.0",
+  "version": "3.6.1",
   "packageManager": "npm@12.2.0",
   "linkedPackage": true,
   "type": "module",

package/readme.md

@@ -26,6 +26,7 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [`ping`](#ping)
   - [Shape catalog per request](#shape-catalog-per-request)
 - [API-only servers (`server.apiOnly`)](#api-only-servers-serverapionly)
+- [Host control channel (`/admin/*`)](#host-control-channel-admin)
 - [Provider lifecycle and HMR](#provider-lifecycle-and-hmr)
   - [When a provider throws, and refusing to start](#when-a-provider-throws-and-refusing-to-start)
   - [When to implement `dispose()`](#when-to-implement-dispose)
@@ -402,6 +403,24 @@ new LinkedServer({
 
 With `apiOnly` the server skips page rendering. It installs no SPA catch-all, so a `GET` for a page that no route handles gets express's plain `404` instead of the app shell. The `/call/...` and `/api/...` routes and the routes that providers register work as usual.
 
+## Host control channel (`/admin/*`)
+
+A host that starts the app process (Create Now) controls it over HTTP routes on the app's own port. They exist only when the process was started with `CN_APP_ADMIN_SECRET` in its environment; without it they answer 404. Every request carries the secret in `x-cn-admin-secret` (401 otherwise).
+
+| Route | Answer |
+|---|---|
+| `GET /admin/health` | 200 `{status: 'ok'}` once the server listens (the boot shape sync has finished by then) |
+| `POST /admin/restart` | 202, then the process exits; the host starts it again |
+| `POST /admin/sync-shapes` | 200 `{written, orphanScope, reloaded, shapes}` (or `{written: 0, skipped, …}` when shape sync is off); 400 `{error}` for a malformed body or a package it may not reload; 500 `{error}` when the sync fails or times out |
+
+`POST /admin/sync-shapes` re-syncs the registered shapes into the app's data exactly as the boot does (core `syncShapes`: only shapes whose stored `core:shapeHash` differs are written, with the boot's orphan policy and `syncShapesOnBoot` / `LINKED_SYNC_SHAPES_ON_BOOT` switches). The optional body `{packages: [...]}` names packages whose source the host changed; each must be a valid npm package name and the app itself or one of its direct dependencies, never an `@_linked/*` package. In dev their modules are invalidated in Vite and their backends reloaded before the sync, so a shape file written a moment ago is registered; a built app reloads nothing. `reloaded` lists the packages actually reloaded and `shapes` the node shape IRIs registered afterwards, so the host can check that the shape it wrote is there. Syncs run one at a time, as the system; one that takes longer than `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120000) fails and releases the queue. A source reload by itself (HMR) never syncs shapes.
+
+Side effects to expect:
+
+- **A reload briefly disposes the package's providers.** Reloading a package (on HMR, or for `sync-shapes`) runs `dispose()` on its providers and constructs new ones; a request to that package's routes or methods that arrives in between can fail. Reloads run one at a time; one that takes longer than `LINKED_SOURCE_RELOAD_TIMEOUT_MS` (default 60000) rejects and releases the queue.
+- **A restart drops in-flight requests.** `POST /admin/restart` exits the process 50 ms after answering. A host that restarts an app whose server has no `sync-shapes` route (an older `@_linked/server`) to make its boot sync the shapes drops whatever that app was serving.
+- The channel listens on the app's public port, like every other route; only the secret protects it.
+
 ## Provider lifecycle and HMR
 
 Every provider — generic (`BackendProvider`) or shape-scoped (`ShapeProvider`) — has a lifecycle the framework drives: