@_linked/server 3.12.1 → 3.14.0

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

@@ -1,5 +1,6 @@
 import type express from 'express';
-import type { ShapeGraphsReport } from './syncShapes.js';
+import type { GraphContents } from './syncShapes.js';
+import type { GraphTargets } from '@_linked/core/utils/graphTargets';
 import { type EffectiveRoutes } from './effectiveRoutes.js';
 /** The environment variable that holds the control channel's secret. */
 export declare const ADMIN_SECRET_ENV = "APP_ADMIN_SECRET";
@@ -7,65 +8,35 @@ export declare const ADMIN_SECRET_ENV = "APP_ADMIN_SECRET";
 export declare const ADMIN_SECRET_HEADER = "x-app-admin-secret";
 /** The control channel's secret: `APP_ADMIN_SECRET`, else `undefined` (no control channel). */
 export declare function resolveAdminSecret(env?: Record<string, string | undefined>): string | undefined;
-/** What one shape sync did. */
-export interface ShapeSyncResult {
-    /**
-     * Shape graphs written (package graphs and the app's own graph) because their stored hash
-     * differed; on a store without graph queries, the default-graph sync's writes.
-     */
-    written: number;
-    /** The orphan policy the sync ran with (see utils/syncShapes). */
-    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 shape graph sync: packages written and skipped, the graphs written, the app's own shape
-     * graph, the registered packages without `shapes.ttl` (so without a shape graph) and the
-     * default-graph shapes removed. Absent when no sync ran.
-     */
-    shapeGraphs?: ShapeGraphsReport;
-    /**
-     * 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[];
-    /**
-     * The ontology sync: packages whose ontology graph (or, on a store without graph queries,
-     * class hierarchy) was written, packages left as they were (unchanged, or their data could not
-     * be read), and the graphs written and dropped. Set by `POST /admin/sync-shapes`.
-     */
-    ontologies?: {
-        written: string[];
-        skipped: string[];
-        graphs?: string[];
-        droppedGraphs?: string[];
-    };
-    /** The shape check's findings, counted by severity (each is logged). Set by `POST /admin/sync-shapes`. */
-    shapeCheck?: {
-        errors: number;
-        warnings: number;
-    };
-}
 /** 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}.
+ * dependencies, its `linked.unpublishedPackages` among them). 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 {
 }
+/** Thrown by a handler for a request that conflicts with how the process runs: answered 409. */
+export declare class AdminConflictError extends Error {
+}
+/** The answer of `POST /admin/graph-content`. */
+export interface GraphContentAnswer extends GraphContents {
+    /** The process's graph targets (both `'package'`, or the route answers 409). */
+    graphTargets: GraphTargets;
+    /** The requested packages whose source was reloaded first (dev only). */
+    reloaded: string[];
+}
+/** The body of a graph-content request: `packages` limits the answer, `reload` is reloaded first. */
+export declare function parseGraphContentBody(body: unknown): {
+    packages?: string[];
+    reload: string[];
+};
 export interface AdminChannelHandlers {
     /** Exit the process (the host restarts it). Called after the 202 is sent. */
     exit: () => void;
-    /** Reload `packages` (when given) and sync the registered shapes into app data. */
-    syncShapes: (request: {
-        packages: string[];
-    }) => Promise<ShapeSyncResult>;
     /**
      * Drop the cached graph registry for `dataset` (see `POST /admin/graph-registry-changed`).
      * Default: {@link dropGraphRegistryCache}.
@@ -73,6 +44,11 @@ export interface AdminChannelHandlers {
     graphRegistryChanged?: (dataset: string) => void;
     /** The effective graph routes (see `GET /admin/routes`). Default: {@link effectiveGraphRoutes}. */
     routes?: () => EffectiveRoutes;
+    /** Reload `reload`, then answer the content of the app's graphs (see `POST /admin/graph-content`); without it the route answers 404. */
+    graphContent?: (request: {
+        packages?: string[];
+        reload: string[];
+    }) => Promise<GraphContentAnswer>;
 }
 /**
  * Drop the process's cached graph registry after the host changed the graphs of `dataset`.
@@ -93,9 +69,5 @@ export declare function parseGraphRegistryChangedBody(body: unknown): {
  * first, so the comparison does not reveal the secret's length either.
  */
 export declare function adminSecretMatches(secret: string | undefined, provided: string | undefined): boolean;
-/** The `packages` of a sync-shapes body: a list of package names, or none. */
-export declare function parseSyncShapesBody(body: unknown): {
-    packages: string[];
-};
 /** Mount the control channel's routes on `app`. */
 export declare function registerAdminRoutes(app: express.Express, secret: string | undefined, handlers: AdminChannelHandlers): void;

package/lib/esm/utils/adminChannel.js

@@ -5,25 +5,26 @@
  * 404, so a standalone app has no control channel. Every request carries the secret in
  * the `x-app-admin-secret` header (401 otherwise).
  *
- * - `GET /admin/health` → 200 `{status: 'ok'}` once the server listens (the boot
- *   shape sync has finished by then).
+ * - `GET /admin/health` → 200 `{status: 'ok'}` once the server listens (a boot sync, when
+ *   the app writes its own graphs, has finished by then).
  * - `POST /admin/restart` → 202, then the process exits; the host starts it again.
- * - `POST /admin/sync-shapes` → re-syncs the app's ontologies (each registered package's
- *   ontology graph, skipped when unchanged), runs the shape check and
- *   re-syncs its shapes into its app data (each package's shape graph and the app's own,
- *   skipped when unchanged), as the boot does, and answers 200 with
- *   {@link ShapeSyncResult}, whose `shapeGraphs` reports the shape graphs. 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. 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}`. The list never filters the syncs. A failed or timed-out sync
- *   answers 500 `{error}` (a failed ontology sync too, after the shape sync ran).
  * - `POST /admin/graph-registry-changed` `{dataset}` → the host changed the named graphs of that
  *   dataset (a graph query through its gateway): the process drops its cached graph registry, so
  *   its next `.from(graphs.allOntologies)` read re-reads it, and answers 200
  *   `{invalidated: dataset}`. A body without a dataset name answers 400. Without the push the
  *   cache's 30-second expiry applies.
+ * - `POST /admin/graph-content` `{packages?, reload?}` → 200 {@link GraphContentAnswer}: what the
+ *   app's `'package'`-mode syncs would write for each package (its shape graph's Turtle, its
+ *   ontology graph's N-Triples, the hash each record gets, its sources) and for the app's own shape
+ *   graph, writing nothing. A host that writes the app's graphs itself (`LINKED_GRAPH_WRITER=host`)
+ *   reads them here. `reload` names packages whose source changed on disk: in dev they are
+ *   reloaded first (their modules invalidated in Vite, their backends reloaded, their ontologies
+ *   registered again and the shape check run), so the answer holds shapes added or changed since
+ *   the boot; a built app reloads nothing. Each name must be a valid npm package name and the app
+ *   itself or one of its direct dependencies, never an `@_linked/*` framework package. `packages`
+ *   limits the answer. One request at a time, as the system; one that takes longer than
+ *   `LINKED_SHAPE_SYNC_TIMEOUT_MS` fails with 500 and releases the queue. 400 for a malformed body
+ *   or a package it may not reload; 409 when a graph target is not `'package'`.
  * - `GET /admin/routes` → 200 {@link EffectiveRoutes}: the graph routes of every dataset the
  *   router knows (shape IRI → graph IRI) and the shapes each one writes to its default graph,
  *   as core's routing holds them once the app's storage file has run. The routes are written
@@ -49,7 +50,7 @@ export function isValidPackageName(name) {
 /**
  * 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}.
+ * dependencies, its `linked.unpublishedPackages` among them). Throws {@link AdminRequestError}.
  */
 export function assertReloadablePackages(packages, allowed) {
     for (const pkg of packages) {
@@ -58,13 +59,39 @@ export function assertReloadablePackages(packages, allowed) {
         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`);
+            throw new AdminRequestError(`unknown package: ${pkg} is neither the app nor one of its direct dependencies (dependencies, devDependencies, linked.unpublishedPackages)`);
         }
     }
 }
 /** Thrown by a handler for a request the channel refuses with 400. */
 export class AdminRequestError extends Error {
 }
+/** Thrown by a handler for a request that conflicts with how the process runs: answered 409. */
+export class AdminConflictError extends Error {
+}
+/** The body of a graph-content request: `packages` limits the answer, `reload` is reloaded first. */
+export function parseGraphContentBody(body) {
+    var _a;
+    if (body === undefined || body === null || body === '')
+        return { reload: [] };
+    if (typeof body !== 'object' || Array.isArray(body))
+        throw new AdminRequestError('the body must be a JSON object');
+    const names = (field) => {
+        const value = body[field];
+        if (value === undefined)
+            return undefined;
+        if (!Array.isArray(value) || value.some((p) => typeof p !== 'string' || !p)) {
+            throw new AdminRequestError(`${field} must be a list of package names`);
+        }
+        for (const p of value) {
+            if (!isValidPackageName(p))
+                throw new AdminRequestError(`not a package name: ${JSON.stringify(p)}`);
+        }
+        return [...new Set(value)];
+    };
+    const packages = names('packages');
+    return { ...(packages ? { packages } : {}), reload: (_a = names('reload')) !== null && _a !== void 0 ? _a : [] };
+}
 /**
  * Drop the process's cached graph registry after the host changed the graphs of `dataset`.
  *
@@ -95,25 +122,6 @@ export function adminSecretMatches(secret, provided) {
     const digest = (value) => createHash('sha256').update(value).digest();
     return timingSafeEqual(digest(provided), digest(secret));
 }
-/** The `packages` of a sync-shapes body: a list of package names, or none. */
-export function parseSyncShapesBody(body) {
-    if (body === undefined || body === null || body === '')
-        return { packages: [] };
-    if (typeof body !== 'object') {
-        throw new AdminRequestError('the body must be a JSON object');
-    }
-    const packages = body.packages;
-    if (packages === undefined)
-        return { packages: [] };
-    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`. */
 export function registerAdminRoutes(app, secret, handlers) {
     const requireAdmin = (req, res) => {
@@ -164,22 +172,26 @@ export function registerAdminRoutes(app, secret, handlers) {
         ((_a = handlers.graphRegistryChanged) !== null && _a !== void 0 ? _a : dropGraphRegistryCache)(dataset);
         res.status(200).json({ invalidated: dataset });
     });
-    app.post('/admin/sync-shapes', async (req, res) => {
+    app.post('/admin/graph-content', async (req, res) => {
         if (!requireAdmin(req, res))
             return;
+        if (!handlers.graphContent) {
+            res.sendStatus(404);
+            return;
+        }
         let request;
         try {
-            request = parseSyncShapesBody(req.body);
+            request = parseGraphContentBody(req.body);
         }
         catch (err) {
             res.status(400).json({ error: err.message });
             return;
         }
         try {
-            res.status(200).json(await handlers.syncShapes(request));
+            res.status(200).json(await handlers.graphContent(request));
         }
         catch (err) {
-            const status = err instanceof AdminRequestError ? 400 : 500;
+            const status = err instanceof AdminRequestError ? 400 : err instanceof AdminConflictError ? 409 : 500;
             res.status(status).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });

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 uses on an app process it\n * started. Present only when the process was started with a shared secret in\n * `APP_ADMIN_SECRET` (see {@link resolveAdminSecret}); without it every route answers\n * 404, so a standalone app has no control channel. Every request carries the secret in\n * the `x-app-admin-secret` header (401 otherwise).\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 ontologies (each registered package's\n *   ontology graph, skipped when unchanged), runs the shape check and\n *   re-syncs its shapes into its app data (each package's shape graph and the app's own,\n *   skipped when unchanged), as the boot does, and answers 200 with\n *   {@link ShapeSyncResult}, whose `shapeGraphs` reports the shape graphs. 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}`. The list never filters the syncs. A failed or timed-out sync\n *   answers 500 `{error}` (a failed ontology sync too, after the shape sync ran).\n * - `POST /admin/graph-registry-changed` `{dataset}` → the host changed the named graphs of that\n *   dataset (a graph query through its gateway): the process drops its cached graph registry, so\n *   its next `.from(graphs.allOntologies)` read re-reads it, and answers 200\n *   `{invalidated: dataset}`. A body without a dataset name answers 400. Without the push the\n *   cache's 30-second expiry applies.\n * - `GET /admin/routes` → 200 {@link EffectiveRoutes}: the graph routes of every dataset the\n *   router knows (shape IRI → graph IRI) and the shapes each one writes to its default graph,\n *   as core's routing holds them once the app's storage file has run. The routes are written\n *   only in the app's storage file; this route lets a host check what actually runs.\n */\nimport { createHash, timingSafeEqual } from 'crypto';\nimport type express from 'express';\nimport { invalidateGraphRegistry } from '@_linked/core/utils/graphRegistryCache';\nimport type { ShapeGraphsReport } from './syncShapes.js';\nimport { effectiveGraphRoutes, type EffectiveRoutes } from './effectiveRoutes.js';\n\n/** The environment variable that holds the control channel's secret. */\nexport const ADMIN_SECRET_ENV = 'APP_ADMIN_SECRET';\n/** The request header that carries the secret. */\nexport const ADMIN_SECRET_HEADER = 'x-app-admin-secret';\n\n/** The control channel's secret: `APP_ADMIN_SECRET`, else `undefined` (no control channel). */\nexport function resolveAdminSecret(\n  env: Record<string, string | undefined> = process.env\n): string | undefined {\n  return env[ADMIN_SECRET_ENV] || undefined;\n}\n\n/** What one shape sync did. */\nexport interface ShapeSyncResult {\n  /**\n   * Shape graphs written (package graphs and the app's own graph) because their stored hash\n   * differed; on a store without graph queries, the default-graph sync's writes.\n   */\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 shape graph sync: packages written and skipped, the graphs written, the app's own shape\n   * graph, the registered packages without `shapes.ttl` (so without a shape graph) and the\n   * default-graph shapes removed. Absent when no sync ran.\n   */\n  shapeGraphs?: ShapeGraphsReport;\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   * The ontology sync: packages whose ontology graph (or, on a store without graph queries,\n   * class hierarchy) was written, packages left as they were (unchanged, or their data could not\n   * be read), and the graphs written and dropped. Set by `POST /admin/sync-shapes`.\n   */\n  ontologies?: { written: string[]; skipped: string[]; graphs?: string[]; droppedGraphs?: string[] };\n  /** The shape check's findings, counted by severity (each is logged). Set by `POST /admin/sync-shapes`. */\n  shapeCheck?: { errors: number; warnings: number };\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   * Drop the cached graph registry for `dataset` (see `POST /admin/graph-registry-changed`).\n   * Default: {@link dropGraphRegistryCache}.\n   */\n  graphRegistryChanged?: (dataset: string) => void;\n  /** The effective graph routes (see `GET /admin/routes`). Default: {@link effectiveGraphRoutes}. */\n  routes?: () => EffectiveRoutes;\n}\n\n/**\n * Drop the process's cached graph registry after the host changed the graphs of `dataset`.\n *\n * Every entry is dropped, not only that dataset's: an entry's key is each store's own\n * (`graphRegistryKey()`: a `FusekiStore` keys by its dataset URL, a `RemoteDataset` by the\n * dataset its server names), no store tells which key it uses, and the stores are built by the\n * app's storage config, whose aliases the server does not see. The registry is small, so the cost\n * is one registry read per dataset on its next expanding read.\n */\nexport function dropGraphRegistryCache(_dataset: string): void {\n  invalidateGraphRegistry();\n}\n\n/** The `dataset` of a graph-registry-changed body: a non-empty name. */\nexport function parseGraphRegistryChangedBody(body: unknown): { dataset: string } {\n  const dataset = body && typeof body === 'object' ? (body as { dataset?: unknown }).dataset : undefined;\n  if (typeof dataset !== 'string' || !dataset.trim() || dataset.length > 1024) {\n    throw new AdminRequestError('dataset must be the name of the dataset whose graphs changed');\n  }\n  return { dataset: dataset.trim() };\n}\n\n/**\n * Compare the provided secret with the configured one in constant time. Both sides are hashed\n * first, so the comparison does not reveal the secret's length either.\n */\nexport function adminSecretMatches(\n  secret: string | undefined,\n  provided: string | undefined\n): boolean {\n  if (!secret || !provided) return false;\n  const digest = (value: string) => createHash('sha256').update(value).digest();\n  return timingSafeEqual(digest(provided), digest(secret));\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(ADMIN_SECRET_HEADER))) {\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.get('/admin/routes', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    try {\n      res.status(200).json((handlers.routes ?? effectiveGraphRoutes)());\n    } catch (err) {\n      res.status(500).json({ error: err instanceof Error ? err.message : String(err) });\n    }\n  });\n\n  app.post('/admin/graph-registry-changed', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    let dataset: string;\n    try {\n      ({ dataset } = parseGraphRegistryChangedBody(req.body));\n    } catch (err) {\n      res.status(400).json({ error: (err as Error).message });\n      return;\n    }\n    (handlers.graphRegistryChanged ?? dropGraphRegistryCache)(dataset);\n    res.status(200).json({ invalidated: dataset });\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":"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","sourcesContent":["/**\n * The host→app control channel: `/admin/*` routes a host uses on an app process it\n * started. Present only when the process was started with a shared secret in\n * `APP_ADMIN_SECRET` (see {@link resolveAdminSecret}); without it every route answers\n * 404, so a standalone app has no control channel. Every request carries the secret in\n * the `x-app-admin-secret` header (401 otherwise).\n *\n * - `GET /admin/health` → 200 `{status: 'ok'}` once the server listens (a boot sync, when\n *   the app writes its own graphs, has finished by then).\n * - `POST /admin/restart` → 202, then the process exits; the host starts it again.\n * - `POST /admin/graph-registry-changed` `{dataset}` → the host changed the named graphs of that\n *   dataset (a graph query through its gateway): the process drops its cached graph registry, so\n *   its next `.from(graphs.allOntologies)` read re-reads it, and answers 200\n *   `{invalidated: dataset}`. A body without a dataset name answers 400. Without the push the\n *   cache's 30-second expiry applies.\n * - `POST /admin/graph-content` `{packages?, reload?}` → 200 {@link GraphContentAnswer}: what the\n *   app's `'package'`-mode syncs would write for each package (its shape graph's Turtle, its\n *   ontology graph's N-Triples, the hash each record gets, its sources) and for the app's own shape\n *   graph, writing nothing. A host that writes the app's graphs itself (`LINKED_GRAPH_WRITER=host`)\n *   reads them here. `reload` names packages whose source changed on disk: in dev they are\n *   reloaded first (their modules invalidated in Vite, their backends reloaded, their ontologies\n *   registered again and the shape check run), so the answer holds shapes added or changed since\n *   the boot; a built app reloads nothing. Each name must be a valid npm package name and the app\n *   itself or one of its direct dependencies, never an `@_linked/*` framework package. `packages`\n *   limits the answer. One request at a time, as the system; one that takes longer than\n *   `LINKED_SHAPE_SYNC_TIMEOUT_MS` fails with 500 and releases the queue. 400 for a malformed body\n *   or a package it may not reload; 409 when a graph target is not `'package'`.\n * - `GET /admin/routes` → 200 {@link EffectiveRoutes}: the graph routes of every dataset the\n *   router knows (shape IRI → graph IRI) and the shapes each one writes to its default graph,\n *   as core's routing holds them once the app's storage file has run. The routes are written\n *   only in the app's storage file; this route lets a host check what actually runs.\n */\nimport { createHash, timingSafeEqual } from 'crypto';\nimport type express from 'express';\nimport { invalidateGraphRegistry } from '@_linked/core/utils/graphRegistryCache';\nimport type { GraphContents } from './syncShapes.js';\nimport type { GraphTargets } from '@_linked/core/utils/graphTargets';\nimport { effectiveGraphRoutes, type EffectiveRoutes } from './effectiveRoutes.js';\n\n/** The environment variable that holds the control channel's secret. */\nexport const ADMIN_SECRET_ENV = 'APP_ADMIN_SECRET';\n/** The request header that carries the secret. */\nexport const ADMIN_SECRET_HEADER = 'x-app-admin-secret';\n\n/** The control channel's secret: `APP_ADMIN_SECRET`, else `undefined` (no control channel). */\nexport function resolveAdminSecret(\n  env: Record<string, string | undefined> = process.env\n): string | undefined {\n  return env[ADMIN_SECRET_ENV] || undefined;\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, its `linked.unpublishedPackages` among them). 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 (dependencies, devDependencies, linked.unpublishedPackages)`);\n    }\n  }\n}\n\n/** Thrown by a handler for a request the channel refuses with 400. */\nexport class AdminRequestError extends Error {}\n\n/** Thrown by a handler for a request that conflicts with how the process runs: answered 409. */\nexport class AdminConflictError extends Error {}\n\n/** The answer of `POST /admin/graph-content`. */\nexport interface GraphContentAnswer extends GraphContents {\n  /** The process's graph targets (both `'package'`, or the route answers 409). */\n  graphTargets: GraphTargets;\n  /** The requested packages whose source was reloaded first (dev only). */\n  reloaded: string[];\n}\n\n/** The body of a graph-content request: `packages` limits the answer, `reload` is reloaded first. */\nexport function parseGraphContentBody(body: unknown): { packages?: string[]; reload: string[] } {\n  if (body === undefined || body === null || body === '') return { reload: [] };\n  if (typeof body !== 'object' || Array.isArray(body)) throw new AdminRequestError('the body must be a JSON object');\n  const names = (field: 'packages' | 'reload'): string[] | undefined => {\n    const value = (body as Record<string, unknown>)[field];\n    if (value === undefined) return undefined;\n    if (!Array.isArray(value) || value.some((p) => typeof p !== 'string' || !p)) {\n      throw new AdminRequestError(`${field} must be a list of package names`);\n    }\n    for (const p of value as string[]) {\n      if (!isValidPackageName(p)) throw new AdminRequestError(`not a package name: ${JSON.stringify(p)}`);\n    }\n    return [...new Set(value as string[])];\n  };\n  const packages = names('packages');\n  return { ...(packages ? { packages } : {}), reload: names('reload') ?? [] };\n}\n\nexport interface AdminChannelHandlers {\n  /** Exit the process (the host restarts it). Called after the 202 is sent. */\n  exit: () => void;\n  /**\n   * Drop the cached graph registry for `dataset` (see `POST /admin/graph-registry-changed`).\n   * Default: {@link dropGraphRegistryCache}.\n   */\n  graphRegistryChanged?: (dataset: string) => void;\n  /** The effective graph routes (see `GET /admin/routes`). Default: {@link effectiveGraphRoutes}. */\n  routes?: () => EffectiveRoutes;\n  /** Reload `reload`, then answer the content of the app's graphs (see `POST /admin/graph-content`); without it the route answers 404. */\n  graphContent?: (request: { packages?: string[]; reload: string[] }) => Promise<GraphContentAnswer>;\n}\n\n/**\n * Drop the process's cached graph registry after the host changed the graphs of `dataset`.\n *\n * Every entry is dropped, not only that dataset's: an entry's key is each store's own\n * (`graphRegistryKey()`: a `FusekiStore` keys by its dataset URL, a `RemoteDataset` by the\n * dataset its server names), no store tells which key it uses, and the stores are built by the\n * app's storage config, whose aliases the server does not see. The registry is small, so the cost\n * is one registry read per dataset on its next expanding read.\n */\nexport function dropGraphRegistryCache(_dataset: string): void {\n  invalidateGraphRegistry();\n}\n\n/** The `dataset` of a graph-registry-changed body: a non-empty name. */\nexport function parseGraphRegistryChangedBody(body: unknown): { dataset: string } {\n  const dataset = body && typeof body === 'object' ? (body as { dataset?: unknown }).dataset : undefined;\n  if (typeof dataset !== 'string' || !dataset.trim() || dataset.length > 1024) {\n    throw new AdminRequestError('dataset must be the name of the dataset whose graphs changed');\n  }\n  return { dataset: dataset.trim() };\n}\n\n/**\n * Compare the provided secret with the configured one in constant time. Both sides are hashed\n * first, so the comparison does not reveal the secret's length either.\n */\nexport function adminSecretMatches(\n  secret: string | undefined,\n  provided: string | undefined\n): boolean {\n  if (!secret || !provided) return false;\n  const digest = (value: string) => createHash('sha256').update(value).digest();\n  return timingSafeEqual(digest(provided), digest(secret));\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(ADMIN_SECRET_HEADER))) {\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.get('/admin/routes', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    try {\n      res.status(200).json((handlers.routes ?? effectiveGraphRoutes)());\n    } catch (err) {\n      res.status(500).json({ error: err instanceof Error ? err.message : String(err) });\n    }\n  });\n\n  app.post('/admin/graph-registry-changed', (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    let dataset: string;\n    try {\n      ({ dataset } = parseGraphRegistryChangedBody(req.body));\n    } catch (err) {\n      res.status(400).json({ error: (err as Error).message });\n      return;\n    }\n    (handlers.graphRegistryChanged ?? dropGraphRegistryCache)(dataset);\n    res.status(200).json({ invalidated: dataset });\n  });\n\n  app.post('/admin/graph-content', async (req, res) => {\n    if (!requireAdmin(req, res)) return;\n    if (!handlers.graphContent) {\n      res.sendStatus(404);\n      return;\n    }\n    let request: { packages?: string[]; reload: string[] };\n    try {\n      request = parseGraphContentBody(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.graphContent(request));\n    } catch (err) {\n      const status = err instanceof AdminRequestError ? 400 : err instanceof AdminConflictError ? 409 : 500;\n      res.status(status).json({ error: err instanceof Error ? err.message : String(err) });\n    }\n  });\n}\n"]}

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

@@ -1,4 +1,5 @@
 import { type GraphTargets } from '@_linked/core/utils/graphTargets';
+import { type GraphWriter } from './graphTargets.js';
 /** One dataset the router knows, and its graph routes. */
 export interface DatasetRoutes {
     /**
@@ -33,6 +34,11 @@ export interface EffectiveRoutes {
      * so a host can tell where {@link graphTargets} came from.
      */
     graphTargetEnv: Record<string, string>;
+    /**
+     * Who writes the app's shape and ontology graphs (`LINKED_GRAPH_WRITER`): `'app'`, or `'host'`
+     * when a host writes them and the process writes none.
+     */
+    graphWriter: GraphWriter;
 }
 /** The routes of every dataset the router knows (see {@link EffectiveRoutes}). */
 export declare function effectiveGraphRoutes(env?: Record<string, string | undefined>): EffectiveRoutes;

package/lib/esm/utils/effectiveRoutes.js

@@ -9,7 +9,7 @@ import { getShapeGraphs, graphRoutingFor } from '@_linked/core/utils/graphRoutin
 import { getAllShapeClasses } from '@_linked/core/utils/ShapeClass';
 import { graphs } from '@_linked/core/ontologies/graphs';
 import { getGraphTargets } from '@_linked/core/utils/graphTargets';
-import { graphTargetEnv } from './graphTargets.js';
+import { graphTargetEnv, graphWriterFromEnv } from './graphTargets.js';
 /** The routes of every dataset the router knows (see {@link EffectiveRoutes}). */
 export function effectiveGraphRoutes(env = process.env) {
     var _a, _b;
@@ -39,6 +39,7 @@ export function effectiveGraphRoutes(env = process.env) {
         }),
         graphTargets: getGraphTargets(),
         graphTargetEnv: graphTargetEnv(env),
+        graphWriter: graphWriterFromEnv(env),
     };
 }
 //# sourceMappingURL=effectiveRoutes.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"effectiveRoutes.js","sourceRoot":"","sources":["../../../src/utils/effectiveRoutes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAqB,MAAM,kCAAkC,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAuCnD,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAAC,MAA0C,OAAO,CAAC,GAAG;;IACxF,MAAM,QAAQ,GAAG,CAAC,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,CAAC;IAClD,MAAM,cAAc,GAAG,aAAa,CAAC,iBAAiB,EAAE,CAAC;IACzD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAqB,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,kBAAkB,EAAE,EAAE,CAAC;QACrD,MAAM,OAAO,GAAG,aAAa,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,KAAK,GAAG,MAAA,MAAA,eAAe,CAAC,OAAO,CAAC,0CAAE,aAAa,CAAC,GAAG,CAAC,mCAAI,MAAM,CAAC,OAAO,CAAC;QAC7E,IAAI,KAAK,KAAK,MAAM,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;;YACjC,MAAM,EAAE,GAAI,OAA4B,CAAC,EAAE,CAAC;YAC5C,OAAO;gBACL,KAAK,EAAE,CAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,0CAAE,IAAI,KAAI,SAAS;gBAC9C,GAAG,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,OAAO,EAAE,OAAO,KAAK,cAAc;gBACnC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC;gBAC/B,kBAAkB,EAAE,CAAC,MAAA,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,mCAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aACnE,CAAC;QACJ,CAAC,CAAC;QACF,YAAY,EAAE,eAAe,EAAE;QAC/B,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC;KACpC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The graph routes the process runs with, as core's routing holds them once the app's storage\n * file has run (`LinkedStorage.setDatasetForShapes(dataset, shapes, {graph})`, or `loadStores`\n * for a datasets config that still carries routes). Answered by `GET /admin/routes`, so a host\n * can compare what it wrote into the storage file with what actually runs.\n */\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { getShapeGraphs, graphRoutingFor } from '@_linked/core/utils/graphRouting';\nimport { getAllShapeClasses } from '@_linked/core/utils/ShapeClass';\nimport { graphs } from '@_linked/core/ontologies/graphs';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport { getGraphTargets, type GraphTargets } from '@_linked/core/utils/graphTargets';\nimport { graphTargetEnv } from './graphTargets.js';\n\n/** One dataset the router knows, and its graph routes. */\nexport interface DatasetRoutes {\n  /**\n   * The store's class name (`FusekiStore`, `RemoteDataset`, …). The server never sees the\n   * aliases of the storage config, so a dataset is told apart by this, `default` and `id`.\n   */\n  store: string;\n  /** The store's `id`, when it has one (a named `RemoteDataset` does). */\n  id?: string;\n  /** Whether this is the default dataset (the one for every shape without a pin). */\n  default: boolean;\n  /** The dataset's routes as registered: shape IRI → graph IRI. */\n  routes: Record<string, string>;\n  /**\n   * The registered shapes that resolve to this dataset and whose instances are written to its\n   * default graph: no route of their own and no routed super-shape. Sorted.\n   */\n  defaultGraphShapes: string[];\n}\n\n/** The body of `GET /admin/routes`. */\nexport interface EffectiveRoutes {\n  /** Every dataset the router knows, the default one first, then in the order they were pinned. */\n  datasets: DatasetRoutes[];\n  /**\n   * The process's graph targets (core's `getGraphTargets()`: `'package'`, `'default'` or a shared\n   * graph IRI each), one global setting for every dataset: where the boot syncs write and where\n   * `graphs.allOntologies` / `graphs.allShapes` read.\n   */\n  graphTargets: GraphTargets;\n  /**\n   * `LINKED_ONTOLOGY_GRAPH` / `LINKED_SHAPE_GRAPH` as the process has them (unset ones left out),\n   * so a host can tell where {@link graphTargets} came from.\n   */\n  graphTargetEnv: Record<string, string>;\n}\n\n/** The routes of every dataset the router knows (see {@link EffectiveRoutes}). */\nexport function effectiveGraphRoutes(env: Record<string, string | undefined> = process.env): EffectiveRoutes {\n  const datasets = [...LinkedStorage.getDatasets()];\n  const defaultDataset = LinkedStorage.getDefaultDataset();\n  const defaultGraphShapes = new Map<IDataset, string[]>(datasets.map((ds) => [ds, []]));\n  for (const [iri, shapeClass] of getAllShapeClasses()) {\n    const dataset = LinkedStorage.getDatasetForShapeClass(shapeClass);\n    const list = dataset && defaultGraphShapes.get(dataset);\n    if (!list) continue;\n    const graph = graphRoutingFor(dataset)?.graphForShape(iri) ?? graphs.default;\n    if (graph === graphs.default) list.push(iri);\n  }\n  return {\n    datasets: datasets.map((dataset) => {\n      const id = (dataset as { id?: unknown }).id;\n      return {\n        store: dataset?.constructor?.name || 'unknown',\n        ...(typeof id === 'string' && id ? { id } : {}),\n        default: dataset === defaultDataset,\n        routes: getShapeGraphs(dataset),\n        defaultGraphShapes: (defaultGraphShapes.get(dataset) ?? []).sort(),\n      };\n    }),\n    graphTargets: getGraphTargets(),\n    graphTargetEnv: graphTargetEnv(env),\n  };\n}\n"]}
+{"version":3,"file":"effectiveRoutes.js","sourceRoot":"","sources":["../../../src/utils/effectiveRoutes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAqB,MAAM,kCAAkC,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAoB,MAAM,mBAAmB,CAAC;AA4CzF,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAAC,MAA0C,OAAO,CAAC,GAAG;;IACxF,MAAM,QAAQ,GAAG,CAAC,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,CAAC;IAClD,MAAM,cAAc,GAAG,aAAa,CAAC,iBAAiB,EAAE,CAAC;IACzD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAqB,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,kBAAkB,EAAE,EAAE,CAAC;QACrD,MAAM,OAAO,GAAG,aAAa,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,KAAK,GAAG,MAAA,MAAA,eAAe,CAAC,OAAO,CAAC,0CAAE,aAAa,CAAC,GAAG,CAAC,mCAAI,MAAM,CAAC,OAAO,CAAC;QAC7E,IAAI,KAAK,KAAK,MAAM,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;;YACjC,MAAM,EAAE,GAAI,OAA4B,CAAC,EAAE,CAAC;YAC5C,OAAO;gBACL,KAAK,EAAE,CAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,0CAAE,IAAI,KAAI,SAAS;gBAC9C,GAAG,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,OAAO,EAAE,OAAO,KAAK,cAAc;gBACnC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC;gBAC/B,kBAAkB,EAAE,CAAC,MAAA,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,mCAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aACnE,CAAC;QACJ,CAAC,CAAC;QACF,YAAY,EAAE,eAAe,EAAE;QAC/B,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC;QACnC,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC;KACrC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The graph routes the process runs with, as core's routing holds them once the app's storage\n * file has run (`LinkedStorage.setDatasetForShapes(dataset, shapes, {graph})`, or `loadStores`\n * for a datasets config that still carries routes). Answered by `GET /admin/routes`, so a host\n * can compare what it wrote into the storage file with what actually runs.\n */\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { getShapeGraphs, graphRoutingFor } from '@_linked/core/utils/graphRouting';\nimport { getAllShapeClasses } from '@_linked/core/utils/ShapeClass';\nimport { graphs } from '@_linked/core/ontologies/graphs';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport { getGraphTargets, type GraphTargets } from '@_linked/core/utils/graphTargets';\nimport { graphTargetEnv, graphWriterFromEnv, type GraphWriter } from './graphTargets.js';\n\n/** One dataset the router knows, and its graph routes. */\nexport interface DatasetRoutes {\n  /**\n   * The store's class name (`FusekiStore`, `RemoteDataset`, …). The server never sees the\n   * aliases of the storage config, so a dataset is told apart by this, `default` and `id`.\n   */\n  store: string;\n  /** The store's `id`, when it has one (a named `RemoteDataset` does). */\n  id?: string;\n  /** Whether this is the default dataset (the one for every shape without a pin). */\n  default: boolean;\n  /** The dataset's routes as registered: shape IRI → graph IRI. */\n  routes: Record<string, string>;\n  /**\n   * The registered shapes that resolve to this dataset and whose instances are written to its\n   * default graph: no route of their own and no routed super-shape. Sorted.\n   */\n  defaultGraphShapes: string[];\n}\n\n/** The body of `GET /admin/routes`. */\nexport interface EffectiveRoutes {\n  /** Every dataset the router knows, the default one first, then in the order they were pinned. */\n  datasets: DatasetRoutes[];\n  /**\n   * The process's graph targets (core's `getGraphTargets()`: `'package'`, `'default'` or a shared\n   * graph IRI each), one global setting for every dataset: where the boot syncs write and where\n   * `graphs.allOntologies` / `graphs.allShapes` read.\n   */\n  graphTargets: GraphTargets;\n  /**\n   * `LINKED_ONTOLOGY_GRAPH` / `LINKED_SHAPE_GRAPH` as the process has them (unset ones left out),\n   * so a host can tell where {@link graphTargets} came from.\n   */\n  graphTargetEnv: Record<string, string>;\n  /**\n   * Who writes the app's shape and ontology graphs (`LINKED_GRAPH_WRITER`): `'app'`, or `'host'`\n   * when a host writes them and the process writes none.\n   */\n  graphWriter: GraphWriter;\n}\n\n/** The routes of every dataset the router knows (see {@link EffectiveRoutes}). */\nexport function effectiveGraphRoutes(env: Record<string, string | undefined> = process.env): EffectiveRoutes {\n  const datasets = [...LinkedStorage.getDatasets()];\n  const defaultDataset = LinkedStorage.getDefaultDataset();\n  const defaultGraphShapes = new Map<IDataset, string[]>(datasets.map((ds) => [ds, []]));\n  for (const [iri, shapeClass] of getAllShapeClasses()) {\n    const dataset = LinkedStorage.getDatasetForShapeClass(shapeClass);\n    const list = dataset && defaultGraphShapes.get(dataset);\n    if (!list) continue;\n    const graph = graphRoutingFor(dataset)?.graphForShape(iri) ?? graphs.default;\n    if (graph === graphs.default) list.push(iri);\n  }\n  return {\n    datasets: datasets.map((dataset) => {\n      const id = (dataset as { id?: unknown }).id;\n      return {\n        store: dataset?.constructor?.name || 'unknown',\n        ...(typeof id === 'string' && id ? { id } : {}),\n        default: dataset === defaultDataset,\n        routes: getShapeGraphs(dataset),\n        defaultGraphShapes: (defaultGraphShapes.get(dataset) ?? []).sort(),\n      };\n    }),\n    graphTargets: getGraphTargets(),\n    graphTargetEnv: graphTargetEnv(env),\n    graphWriter: graphWriterFromEnv(env),\n  };\n}\n"]}

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

@@ -0,0 +1,46 @@
+import type { Transaction } from '@_linked/core/utils/Transaction';
+/** A transaction was asked of a forwarder whose stores do not all hold transactions. */
+export declare class TransactionUnsupportedError extends Error {
+    readonly code = "transactions-unsupported";
+    constructor(message: string);
+}
+/** A txId this forwarder does not hold: never begun here, ended, failed, or expired. */
+export declare class TransactionUnknownError extends Error {
+    readonly code = "transaction-unknown";
+    constructor(txId: string);
+}
+/** A txId presented by another caller than the one that began it. */
+export declare class TransactionNotYoursError extends Error {
+    readonly code = "transaction-not-yours";
+    constructor(txId: string);
+}
+/** The query a transaction view stands for: core's `inTransaction` view has it as prototype. */
+export declare function withoutTxId<Q extends object>(query: Q): Q;
+export interface ForwardedTransactionsOptions {
+    /** Idle time after which a transaction is rolled back and forgotten, in ms (default 30 000). */
+    timeoutMs?: number;
+}
+export declare class ForwardedTransactions {
+    private readonly held;
+    private readonly timeoutMs;
+    constructor(options?: ForwardedTransactionsOptions);
+    /** How many transactions are open (for tests and diagnostics). */
+    get size(): number;
+    /** Hold `tx` for `caller`; answers its id. */
+    begin(caller: string, tx: Transaction): string;
+    /**
+     * Run `query` (which carries a txId) in its transaction: the caller must be the one that began
+     * it; then `check` (the rights of the query, as if it were sent alone) and `run` with the query
+     * outside its view. A refusal by `check` and a failure of `run` roll the transaction back. The
+     * transaction does not expire while the query runs.
+     */
+    query<R>(query: object, caller: string, check: (tx: Transaction) => Promise<void> | void, run: (tx: Transaction, query: any) => Promise<R>): Promise<R>;
+    /** Commit: the caller's own transaction, else refused; unknown or expired rejects. */
+    commit(txId: string, caller: string): Promise<void>;
+    /** Roll back: the caller's own transaction, else refused; an unknown txId resolves (a no-op). */
+    rollback(txId: string, caller: string): Promise<void>;
+    private own;
+    private touch;
+    /** Forget `txId` (once), rolling its transaction back when asked to. */
+    private drop;
+}

package/lib/esm/utils/forwardedTransactions.js

@@ -0,0 +1,155 @@
+/**
+ * The store transactions a forwarder holds for its callers (core report 103, "Forwarding contract").
+ *
+ * A forwarder (this server's query plane) answers `beginTransaction()` with an id of its own and
+ * keeps a core `Transaction` for it. Each later query that carries the id runs in that
+ * transaction, which opens a transaction in the store the query routes to at its first query
+ * there (and warns, as core does, when a second store is reached). The id is bound to the caller
+ * that began it: anyone else presenting it is refused, and the transaction is left as it was.
+ *
+ * - A query that fails, or that a check refuses, fails the transaction: it is rolled back in
+ *   every store and forgotten, so a later `commit` rejects as unknown and `rollback` resolves
+ *   (a select whose query context is not ready, core's `UnresolvedContextError`, did not run and
+ *   fails nothing). A forwarder that refuses a query before it gets here calls `rollback` itself.
+ * - An idle transaction (no query running, and none, no commit or rollback for `timeoutMs`,
+ *   default 30 s) is rolled back and forgotten.
+ * - A forwarder holds transactions only when every store it routes to does; it checks that
+ *   itself (see `supportsTransactions` in core) before it begins one or runs a query in one.
+ */
+import { randomUUID } from 'node:crypto';
+import { brandLinkedError, isLinkedError } from '@_linked/core/utils/linkedError';
+import { UnresolvedContextError } from '@_linked/core/queries/QueryContext';
+import { txIdOf } from '@_linked/core/queries/transactionQuery';
+/** A transaction was asked of a forwarder whose stores do not all hold transactions. */
+export class TransactionUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'transactions-unsupported';
+        this.name = new.target.name;
+    }
+}
+/** A txId this forwarder does not hold: never begun here, ended, failed, or expired. */
+export class TransactionUnknownError extends Error {
+    constructor(txId) {
+        super(`transaction ${txId} is unknown or expired`);
+        this.code = 'transaction-unknown';
+        this.name = new.target.name;
+    }
+}
+/** A txId presented by another caller than the one that began it. */
+export class TransactionNotYoursError extends Error {
+    constructor(txId) {
+        super(`transaction ${txId} was begun by another caller`);
+        this.code = 'transaction-not-yours';
+        this.name = new.target.name;
+    }
+}
+brandLinkedError(TransactionUnsupportedError, '@_linked/server', 'TransactionUnsupportedError');
+brandLinkedError(TransactionUnknownError, '@_linked/server', 'TransactionUnknownError');
+brandLinkedError(TransactionNotYoursError, '@_linked/server', 'TransactionNotYoursError');
+/** The query a transaction view stands for: core's `inTransaction` view has it as prototype. */
+export function withoutTxId(query) {
+    if (!Object.prototype.hasOwnProperty.call(query, 'txId'))
+        return query;
+    return Object.getPrototypeOf(query);
+}
+export class ForwardedTransactions {
+    constructor(options = {}) {
+        var _a;
+        this.held = new Map();
+        this.timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : 30000;
+    }
+    /** How many transactions are open (for tests and diagnostics). */
+    get size() {
+        return this.held.size;
+    }
+    /** Hold `tx` for `caller`; answers its id. */
+    begin(caller, tx) {
+        const txId = randomUUID();
+        const held = { tx, caller, running: 0 };
+        this.held.set(txId, held);
+        this.touch(txId, held);
+        return txId;
+    }
+    /**
+     * Run `query` (which carries a txId) in its transaction: the caller must be the one that began
+     * it; then `check` (the rights of the query, as if it were sent alone) and `run` with the query
+     * outside its view. A refusal by `check` and a failure of `run` roll the transaction back. The
+     * transaction does not expire while the query runs.
+     */
+    async query(query, caller, check, run) {
+        const txId = txIdOf(query);
+        if (txId === undefined)
+            throw new Error('ForwardedTransactions.query: the query carries no txId');
+        const held = this.own(txId, caller);
+        if (held.timer)
+            clearTimeout(held.timer);
+        held.running++;
+        try {
+            await check(held.tx);
+            return await run(held.tx, withoutTxId(query));
+        }
+        catch (err) {
+            if (!isLinkedError(err, UnresolvedContextError))
+                await this.drop(txId, held, true);
+            throw err;
+        }
+        finally {
+            held.running--;
+            if (this.held.get(txId) === held && held.running === 0)
+                this.touch(txId, held);
+        }
+    }
+    /** Commit: the caller's own transaction, else refused; unknown or expired rejects. */
+    async commit(txId, caller) {
+        const held = this.own(txId, caller);
+        await this.drop(txId, held, false);
+        await held.tx.commit();
+    }
+    /** Roll back: the caller's own transaction, else refused; an unknown txId resolves (a no-op). */
+    async rollback(txId, caller) {
+        const held = this.held.get(txId);
+        if (!held)
+            return;
+        if (held.caller !== caller)
+            throw new TransactionNotYoursError(txId);
+        await this.drop(txId, held, true);
+    }
+    own(txId, caller) {
+        const held = typeof txId === 'string' ? this.held.get(txId) : undefined;
+        if (!held)
+            throw new TransactionUnknownError(String(txId));
+        if (held.caller !== caller)
+            throw new TransactionNotYoursError(txId);
+        return held;
+    }
+    touch(txId, held) {
+        var _a, _b;
+        if (held.timer)
+            clearTimeout(held.timer);
+        held.timer = setTimeout(() => {
+            if (!held.running)
+                void this.drop(txId, held, true);
+        }, this.timeoutMs);
+        (_b = (_a = held.timer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    /** Forget `txId` (once), rolling its transaction back when asked to. */
+    async drop(txId, held, rollBack) {
+        if (held.timer)
+            clearTimeout(held.timer);
+        if (this.held.get(txId) !== held)
+            return;
+        this.held.delete(txId);
+        if (!rollBack)
+            return;
+        try {
+            await held.tx.rollback();
+        }
+        catch (err) {
+            // Committed or failed already: nothing to roll back.
+            if (held.tx.state === 'open')
+                console.error(`[linked] rolling back transaction ${txId} failed:`, err);
+        }
+    }
+}
+//# sourceMappingURL=forwardedTransactions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forwardedTransactions.js","sourceRoot":"","sources":["../../../src/utils/forwardedTransactions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The store transactions a forwarder holds for its callers (core report 103, \"Forwarding contract\").\n *\n * A forwarder (this server's query plane) answers `beginTransaction()` with an id of its own and\n * keeps a core `Transaction` for it. Each later query that carries the id runs in that\n * transaction, which opens a transaction in the store the query routes to at its first query\n * there (and warns, as core does, when a second store is reached). The id is bound to the caller\n * that began it: anyone else presenting it is refused, and the transaction is left as it was.\n *\n * - A query that fails, or that a check refuses, fails the transaction: it is rolled back in\n *   every store and forgotten, so a later `commit` rejects as unknown and `rollback` resolves\n *   (a select whose query context is not ready, core's `UnresolvedContextError`, did not run and\n *   fails nothing). A forwarder that refuses a query before it gets here calls `rollback` itself.\n * - An idle transaction (no query running, and none, no commit or rollback for `timeoutMs`,\n *   default 30 s) is rolled back and forgotten.\n * - A forwarder holds transactions only when every store it routes to does; it checks that\n *   itself (see `supportsTransactions` in core) before it begins one or runs a query in one.\n */\nimport { randomUUID } from 'node:crypto';\nimport { brandLinkedError, isLinkedError } from '@_linked/core/utils/linkedError';\nimport { UnresolvedContextError } from '@_linked/core/queries/QueryContext';\nimport type { Transaction } from '@_linked/core/utils/Transaction';\nimport { txIdOf } from '@_linked/core/queries/transactionQuery';\n\n/** A transaction was asked of a forwarder whose stores do not all hold transactions. */\nexport class TransactionUnsupportedError extends Error {\n  readonly code = 'transactions-unsupported';\n  constructor(message: string) {\n    super(message);\n    this.name = new.target.name;\n  }\n}\n\n/** A txId this forwarder does not hold: never begun here, ended, failed, or expired. */\nexport class TransactionUnknownError extends Error {\n  readonly code = 'transaction-unknown';\n  constructor(txId: string) {\n    super(`transaction ${txId} is unknown or expired`);\n    this.name = new.target.name;\n  }\n}\n\n/** A txId presented by another caller than the one that began it. */\nexport class TransactionNotYoursError extends Error {\n  readonly code = 'transaction-not-yours';\n  constructor(txId: string) {\n    super(`transaction ${txId} was begun by another caller`);\n    this.name = new.target.name;\n  }\n}\n\nbrandLinkedError(TransactionUnsupportedError, '@_linked/server', 'TransactionUnsupportedError');\nbrandLinkedError(TransactionUnknownError, '@_linked/server', 'TransactionUnknownError');\nbrandLinkedError(TransactionNotYoursError, '@_linked/server', 'TransactionNotYoursError');\n\n/** The query a transaction view stands for: core's `inTransaction` view has it as prototype. */\nexport function withoutTxId<Q extends object>(query: Q): Q {\n  if (!Object.prototype.hasOwnProperty.call(query, 'txId')) return query;\n  return Object.getPrototypeOf(query) as Q;\n}\n\ninterface Held {\n  tx: Transaction;\n  caller: string;\n  timer?: ReturnType<typeof setTimeout>;\n  /** Queries of it running now: it does not expire meanwhile. */\n  running: number;\n}\n\nexport interface ForwardedTransactionsOptions {\n  /** Idle time after which a transaction is rolled back and forgotten, in ms (default 30 000). */\n  timeoutMs?: number;\n}\n\nexport class ForwardedTransactions {\n  private readonly held = new Map<string, Held>();\n  private readonly timeoutMs: number;\n\n  constructor(options: ForwardedTransactionsOptions = {}) {\n    this.timeoutMs = options.timeoutMs ?? 30_000;\n  }\n\n  /** How many transactions are open (for tests and diagnostics). */\n  get size(): number {\n    return this.held.size;\n  }\n\n  /** Hold `tx` for `caller`; answers its id. */\n  begin(caller: string, tx: Transaction): string {\n    const txId = randomUUID();\n    const held: Held = { tx, caller, running: 0 };\n    this.held.set(txId, held);\n    this.touch(txId, held);\n    return txId;\n  }\n\n  /**\n   * Run `query` (which carries a txId) in its transaction: the caller must be the one that began\n   * it; then `check` (the rights of the query, as if it were sent alone) and `run` with the query\n   * outside its view. A refusal by `check` and a failure of `run` roll the transaction back. The\n   * transaction does not expire while the query runs.\n   */\n  async query<R>(\n    query: object,\n    caller: string,\n    check: (tx: Transaction) => Promise<void> | void,\n    run: (tx: Transaction, query: any) => Promise<R>,\n  ): Promise<R> {\n    const txId = txIdOf(query);\n    if (txId === undefined) throw new Error('ForwardedTransactions.query: the query carries no txId');\n    const held = this.own(txId, caller);\n    if (held.timer) clearTimeout(held.timer);\n    held.running++;\n    try {\n      await check(held.tx);\n      return await run(held.tx, withoutTxId(query));\n    } catch (err) {\n      if (!isLinkedError(err, UnresolvedContextError)) await this.drop(txId, held, true);\n      throw err;\n    } finally {\n      held.running--;\n      if (this.held.get(txId) === held && held.running === 0) this.touch(txId, held);\n    }\n  }\n\n  /** Commit: the caller's own transaction, else refused; unknown or expired rejects. */\n  async commit(txId: string, caller: string): Promise<void> {\n    const held = this.own(txId, caller);\n    await this.drop(txId, held, false);\n    await held.tx.commit();\n  }\n\n  /** Roll back: the caller's own transaction, else refused; an unknown txId resolves (a no-op). */\n  async rollback(txId: string, caller: string): Promise<void> {\n    const held = this.held.get(txId);\n    if (!held) return;\n    if (held.caller !== caller) throw new TransactionNotYoursError(txId);\n    await this.drop(txId, held, true);\n  }\n\n  private own(txId: string, caller: string): Held {\n    const held = typeof txId === 'string' ? this.held.get(txId) : undefined;\n    if (!held) throw new TransactionUnknownError(String(txId));\n    if (held.caller !== caller) throw new TransactionNotYoursError(txId);\n    return held;\n  }\n\n  private touch(txId: string, held: Held): void {\n    if (held.timer) clearTimeout(held.timer);\n    held.timer = setTimeout(() => {\n      if (!held.running) void this.drop(txId, held, true);\n    }, this.timeoutMs);\n    held.timer.unref?.();\n  }\n\n  /** Forget `txId` (once), rolling its transaction back when asked to. */\n  private async drop(txId: string, held: Held, rollBack: boolean): Promise<void> {\n    if (held.timer) clearTimeout(held.timer);\n    if (this.held.get(txId) !== held) return;\n    this.held.delete(txId);\n    if (!rollBack) return;\n    try {\n      await held.tx.rollback();\n    } catch (err) {\n      // Committed or failed already: nothing to roll back.\n      if (held.tx.state === 'open') console.error(`[linked] rolling back transaction ${txId} failed:`, err);\n    }\n  }\n}\n"]}