@_linked/server 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @\_linked/server
 
+## 3.2.0
+
+### Minor Changes
+
+- [#185](https://github.com/linked-fw/server/pull/185) [`0525786`](https://github.com/linked-fw/server/commit/05257867d02ad8057a8691f61e94f1bbb937c56d) Thanks [@flyon](https://github.com/flyon)! - `RemoteDataset.init()` now resolves the data server's `ping` body, and the store keeps it as the readonly `info` (type `RemoteDatasetPingInfo`). A gateway that names the dataset it serves (for example `{ok, projectId, branchName, dataset, forked}`) lets an app log at startup which dataset its data goes to. The no-url form resolves `undefined`, as before.
+
+## 3.1.0
+
+### Minor Changes
+
+- [#181](https://github.com/linked-fw/server/pull/181) [`059dd58`](https://github.com/linked-fw/server/commit/059dd584bc95efac30ba5e9831b69a9931236690) Thanks [@flyon](https://github.com/flyon)! - Query-plane shape catalog hook: `setQueryCatalogResolver(resolver)` in `@_linked/server/utils/queryPlane` lets the host supply the `ShapeCatalog` each generic query request (`/call/@_linked/server/*Query`, `/api/*`) is decoded in. The access check and the store lower the query in that catalog. A resolver that throws a `ServerCallError` answers with its status; any other throw answers 500 `Shape catalog unavailable`. Without a resolver, behaviour is unchanged. Requires `@_linked/core` 2.35.0.
+
 ## 3.0.0
 
 ### Major Changes

package/lib/esm/backend.js

@@ -12,7 +12,7 @@ import { callable } from '@_linked/server-utils/utils/callable';
 import { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';
 import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
 import { LocalFileStore } from './shapes/filestores/LocalFileStore.js';
-import { authorizeGenericQuery, toQueryBuilder } from './utils/queryPlane.js';
+import { authorizeGenericQuery, resolveQueryCatalog, toQueryBuilder, } from './utils/queryPlane.js';
 import path from 'path';
 import fs from 'fs/promises';
 export default class LincdServerBackendProvider extends BackendProvider {
@@ -48,7 +48,8 @@ export default class LincdServerBackendProvider extends BackendProvider {
     // A query cannot cross the wire live, so the client ships `toJSON()` and `fromJSON()`
     // rehydrates it here into a live, closed query. `LinkedStorage` then routes it by the
     // QUERY's shape, which is what decides the target dataset; the store instance never
-    // participates.
+    // participates. The host's catalog resolver (`setQueryCatalogResolver`) picks the shape
+    // catalog the JSON is decoded in; the builder keeps it for both lowerings.
     //
     // Every query is checked first against the access rules of the stores it
     // maps to, declared in the app's storage config (`withAccess`; a store with
@@ -57,27 +58,27 @@ export default class LincdServerBackendProvider extends BackendProvider {
     // 'public' because that check, not the RPC layer, decides whether a session
     // is required.
     async selectQuery(json) {
-        const query = toQueryBuilder(json);
+        const query = toQueryBuilder(json, await resolveQueryCatalog(json));
         await authorizeGenericQuery('select', json, query, 'selectQuery');
         return LinkedStorage.selectQuery(query);
     }
     async askQuery(json) {
-        const query = toQueryBuilder(json);
+        const query = toQueryBuilder(json, await resolveQueryCatalog(json));
         await authorizeGenericQuery('ask', json, query, 'askQuery');
         return LinkedStorage.askQuery(query);
     }
     async updateQuery(json) {
-        const query = toQueryBuilder(json);
+        const query = toQueryBuilder(json, await resolveQueryCatalog(json));
         await authorizeGenericQuery('update', json, query, 'updateQuery');
         return LinkedStorage.updateQuery(query);
     }
     async createQuery(json) {
-        const query = toQueryBuilder(json);
+        const query = toQueryBuilder(json, await resolveQueryCatalog(json));
         await authorizeGenericQuery('create', json, query, 'createQuery');
         return LinkedStorage.createQuery(query);
     }
     async deleteQuery(json) {
-        const query = toQueryBuilder(json);
+        const query = toQueryBuilder(json, await resolveQueryCatalog(json));
         await authorizeGenericQuery('delete', json, query, 'deleteQuery');
         return LinkedStorage.deleteQuery(query);
     }

package/lib/esm/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';\nimport { callable } from '@_linked/server-utils/utils/callable';\nimport { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { LocalFileStore } from './shapes/filestores/LocalFileStore.js';\nimport { authorizeGenericQuery, toQueryBuilder } from './utils/queryPlane.js';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nexport default class LincdServerBackendProvider extends BackendProvider {\n  async setupBeforeControllers() {\n    if (!LinkedFileStorage.getDefaultStore()) {\n      LinkedFileStorage.setDefaultStore(\n        new LocalFileStore(process.env.NODE_ENV + '-filestore')\n      );\n    }\n    let fileSystemUploadPath = path.join('data', 'filestores');\n    try {\n      await fs.access(fileSystemUploadPath);\n    } catch (err) {\n      await fs.mkdir(path.join(fileSystemUploadPath, 'filestores'), {\n        recursive: true,\n      });\n    }\n  }\n\n  /**\n   * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes\n   * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;\n   * a host that serves the wire with tokens answers 401 for a refused one.\n   */\n  @callable('public')\n  async ping(): Promise<{ ok: true }> {\n    return { ok: true };\n  }\n\n  // ── Generic query execution ──────────────────────────────────────────────\n  //\n  // These answer `RemoteDataset`: a browser's store calls\n  // `Server.call(packageName, {method}, json)` (the PACKAGE form), and a remote app's store\n  // posts the same `{args}` body to `{url}/call/@_linked/server/<method>`. Either way the\n  // request arrives here on the generic provider rather than through Shape resolution.\n  //\n  // A query cannot cross the wire live, so the client ships `toJSON()` and `fromJSON()`\n  // rehydrates it here into a live, closed query. `LinkedStorage` then routes it by the\n  // QUERY's shape, which is what decides the target dataset; the store instance never\n  // participates.\n  //\n  // Every query is checked first against the access rules of the stores it\n  // maps to, declared in the app's storage config (`withAccess`; a store with\n  // no rule requires a session): see utils/queryPlane. INTERIM model, to be\n  // rethought. The store runs the builder that was checked. They are declared\n  // 'public' because that check, not the RPC layer, decides whether a session\n  // is required.\n\n  @callable('public')\n  async selectQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('select', json, query, 'selectQuery');\n    return LinkedStorage.selectQuery(query);\n  }\n\n  @callable('public')\n  async askQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('ask', json, query, 'askQuery');\n    return LinkedStorage.askQuery(query);\n  }\n\n  @callable('public')\n  async updateQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('update', json, query, 'updateQuery');\n    return LinkedStorage.updateQuery(query);\n  }\n\n  @callable('public')\n  async createQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('create', json, query, 'createQuery');\n    return LinkedStorage.createQuery(query);\n  }\n\n  @callable('public')\n  async deleteQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('delete', json, query, 'deleteQuery');\n    return LinkedStorage.deleteQuery(query);\n  }\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';\nimport { callable } from '@_linked/server-utils/utils/callable';\nimport { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { LocalFileStore } from './shapes/filestores/LocalFileStore.js';\nimport {\n  authorizeGenericQuery,\n  resolveQueryCatalog,\n  toQueryBuilder,\n} from './utils/queryPlane.js';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nexport default class LincdServerBackendProvider extends BackendProvider {\n  async setupBeforeControllers() {\n    if (!LinkedFileStorage.getDefaultStore()) {\n      LinkedFileStorage.setDefaultStore(\n        new LocalFileStore(process.env.NODE_ENV + '-filestore')\n      );\n    }\n    let fileSystemUploadPath = path.join('data', 'filestores');\n    try {\n      await fs.access(fileSystemUploadPath);\n    } catch (err) {\n      await fs.mkdir(path.join(fileSystemUploadPath, 'filestores'), {\n        recursive: true,\n      });\n    }\n  }\n\n  /**\n   * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes\n   * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;\n   * a host that serves the wire with tokens answers 401 for a refused one.\n   */\n  @callable('public')\n  async ping(): Promise<{ ok: true }> {\n    return { ok: true };\n  }\n\n  // ── Generic query execution ──────────────────────────────────────────────\n  //\n  // These answer `RemoteDataset`: a browser's store calls\n  // `Server.call(packageName, {method}, json)` (the PACKAGE form), and a remote app's store\n  // posts the same `{args}` body to `{url}/call/@_linked/server/<method>`. Either way the\n  // request arrives here on the generic provider rather than through Shape resolution.\n  //\n  // A query cannot cross the wire live, so the client ships `toJSON()` and `fromJSON()`\n  // rehydrates it here into a live, closed query. `LinkedStorage` then routes it by the\n  // QUERY's shape, which is what decides the target dataset; the store instance never\n  // participates. The host's catalog resolver (`setQueryCatalogResolver`) picks the shape\n  // catalog the JSON is decoded in; the builder keeps it for both lowerings.\n  //\n  // Every query is checked first against the access rules of the stores it\n  // maps to, declared in the app's storage config (`withAccess`; a store with\n  // no rule requires a session): see utils/queryPlane. INTERIM model, to be\n  // rethought. The store runs the builder that was checked. They are declared\n  // 'public' because that check, not the RPC layer, decides whether a session\n  // is required.\n\n  @callable('public')\n  async selectQuery(json: any) {\n    const query = toQueryBuilder(json, await resolveQueryCatalog(json));\n    await authorizeGenericQuery('select', json, query, 'selectQuery');\n    return LinkedStorage.selectQuery(query);\n  }\n\n  @callable('public')\n  async askQuery(json: any) {\n    const query = toQueryBuilder(json, await resolveQueryCatalog(json));\n    await authorizeGenericQuery('ask', json, query, 'askQuery');\n    return LinkedStorage.askQuery(query);\n  }\n\n  @callable('public')\n  async updateQuery(json: any) {\n    const query = toQueryBuilder(json, await resolveQueryCatalog(json));\n    await authorizeGenericQuery('update', json, query, 'updateQuery');\n    return LinkedStorage.updateQuery(query);\n  }\n\n  @callable('public')\n  async createQuery(json: any) {\n    const query = toQueryBuilder(json, await resolveQueryCatalog(json));\n    await authorizeGenericQuery('create', json, query, 'createQuery');\n    return LinkedStorage.createQuery(query);\n  }\n\n  @callable('public')\n  async deleteQuery(json: any) {\n    const query = toQueryBuilder(json, await resolveQueryCatalog(json));\n    await authorizeGenericQuery('delete', json, query, 'deleteQuery');\n    return LinkedStorage.deleteQuery(query);\n  }\n}\n"]}

package/lib/esm/shapes/LincdAPI.js

@@ -10,7 +10,7 @@ import { server } from '../ontologies/server.js';
 import { JSONParser } from '@_linked/server-utils/utils/JSONParser';
 import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
 import { JSONWriter } from '@_linked/server-utils/utils/JSONWriter';
-import { authorizeGenericQuery, authorizeRawQuery, toQueryBuilder, } from '../utils/queryPlane.js';
+import { authorizeGenericQuery, authorizeRawQuery, resolveQueryCatalog, toQueryBuilder, } from '../utils/queryPlane.js';
 import { getRpcExposureMode } from '../utils/rpcExposure.js';
 /** An error carrying an HTTP status, such as a `ServerCallError` (401/403). */
 function isStatusError(error) {
@@ -56,22 +56,22 @@ let LincdAPI = class LincdAPI extends Shape {
         }
     }
     async post_select({ query }) {
-        const builder = toQueryBuilder(query);
+        const builder = toQueryBuilder(query, await resolveQueryCatalog(query));
         await authorizeGenericQuery('select', query, builder, 'api/select');
         return LinkedStorage.selectQuery(builder);
     }
     async post_create({ query }) {
-        const builder = toQueryBuilder(query);
+        const builder = toQueryBuilder(query, await resolveQueryCatalog(query));
         await authorizeGenericQuery('create', query, builder, 'api/create');
         return LinkedStorage.createQuery(builder);
     }
     async post_update({ query }) {
-        const builder = toQueryBuilder(query);
+        const builder = toQueryBuilder(query, await resolveQueryCatalog(query));
         await authorizeGenericQuery('update', query, builder, 'api/update');
         return LinkedStorage.updateQuery(builder);
     }
     async post_delete({ query }) {
-        const builder = toQueryBuilder(query);
+        const builder = toQueryBuilder(query, await resolveQueryCatalog(query));
         await authorizeGenericQuery('delete', query, builder, 'api/delete');
         return LinkedStorage.deleteQuery(builder);
     }

package/lib/esm/shapes/LincdAPI.js.map

@@ -1 +1 @@
-{"version":3,"file":"LincdAPI.js","sourceRoot":"","sources":["../../../src/shapes/LincdAPI.ts"],"names":[],"mappings":"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","sourcesContent":["import { Shape } from '@_linked/core/shapes/Shape';\nimport { linkedShape } from '../package.js';\nimport { server } from '../ontologies/server.js';\nimport { JSONParser } from '@_linked/server-utils/utils/JSONParser';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { JSONWriter } from '@_linked/server-utils/utils/JSONWriter';\nimport { SparqlDataset as SPARQLStore } from '@_linked/core/sparql/SparqlDataset';\nimport {\n  authorizeGenericQuery,\n  authorizeRawQuery,\n  toQueryBuilder,\n} from '../utils/queryPlane.js';\nimport { getRpcExposureMode } from '../utils/rpcExposure.js';\n\n/** An error carrying an HTTP status, such as a `ServerCallError` (401/403). */\nfunction isStatusError(error: any): error is { status: number; message: string } {\n  return (\n    !!error &&\n    typeof error.status === 'number' &&\n    error.status >= 400 &&\n    error.status < 600 &&\n    error.name === 'ServerCallError'\n  );\n}\n\n// Named explicitly: tsc emits `let X = class X`, and any later esbuild pass over that JS (Vite's\n// SSR `define` replacement runs one on every file mentioning a defined `process.env.*`) renames\n// the inner binding to `X2`, which would otherwise become this shape's IRI.\n@linkedShape({name: 'LincdAPI'})\nexport class LincdAPI extends Shape {\n  static targetClass = server.LincdAPI;\n\n  async process(\n    request,\n    response,\n    httpMethod: 'get' | 'post' | 'put' | 'delete'\n  ) {\n    let { method, action } = request.params;\n    const body = JSONParser.parseObject<any>(request.body, {\n      shapeClasses: getRpcExposureMode() === 'enforce' ? 'reject' : 'warn',\n    });\n\n    //replace - with _ in action names\n    let localMethod = httpMethod + '_' + method.replace(/-/g, '_');\n    if (typeof this[localMethod] !== 'function') {\n      throw new Error('Unknown method: ' + localMethod);\n    }\n\n    // The query routes (`post_*`) check access themselves, through\n    // utils/queryPlane.\n    try {\n      const result = await this[localMethod](body, request, response);\n      if (typeof result !== 'undefined' || !response.headersSent) {\n        const jsonObject = JSONWriter.toJsObject(result);\n        response.json(jsonObject);\n      }\n    } catch (error) {\n      if (!response.headersSent && isStatusError(error)) {\n        response.status(error.status).json({ error: error.message });\n        return;\n      }\n      console.error(`Error while processing ${localMethod}:`, error);\n      if (!response.headersSent) {\n        const message =\n          error instanceof Error ? error.message : 'Unknown server error';\n        response.status(500).json({ error: message });\n      }\n    }\n  }\n\n  async post_select({ query }) {\n    const builder = toQueryBuilder(query);\n    await authorizeGenericQuery('select', query, builder, 'api/select');\n    return LinkedStorage.selectQuery(builder);\n  }\n  async post_create({ query }) {\n    const builder = toQueryBuilder(query);\n    await authorizeGenericQuery('create', query, builder, 'api/create');\n    return LinkedStorage.createQuery(builder);\n  }\n  async post_update({ query }) {\n    const builder = toQueryBuilder(query);\n    await authorizeGenericQuery('update', query, builder, 'api/update');\n    return LinkedStorage.updateQuery(builder);\n  }\n  async post_delete({ query }) {\n    const builder = toQueryBuilder(query);\n    await authorizeGenericQuery('delete', query, builder, 'api/delete');\n    return LinkedStorage.deleteQuery(builder);\n  }\n\n  async post_select_raw({ query }) {\n    // A raw SPARQL string cannot be analysed for the shapes it touches: the\n    // `rawQueries` setting decides (a session by default, or off).\n    await authorizeRawQuery(query, 'api/select-raw');\n    this.checkRawQuerySupport();\n    return (LinkedStorage.getDefaultDataset() as unknown as SPARQLStore).rawQuery(\n      query\n    );\n  }\n\n  private checkRawQuerySupport() {\n    if (!(LinkedStorage.getDefaultDataset() as unknown as SPARQLStore).rawQuery) {\n      throw new Error(\n        `Default store (${\n          Object.getPrototypeOf(LinkedStorage.getDefaultDataset()).constructor\n            .name\n        }) does not support raw SPARQL queries`\n      );\n    }\n  }\n}\n"]}
+{"version":3,"file":"LincdAPI.js","sourceRoot":"","sources":["../../../src/shapes/LincdAPI.ts"],"names":[],"mappings":"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","sourcesContent":["import { Shape } from '@_linked/core/shapes/Shape';\nimport { linkedShape } from '../package.js';\nimport { server } from '../ontologies/server.js';\nimport { JSONParser } from '@_linked/server-utils/utils/JSONParser';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { JSONWriter } from '@_linked/server-utils/utils/JSONWriter';\nimport { SparqlDataset as SPARQLStore } from '@_linked/core/sparql/SparqlDataset';\nimport {\n  authorizeGenericQuery,\n  authorizeRawQuery,\n  resolveQueryCatalog,\n  toQueryBuilder,\n} from '../utils/queryPlane.js';\nimport { getRpcExposureMode } from '../utils/rpcExposure.js';\n\n/** An error carrying an HTTP status, such as a `ServerCallError` (401/403). */\nfunction isStatusError(error: any): error is { status: number; message: string } {\n  return (\n    !!error &&\n    typeof error.status === 'number' &&\n    error.status >= 400 &&\n    error.status < 600 &&\n    error.name === 'ServerCallError'\n  );\n}\n\n// Named explicitly: tsc emits `let X = class X`, and any later esbuild pass over that JS (Vite's\n// SSR `define` replacement runs one on every file mentioning a defined `process.env.*`) renames\n// the inner binding to `X2`, which would otherwise become this shape's IRI.\n@linkedShape({name: 'LincdAPI'})\nexport class LincdAPI extends Shape {\n  static targetClass = server.LincdAPI;\n\n  async process(\n    request,\n    response,\n    httpMethod: 'get' | 'post' | 'put' | 'delete'\n  ) {\n    let { method, action } = request.params;\n    const body = JSONParser.parseObject<any>(request.body, {\n      shapeClasses: getRpcExposureMode() === 'enforce' ? 'reject' : 'warn',\n    });\n\n    //replace - with _ in action names\n    let localMethod = httpMethod + '_' + method.replace(/-/g, '_');\n    if (typeof this[localMethod] !== 'function') {\n      throw new Error('Unknown method: ' + localMethod);\n    }\n\n    // The query routes (`post_*`) check access themselves, through\n    // utils/queryPlane.\n    try {\n      const result = await this[localMethod](body, request, response);\n      if (typeof result !== 'undefined' || !response.headersSent) {\n        const jsonObject = JSONWriter.toJsObject(result);\n        response.json(jsonObject);\n      }\n    } catch (error) {\n      if (!response.headersSent && isStatusError(error)) {\n        response.status(error.status).json({ error: error.message });\n        return;\n      }\n      console.error(`Error while processing ${localMethod}:`, error);\n      if (!response.headersSent) {\n        const message =\n          error instanceof Error ? error.message : 'Unknown server error';\n        response.status(500).json({ error: message });\n      }\n    }\n  }\n\n  async post_select({ query }) {\n    const builder = toQueryBuilder(query, await resolveQueryCatalog(query));\n    await authorizeGenericQuery('select', query, builder, 'api/select');\n    return LinkedStorage.selectQuery(builder);\n  }\n  async post_create({ query }) {\n    const builder = toQueryBuilder(query, await resolveQueryCatalog(query));\n    await authorizeGenericQuery('create', query, builder, 'api/create');\n    return LinkedStorage.createQuery(builder);\n  }\n  async post_update({ query }) {\n    const builder = toQueryBuilder(query, await resolveQueryCatalog(query));\n    await authorizeGenericQuery('update', query, builder, 'api/update');\n    return LinkedStorage.updateQuery(builder);\n  }\n  async post_delete({ query }) {\n    const builder = toQueryBuilder(query, await resolveQueryCatalog(query));\n    await authorizeGenericQuery('delete', query, builder, 'api/delete');\n    return LinkedStorage.deleteQuery(builder);\n  }\n\n  async post_select_raw({ query }) {\n    // A raw SPARQL string cannot be analysed for the shapes it touches: the\n    // `rawQueries` setting decides (a session by default, or off).\n    await authorizeRawQuery(query, 'api/select-raw');\n    this.checkRawQuerySupport();\n    return (LinkedStorage.getDefaultDataset() as unknown as SPARQLStore).rawQuery(\n      query\n    );\n  }\n\n  private checkRawQuerySupport() {\n    if (!(LinkedStorage.getDefaultDataset() as unknown as SPARQLStore).rawQuery) {\n      throw new Error(\n        `Default store (${\n          Object.getPrototypeOf(LinkedStorage.getDefaultDataset()).constructor\n            .name\n        }) does not support raw SPARQL queries`\n      );\n    }\n  }\n}\n"]}

package/lib/esm/shapes/quadstores/RemoteDataset.d.ts

@@ -46,6 +46,12 @@ export declare class RemoteDatasetUnreachableError extends RemoteDatasetError {
 /** The data server answered 401 or 403: it refused this dataset's token. */
 export declare class RemoteDatasetUnauthorizedError extends RemoteDatasetError {
 }
+/**
+ * What the data server's `ping` answered, as is. The generic `@_linked/server` ping answers
+ * `{ok: true}`; a gateway may add fields that say which dataset it serves, such as
+ * `{ok, projectId, branchName, dataset, forked}`. A body that is not a JSON object reads as `{}`.
+ */
+export type RemoteDatasetPingInfo = Readonly<Record<string, unknown>>;
 /**
  * An {@link IDataset} whose queries are answered by a linked server.
  *
@@ -64,7 +70,8 @@ export declare class RemoteDatasetUnauthorizedError extends RemoteDatasetError {
  * store instance crosses the wire. Query routing is decided by the query's shape.
  *
  * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
- * fail loudly awaits `init()` itself first; a successful `init()` is memoized.
+ * fail loudly awaits `init()` itself first; a successful `init()` is memoized, and resolves
+ * the ping body (also readable as `info`), so a boot can log which dataset the server serves.
  */
 export declare class RemoteDataset implements IDataset {
     /**
@@ -76,8 +83,18 @@ export declare class RemoteDataset implements IDataset {
     readonly url?: string;
     private readonly token?;
     private initialized?;
+    private pingInfo?;
     constructor(config?: RemoteDatasetConfig | string);
-    init(): Promise<void>;
+    /**
+     * The body of the last successful `ping` (see {@link init}); undefined before one, and
+     * always in the no-url form.
+     */
+    get info(): RemoteDatasetPingInfo | undefined;
+    /**
+     * In the url form, asks the server's `ping` and resolves its body (also kept as
+     * {@link info}); resolves undefined in the no-url form.
+     */
+    init(): Promise<RemoteDatasetPingInfo | undefined>;
     selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;
     askQuery(query: AskQuery): Promise<boolean>;
     updateQuery(query: UpdateQuery): Promise<UpdateResult>;

package/lib/esm/shapes/quadstores/RemoteDataset.js

@@ -43,7 +43,8 @@ const PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);
  * store instance crosses the wire. Query routing is decided by the query's shape.
  *
  * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
- * fail loudly awaits `init()` itself first; a successful `init()` is memoized.
+ * fail loudly awaits `init()` itself first; a successful `init()` is memoized, and resolves
+ * the ping body (also readable as `info`), so a boot can log which dataset the server serves.
  */
 export class RemoteDataset {
     constructor(config) {
@@ -67,12 +68,29 @@ export class RemoteDataset {
             this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;
         }
     }
+    /**
+     * The body of the last successful `ping` (see {@link init}); undefined before one, and
+     * always in the no-url form.
+     */
+    get info() {
+        return this.pingInfo;
+    }
+    /**
+     * In the url form, asks the server's `ping` and resolves its body (also kept as
+     * {@link info}); resolves undefined in the no-url form.
+     */
     init() {
         // No initialization needed when queries are routed to the app's own backend.
         if (this.url === undefined)
-            return Promise.resolve();
+            return Promise.resolve(undefined);
         if (!this.initialized) {
-            this.initialized = this.post('ping', []).then(() => undefined, (err) => {
+            this.initialized = this.post('ping', []).then((body) => {
+                const info = Object.freeze(body && typeof body === 'object' && !Array.isArray(body)
+                    ? { ...body }
+                    : {});
+                this.pingInfo = info;
+                return info;
+            }, (err) => {
                 // Not memoized: the next init() asks again.
                 this.initialized = undefined;
                 throw err;

package/lib/esm/shapes/quadstores/RemoteDataset.js.map

@@ -1 +1 @@
-{"version":3,"file":"RemoteDataset.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/RemoteDataset.ts"],"names":[],"mappings":"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","sourcesContent":["import { packageName } from '../../package.js';\nimport { Server } from '@_linked/server-utils/utils/Server';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport type { SelectQuery } from '@_linked/core/queries/SelectQuery';\nimport type { CountQuery } from '@_linked/core/queries/CountQuery';\nimport type { AskQuery } from '@_linked/core/queries/AskQuery';\nimport type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';\nimport type { CreateQuery } from '@_linked/core/queries/CreateQuery';\nimport type {\n  DeleteQuery,\n  DeleteResponse,\n} from '@_linked/core/queries/DeleteQuery';\nimport type {\n  SelectResult,\n  UpdateResult,\n  CreateResult,\n} from '@_linked/core/queries/IntermediateRepresentation';\n\n/**\n * Constructor argument for `new RemoteDataset(config)`: the `config` object of a\n * `linked.{frontend,backend}.datasets.json` entry, passed verbatim.\n */\nexport interface RemoteDatasetConfig {\n  /**\n   * Base URL of the data server, e.g. `http://localhost:4040/gateway`; routes are appended\n   * to it. Without it, queries go to this process's own backend through `Server.call`.\n   * Present but empty is an error, never the no-url form.\n   */\n  url?: string;\n  /** Sent as `Authorization: Bearer <token>` when set and `url` is set. */\n  token?: string;\n  /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */\n  name?: string;\n  /** Or pass a fully-qualified URI directly. */\n  id?: string;\n}\n\n/**\n * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP\n * answer came back); `code` is the error body's `code` when the server sent one.\n */\nexport class RemoteDatasetError extends Error {\n  /** The data server base url ('' when the configured url is empty). */\n  readonly url: string;\n  /** The HTTP status; 0 = no HTTP answer. */\n  readonly status: number;\n  /** The error body's `code`, when the server sent one. */\n  readonly code?: string;\n\n  constructor(message: string, url: string, status: number, code?: string) {\n    super(message);\n    this.name = new.target.name;\n    this.url = url;\n    this.status = status;\n    if (code !== undefined) this.code = code;\n  }\n}\n\n/**\n * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an\n * answer that is not the server's. A boot that gets this should stop.\n */\nexport class RemoteDatasetUnreachableError extends RemoteDatasetError {}\n\n/** The data server answered 401 or 403: it refused this dataset's token. */\nexport class RemoteDatasetUnauthorizedError extends RemoteDatasetError {}\n\ntype Method =\n  | 'ping'\n  | 'selectQuery'\n  | 'askQuery'\n  | 'updateQuery'\n  | 'createQuery'\n  | 'deleteQuery';\n\n/** On `ping`, these statuses mean nothing at that url serves the query wire. */\nconst PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);\n\n/**\n * An {@link IDataset} whose queries are answered by a linked server.\n *\n * - **Without `url`** the server is this app's own backend: every query goes through\n *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),\n *   and on a backend `Server`'s local shortcut answers it in process. This is the store a\n *   browser uses to talk to its backend.\n * - **With `url`** the server is a remote data server: every query posts\n *   `{\"args\": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer\n *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the\n *   app's own provider) and never retried (a retried write could apply twice). `init()` asks\n *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or\n *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.\n *\n * A store is not a Shape: it addresses the backend by package name, so nothing about the\n * store instance crosses the wire. Query routing is decided by the query's shape.\n *\n * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must\n * fail loudly awaits `init()` itself first; a successful `init()` is memoized.\n */\nexport class RemoteDataset implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named; it is not an\n   * addressing mechanism, nothing transmits or resolves it.\n   */\n  readonly id?: string;\n  /** The data server base url, trailing slashes trimmed; undefined in the no-url form. */\n  readonly url?: string;\n  private readonly token?: string;\n  private initialized?: Promise<void>;\n\n  constructor(config?: RemoteDatasetConfig | string) {\n    if (!config) return;\n    if (typeof config === 'string') {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;\n      return;\n    }\n    if (typeof config.url === 'string') {\n      this.url = config.url.trim().replace(/\\/+$/, '');\n      const token = typeof config.token === 'string' ? config.token.trim() : '';\n      if (token) this.token = token;\n    }\n    if (config.id) {\n      this.id = config.id;\n      return;\n    }\n    if (config.name) {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;\n    }\n  }\n\n  init(): Promise<void> {\n    // No initialization needed when queries are routed to the app's own backend.\n    if (this.url === undefined) return Promise.resolve();\n    if (!this.initialized) {\n      this.initialized = this.post('ping', []).then(\n        () => undefined,\n        (err) => {\n          // Not memoized: the next init() asks again.\n          this.initialized = undefined;\n          throw err;\n        },\n      );\n    }\n    return this.initialized;\n  }\n\n  // Queries serialize to DSL-JSON for the wire: the live (closed) query can't cross a call\n  // as-is, so we ship `toJSON()` and the server's generic provider rehydrates it with\n  // `fromJSON()`.\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number> {\n    return this.call('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.call('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.call('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.call('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.call('deleteQuery', query.toJSON());\n  }\n\n  private call<T>(method: Method, json: unknown): Promise<T> {\n    if (this.url === undefined) return this.callBackend(method, json);\n    return this.post(method, [json]) as Promise<T>;\n  }\n\n  /**\n   * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no\n   * provider on the backend) rejects with a `ServerCallError` carrying the\n   * status and the server's message instead of reading as an empty result.\n   * Whatever a successful call returns, `undefined` included, resolves as is.\n   */\n  private callBackend<T>(method: string, json: unknown): Promise<T> {\n    // The PACKAGE form, not the shape form. It posts to\n    // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,\n    // no `instanceNode` — and the backend answers from this package's generic\n    // provider without resolving or instantiating any Shape.\n    return Server.call(packageName, { method, rejectOnError: true }, json);\n  }\n\n  /**\n   * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed\n   * body (`null` is a valid result: a method that returned `undefined`). Messages name the\n   * url and the method, never the token.\n   */\n  private async post(method: Method, args: unknown[]): Promise<unknown> {\n    const base = this.url ?? '';\n    if (!base) {\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: no data server url is set (the configured url is empty); cannot ${method}`,\n        '',\n        0,\n      );\n    }\n    const target = `${base}/call/${packageName}/${method}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    };\n    if (this.token) headers.Authorization = `Bearer ${this.token}`;\n\n    let response: Response;\n    try {\n      response = await globalThis.fetch(target, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify({ args }),\n      });\n    } catch (err) {\n      const cause = err instanceof Error ? err.message : String(err);\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: cannot reach the data server at ${base} (${method}): ${cause}`,\n        base,\n        0,\n      );\n    }\n\n    const text = await response.text();\n    let body: unknown = undefined;\n    let isJson = false;\n    if (text) {\n      try {\n        body = JSON.parse(text);\n        isJson = true;\n      } catch {\n        body = text;\n      }\n    }\n\n    if (response.ok) {\n      if (isJson) return body;\n      if (method === 'ping') {\n        throw new RemoteDatasetUnreachableError(\n          `RemoteDataset: the data server at ${base} answered ping with a body that is not JSON`,\n          base,\n          response.status,\n        );\n      }\n      if (!text) return undefined;\n      throw new RemoteDatasetError(\n        `RemoteDataset: the data server at ${base} answered ${method} with a body that is not JSON`,\n        base,\n        response.status,\n      );\n    }\n\n    const record = body && typeof body === 'object' ? (body as Record<string, unknown>) : undefined;\n    const code = typeof record?.code === 'string' ? record.code : undefined;\n    const detail =\n      typeof record?.error === 'string'\n        ? record.error\n        : typeof body === 'string' && body\n          ? body\n          : response.statusText;\n    const message = `RemoteDataset: the data server at ${base} answered ${method} with ${response.status}${\n      code ? ` (${code})` : ''\n    }${detail ? `: ${detail}` : ''}`;\n\n    if (response.status === 401 || response.status === 403) {\n      throw new RemoteDatasetUnauthorizedError(message, base, response.status, code);\n    }\n    if (method === 'ping' && (PING_UNREACHABLE_STATUSES.has(response.status) || !isJson)) {\n      throw new RemoteDatasetUnreachableError(message, base, response.status, code);\n    }\n    throw new RemoteDatasetError(message, base, response.status, code);\n  }\n}\n"]}
+{"version":3,"file":"RemoteDataset.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/RemoteDataset.ts"],"names":[],"mappings":"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","sourcesContent":["import { packageName } from '../../package.js';\nimport { Server } from '@_linked/server-utils/utils/Server';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport type { SelectQuery } from '@_linked/core/queries/SelectQuery';\nimport type { CountQuery } from '@_linked/core/queries/CountQuery';\nimport type { AskQuery } from '@_linked/core/queries/AskQuery';\nimport type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';\nimport type { CreateQuery } from '@_linked/core/queries/CreateQuery';\nimport type {\n  DeleteQuery,\n  DeleteResponse,\n} from '@_linked/core/queries/DeleteQuery';\nimport type {\n  SelectResult,\n  UpdateResult,\n  CreateResult,\n} from '@_linked/core/queries/IntermediateRepresentation';\n\n/**\n * Constructor argument for `new RemoteDataset(config)`: the `config` object of a\n * `linked.{frontend,backend}.datasets.json` entry, passed verbatim.\n */\nexport interface RemoteDatasetConfig {\n  /**\n   * Base URL of the data server, e.g. `http://localhost:4040/gateway`; routes are appended\n   * to it. Without it, queries go to this process's own backend through `Server.call`.\n   * Present but empty is an error, never the no-url form.\n   */\n  url?: string;\n  /** Sent as `Authorization: Bearer <token>` when set and `url` is set. */\n  token?: string;\n  /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */\n  name?: string;\n  /** Or pass a fully-qualified URI directly. */\n  id?: string;\n}\n\n/**\n * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP\n * answer came back); `code` is the error body's `code` when the server sent one.\n */\nexport class RemoteDatasetError extends Error {\n  /** The data server base url ('' when the configured url is empty). */\n  readonly url: string;\n  /** The HTTP status; 0 = no HTTP answer. */\n  readonly status: number;\n  /** The error body's `code`, when the server sent one. */\n  readonly code?: string;\n\n  constructor(message: string, url: string, status: number, code?: string) {\n    super(message);\n    this.name = new.target.name;\n    this.url = url;\n    this.status = status;\n    if (code !== undefined) this.code = code;\n  }\n}\n\n/**\n * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an\n * answer that is not the server's. A boot that gets this should stop.\n */\nexport class RemoteDatasetUnreachableError extends RemoteDatasetError {}\n\n/** The data server answered 401 or 403: it refused this dataset's token. */\nexport class RemoteDatasetUnauthorizedError extends RemoteDatasetError {}\n\n/**\n * What the data server's `ping` answered, as is. The generic `@_linked/server` ping answers\n * `{ok: true}`; a gateway may add fields that say which dataset it serves, such as\n * `{ok, projectId, branchName, dataset, forked}`. A body that is not a JSON object reads as `{}`.\n */\nexport type RemoteDatasetPingInfo = Readonly<Record<string, unknown>>;\n\ntype Method =\n  | 'ping'\n  | 'selectQuery'\n  | 'askQuery'\n  | 'updateQuery'\n  | 'createQuery'\n  | 'deleteQuery';\n\n/** On `ping`, these statuses mean nothing at that url serves the query wire. */\nconst PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);\n\n/**\n * An {@link IDataset} whose queries are answered by a linked server.\n *\n * - **Without `url`** the server is this app's own backend: every query goes through\n *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),\n *   and on a backend `Server`'s local shortcut answers it in process. This is the store a\n *   browser uses to talk to its backend.\n * - **With `url`** the server is a remote data server: every query posts\n *   `{\"args\": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer\n *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the\n *   app's own provider) and never retried (a retried write could apply twice). `init()` asks\n *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or\n *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.\n *\n * A store is not a Shape: it addresses the backend by package name, so nothing about the\n * store instance crosses the wire. Query routing is decided by the query's shape.\n *\n * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must\n * fail loudly awaits `init()` itself first; a successful `init()` is memoized, and resolves\n * the ping body (also readable as `info`), so a boot can log which dataset the server serves.\n */\nexport class RemoteDataset implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named; it is not an\n   * addressing mechanism, nothing transmits or resolves it.\n   */\n  readonly id?: string;\n  /** The data server base url, trailing slashes trimmed; undefined in the no-url form. */\n  readonly url?: string;\n  private readonly token?: string;\n  private initialized?: Promise<RemoteDatasetPingInfo | undefined>;\n  private pingInfo?: RemoteDatasetPingInfo;\n\n  constructor(config?: RemoteDatasetConfig | string) {\n    if (!config) return;\n    if (typeof config === 'string') {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;\n      return;\n    }\n    if (typeof config.url === 'string') {\n      this.url = config.url.trim().replace(/\\/+$/, '');\n      const token = typeof config.token === 'string' ? config.token.trim() : '';\n      if (token) this.token = token;\n    }\n    if (config.id) {\n      this.id = config.id;\n      return;\n    }\n    if (config.name) {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;\n    }\n  }\n\n  /**\n   * The body of the last successful `ping` (see {@link init}); undefined before one, and\n   * always in the no-url form.\n   */\n  get info(): RemoteDatasetPingInfo | undefined {\n    return this.pingInfo;\n  }\n\n  /**\n   * In the url form, asks the server's `ping` and resolves its body (also kept as\n   * {@link info}); resolves undefined in the no-url form.\n   */\n  init(): Promise<RemoteDatasetPingInfo | undefined> {\n    // No initialization needed when queries are routed to the app's own backend.\n    if (this.url === undefined) return Promise.resolve(undefined);\n    if (!this.initialized) {\n      this.initialized = this.post('ping', []).then(\n        (body) => {\n          const info: RemoteDatasetPingInfo = Object.freeze(\n            body && typeof body === 'object' && !Array.isArray(body)\n              ? { ...(body as Record<string, unknown>) }\n              : {},\n          );\n          this.pingInfo = info;\n          return info;\n        },\n        (err) => {\n          // Not memoized: the next init() asks again.\n          this.initialized = undefined;\n          throw err;\n        },\n      );\n    }\n    return this.initialized;\n  }\n\n  // Queries serialize to DSL-JSON for the wire: the live (closed) query can't cross a call\n  // as-is, so we ship `toJSON()` and the server's generic provider rehydrates it with\n  // `fromJSON()`.\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number> {\n    return this.call('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.call('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.call('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.call('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.call('deleteQuery', query.toJSON());\n  }\n\n  private call<T>(method: Method, json: unknown): Promise<T> {\n    if (this.url === undefined) return this.callBackend(method, json);\n    return this.post(method, [json]) as Promise<T>;\n  }\n\n  /**\n   * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no\n   * provider on the backend) rejects with a `ServerCallError` carrying the\n   * status and the server's message instead of reading as an empty result.\n   * Whatever a successful call returns, `undefined` included, resolves as is.\n   */\n  private callBackend<T>(method: string, json: unknown): Promise<T> {\n    // The PACKAGE form, not the shape form. It posts to\n    // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,\n    // no `instanceNode` — and the backend answers from this package's generic\n    // provider without resolving or instantiating any Shape.\n    return Server.call(packageName, { method, rejectOnError: true }, json);\n  }\n\n  /**\n   * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed\n   * body (`null` is a valid result: a method that returned `undefined`). Messages name the\n   * url and the method, never the token.\n   */\n  private async post(method: Method, args: unknown[]): Promise<unknown> {\n    const base = this.url ?? '';\n    if (!base) {\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: no data server url is set (the configured url is empty); cannot ${method}`,\n        '',\n        0,\n      );\n    }\n    const target = `${base}/call/${packageName}/${method}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    };\n    if (this.token) headers.Authorization = `Bearer ${this.token}`;\n\n    let response: Response;\n    try {\n      response = await globalThis.fetch(target, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify({ args }),\n      });\n    } catch (err) {\n      const cause = err instanceof Error ? err.message : String(err);\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: cannot reach the data server at ${base} (${method}): ${cause}`,\n        base,\n        0,\n      );\n    }\n\n    const text = await response.text();\n    let body: unknown = undefined;\n    let isJson = false;\n    if (text) {\n      try {\n        body = JSON.parse(text);\n        isJson = true;\n      } catch {\n        body = text;\n      }\n    }\n\n    if (response.ok) {\n      if (isJson) return body;\n      if (method === 'ping') {\n        throw new RemoteDatasetUnreachableError(\n          `RemoteDataset: the data server at ${base} answered ping with a body that is not JSON`,\n          base,\n          response.status,\n        );\n      }\n      if (!text) return undefined;\n      throw new RemoteDatasetError(\n        `RemoteDataset: the data server at ${base} answered ${method} with a body that is not JSON`,\n        base,\n        response.status,\n      );\n    }\n\n    const record = body && typeof body === 'object' ? (body as Record<string, unknown>) : undefined;\n    const code = typeof record?.code === 'string' ? record.code : undefined;\n    const detail =\n      typeof record?.error === 'string'\n        ? record.error\n        : typeof body === 'string' && body\n          ? body\n          : response.statusText;\n    const message = `RemoteDataset: the data server at ${base} answered ${method} with ${response.status}${\n      code ? ` (${code})` : ''\n    }${detail ? `: ${detail}` : ''}`;\n\n    if (response.status === 401 || response.status === 403) {\n      throw new RemoteDatasetUnauthorizedError(message, base, response.status, code);\n    }\n    if (method === 'ping' && (PING_UNREACHABLE_STATUSES.has(response.status) || !isJson)) {\n      throw new RemoteDatasetUnreachableError(message, base, response.status, code);\n    }\n    throw new RemoteDatasetError(message, base, response.status, code);\n  }\n}\n"]}

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

@@ -1,3 +1,4 @@
+import type { ShapeCatalog } from '@_linked/core/utils/ShapeCatalog';
 import { type QueryOperation } from '@_linked/server-utils/utils/QueryAccess';
 /**
  * Whether DSL-JSON carries a query-context reference (`{"@ctx": name}`) in any
@@ -7,9 +8,34 @@ import { type QueryOperation } from '@_linked/server-utils/utils/QueryAccess';
  */
 export declare function containsContextRef(json: unknown): boolean;
 /**
- * A rehydrated query builder from the DSL-JSON a client sent. The result is
- * what the store runs, so the access check and the store see the same query.
- * A body that is not a query answers 400.
+ * Supplies the shape catalog a generic query request is decoded in, from the
+ * DSL-JSON the client sent (the request context is available through the
+ * host's own means, e.g. `getCallContext`). `undefined` means the global
+ * shape registry.
+ */
+export type QueryCatalogResolver = (query: unknown) => ShapeCatalog | undefined | Promise<ShapeCatalog | undefined>;
+/**
+ * Set (or, with `undefined`, clear) the host's catalog resolver for the
+ * generic query endpoints. Without one, every query decodes in the global
+ * shape registry.
+ */
+export declare function setQueryCatalogResolver(resolver: QueryCatalogResolver | undefined): void;
+/**
+ * The catalog `query` is decoded in: the host resolver's answer, or
+ * `undefined` (the global registry) without a resolver. A live builder already
+ * carries its catalog, so the resolver is not asked for it.
+ *
+ * A `ServerCallError` the resolver throws is passed on as is (the host chose
+ * the status); any other failure is logged and answers 500.
+ */
+export declare function resolveQueryCatalog(query: unknown): Promise<ShapeCatalog | undefined>;
+/**
+ * A rehydrated query builder from the DSL-JSON a client sent, decoded in
+ * `catalog` (`undefined`: the global registry, whatever catalog is active;
+ * see `resolveQueryCatalog`). The builder keeps that catalog, so
+ * the access-check lowering and the store's lowering both resolve against it.
+ * The result is what the store runs, so the access check and the store see
+ * the same query. A body that is not a query answers 400.
  *
  * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
  * resolves one at lowering time against a process-wide context map, which on a
@@ -19,11 +45,11 @@ export declare function containsContextRef(json: unknown): boolean;
  * names its nodes by id.
  *
  * Without context references, lowering a rehydrated builder is a pure function
- * of the builder (closed and never mutated after `fromJSON`) and the shape
- * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * of the builder (closed and never mutated after `fromJSON`) and its shape
+ * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers
  * from the same builder.
  */
-export declare function toQueryBuilder(query: any): any;
+export declare function toQueryBuilder(query: unknown, catalog?: ShapeCatalog): any;
 /** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */
 export declare function lowerForAccessCheck(builder: any): unknown;
 /**

package/lib/esm/utils/queryPlane.js

@@ -10,6 +10,10 @@
  * module turns the incoming query into the builder the store runs and the IR
  * the rules read.
  *
+ * The host can supply the shape catalog a request's query is decoded in
+ * (`setQueryCatalogResolver`), so one server can resolve the same shape IRI
+ * differently per request (for example per project branch).
+ *
  * INTERIM: that per-store access model needs to be revised and rethought from
  * the ground up (see QueryAccess).
  */
@@ -47,10 +51,51 @@ export function containsContextRef(json) {
     }
     return false;
 }
+let queryCatalogResolver;
+/**
+ * Set (or, with `undefined`, clear) the host's catalog resolver for the
+ * generic query endpoints. Without one, every query decodes in the global
+ * shape registry.
+ */
+export function setQueryCatalogResolver(resolver) {
+    queryCatalogResolver = resolver;
+}
+/** A live builder passed by backend code (never a plain object from JSON). */
+function isLiveBuilder(query) {
+    return (!!query &&
+        typeof query === 'object' &&
+        Object.getPrototypeOf(query) !== Object.prototype &&
+        typeof query.__queryKind === 'string');
+}
+/**
+ * The catalog `query` is decoded in: the host resolver's answer, or
+ * `undefined` (the global registry) without a resolver. A live builder already
+ * carries its catalog, so the resolver is not asked for it.
+ *
+ * A `ServerCallError` the resolver throws is passed on as is (the host chose
+ * the status); any other failure is logged and answers 500.
+ */
+export async function resolveQueryCatalog(query) {
+    const resolver = queryCatalogResolver;
+    if (!resolver || isLiveBuilder(query))
+        return undefined;
+    try {
+        return await resolver(query);
+    }
+    catch (error) {
+        if (ServerCallError.is(error))
+            throw error;
+        console.error('[queryPlane] the shape catalog resolver failed:', error);
+        throw new ServerCallError(500, 'Shape catalog unavailable');
+    }
+}
 /**
- * A rehydrated query builder from the DSL-JSON a client sent. The result is
- * what the store runs, so the access check and the store see the same query.
- * A body that is not a query answers 400.
+ * A rehydrated query builder from the DSL-JSON a client sent, decoded in
+ * `catalog` (`undefined`: the global registry, whatever catalog is active;
+ * see `resolveQueryCatalog`). The builder keeps that catalog, so
+ * the access-check lowering and the store's lowering both resolve against it.
+ * The result is what the store runs, so the access check and the store see
+ * the same query. A body that is not a query answers 400.
  *
  * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
  * resolves one at lowering time against a process-wide context map, which on a
@@ -60,23 +105,18 @@ export function containsContextRef(json) {
  * names its nodes by id.
  *
  * Without context references, lowering a rehydrated builder is a pure function
- * of the builder (closed and never mutated after `fromJSON`) and the shape
- * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * of the builder (closed and never mutated after `fromJSON`) and its shape
+ * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers
  * from the same builder.
  */
-export function toQueryBuilder(query) {
-    // A live builder passed by backend code (never a plain object from JSON).
-    if (query &&
-        typeof query === 'object' &&
-        Object.getPrototypeOf(query) !== Object.prototype &&
-        typeof query.__queryKind === 'string') {
+export function toQueryBuilder(query, catalog) {
+    if (isLiveBuilder(query))
         return query;
-    }
     if (containsContextRef(query)) {
         throw new ServerCallError(400, 'Query context references (@ctx) are not accepted by the generic query endpoints');
     }
     try {
-        const builder = fromJSON(query);
+        const builder = fromJSON(query, { catalog });
         if (!builder || typeof builder !== 'object')
             throw new Error('not a query');
         return builder;

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

@@ -1 +1 @@
-{"version":3,"file":"queryPlane.js","sourceRoot":"","sources":["../../../src/utils/queryPlane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authorization for the generic query plane: the endpoints that run a query the\n * client built (`LincdServerBackendProvider.*Query` behind\n * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).\n *\n * The rules are declared per store in the app's storage config\n * (`linked.backend.storage.js`) with `withAccess` from\n * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for\n * how a query is mapped to stores and the order the checks apply in. This\n * module turns the incoming query into the builder the store runs and the IR\n * the rules read.\n *\n * INTERIM: that per-store access model needs to be revised and rethought from\n * the ground up (see QueryAccess).\n */\nimport { fromJSON } from '@_linked/core';\nimport { lower } from '@_linked/core/queries/lower';\nimport {\n  checkQueryAccess,\n  type QueryOperation,\n} from '@_linked/server-utils/utils/QueryAccess';\nimport { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';\nimport { getRawQueriesMode } from './rawQueries.js';\nimport { getRpcExposureMode } from './rpcExposure.js';\n\n/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */\nconst CONTEXT_REF_KEY = '@ctx';\n\n/**\n * Whether DSL-JSON carries a query-context reference (`{\"@ctx\": name}`) in any\n * position: a select or count subject, an update target, a delete id, a\n * where-clause operand or a mutation field value. Every DSL-JSON decoder in\n * core reads a context reference from this one key.\n */\nexport function containsContextRef(json: unknown): boolean {\n  const seen = new Set<object>();\n  const stack: unknown[] = [json];\n  while (stack.length) {\n    const value = stack.pop();\n    if (!value || typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n    if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n      continue;\n    }\n    if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY)) return true;\n    for (const key of Object.keys(value)) stack.push((value as any)[key]);\n  }\n  return false;\n}\n\n/**\n * A rehydrated query builder from the DSL-JSON a client sent. The result is\n * what the store runs, so the access check and the store see the same query.\n * A body that is not a query answers 400.\n *\n * A query-context reference (`{\"@ctx\": \"user\"}`) also answers 400. Core\n * resolves one at lowering time against a process-wide context map, which on a\n * server holds whatever some code last set there, not the caller's identity,\n * and lowering runs twice (once for the access check, once in the store), so\n * the two could even resolve it differently. A query built from client JSON\n * names its nodes by id.\n *\n * Without context references, lowering a rehydrated builder is a pure function\n * of the builder (closed and never mutated after `fromJSON`) and the shape\n * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers\n * from the same builder.\n */\nexport function toQueryBuilder(query: any): any {\n  // A live builder passed by backend code (never a plain object from JSON).\n  if (\n    query &&\n    typeof query === 'object' &&\n    Object.getPrototypeOf(query) !== Object.prototype &&\n    typeof query.__queryKind === 'string'\n  ) {\n    return query;\n  }\n  if (containsContextRef(query)) {\n    throw new ServerCallError(\n      400,\n      'Query context references (@ctx) are not accepted by the generic query endpoints'\n    );\n  }\n  try {\n    const builder = fromJSON(query);\n    if (!builder || typeof builder !== 'object') throw new Error('not a query');\n    return builder;\n  } catch {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n}\n\n/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */\nexport function lowerForAccessCheck(builder: any): unknown {\n  try {\n    return lower(builder);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the\n * store access rules. Throws a `ServerCallError` (400/401/403) when the current\n * call may not run it; the caller then hands the same builder to the store.\n *\n * Deliberately returns nothing: a query builder is a thenable, so resolving an\n * async function with one would run it.\n */\nexport async function authorizeGenericQuery(\n  operation: QueryOperation,\n  query: unknown,\n  builder: any,\n  endpoint: string\n): Promise<void> {\n  await checkQueryAccess({\n    operation,\n    query,\n    ir: lowerForAccessCheck(builder),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n\n/** Check a raw SPARQL query against the `rawQueries` setting (see utils/rawQueries). */\nexport async function authorizeRawQuery(query: unknown, endpoint: string): Promise<void> {\n  if (typeof query !== 'string') {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n  await checkQueryAccess({\n    operation: 'select',\n    query,\n    ir: undefined,\n    raw: true,\n    rawQueries: getRawQueriesMode(),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n"]}
+{"version":3,"file":"queryPlane.js","sourceRoot":"","sources":["../../../src/utils/queryPlane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authorization for the generic query plane: the endpoints that run a query the\n * client built (`LincdServerBackendProvider.*Query` behind\n * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).\n *\n * The rules are declared per store in the app's storage config\n * (`linked.backend.storage.js`) with `withAccess` from\n * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for\n * how a query is mapped to stores and the order the checks apply in. This\n * module turns the incoming query into the builder the store runs and the IR\n * the rules read.\n *\n * The host can supply the shape catalog a request's query is decoded in\n * (`setQueryCatalogResolver`), so one server can resolve the same shape IRI\n * differently per request (for example per project branch).\n *\n * INTERIM: that per-store access model needs to be revised and rethought from\n * the ground up (see QueryAccess).\n */\nimport { fromJSON } from '@_linked/core';\nimport { lower } from '@_linked/core/queries/lower';\nimport type { ShapeCatalog } from '@_linked/core/utils/ShapeCatalog';\nimport {\n  checkQueryAccess,\n  type QueryOperation,\n} from '@_linked/server-utils/utils/QueryAccess';\nimport { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';\nimport { getRawQueriesMode } from './rawQueries.js';\nimport { getRpcExposureMode } from './rpcExposure.js';\n\n/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */\nconst CONTEXT_REF_KEY = '@ctx';\n\n/**\n * Whether DSL-JSON carries a query-context reference (`{\"@ctx\": name}`) in any\n * position: a select or count subject, an update target, a delete id, a\n * where-clause operand or a mutation field value. Every DSL-JSON decoder in\n * core reads a context reference from this one key.\n */\nexport function containsContextRef(json: unknown): boolean {\n  const seen = new Set<object>();\n  const stack: unknown[] = [json];\n  while (stack.length) {\n    const value = stack.pop();\n    if (!value || typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n    if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n      continue;\n    }\n    if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY)) return true;\n    for (const key of Object.keys(value)) stack.push((value as any)[key]);\n  }\n  return false;\n}\n\n/**\n * Supplies the shape catalog a generic query request is decoded in, from the\n * DSL-JSON the client sent (the request context is available through the\n * host's own means, e.g. `getCallContext`). `undefined` means the global\n * shape registry.\n */\nexport type QueryCatalogResolver = (\n  query: unknown\n) => ShapeCatalog | undefined | Promise<ShapeCatalog | undefined>;\n\nlet queryCatalogResolver: QueryCatalogResolver | undefined;\n\n/**\n * Set (or, with `undefined`, clear) the host's catalog resolver for the\n * generic query endpoints. Without one, every query decodes in the global\n * shape registry.\n */\nexport function setQueryCatalogResolver(resolver: QueryCatalogResolver | undefined): void {\n  queryCatalogResolver = resolver;\n}\n\n/** A live builder passed by backend code (never a plain object from JSON). */\nfunction isLiveBuilder(query: any): boolean {\n  return (\n    !!query &&\n    typeof query === 'object' &&\n    Object.getPrototypeOf(query) !== Object.prototype &&\n    typeof query.__queryKind === 'string'\n  );\n}\n\n/**\n * The catalog `query` is decoded in: the host resolver's answer, or\n * `undefined` (the global registry) without a resolver. A live builder already\n * carries its catalog, so the resolver is not asked for it.\n *\n * A `ServerCallError` the resolver throws is passed on as is (the host chose\n * the status); any other failure is logged and answers 500.\n */\nexport async function resolveQueryCatalog(query: unknown): Promise<ShapeCatalog | undefined> {\n  const resolver = queryCatalogResolver;\n  if (!resolver || isLiveBuilder(query)) return undefined;\n  try {\n    return await resolver(query);\n  } catch (error) {\n    if (ServerCallError.is(error)) throw error;\n    console.error('[queryPlane] the shape catalog resolver failed:', error);\n    throw new ServerCallError(500, 'Shape catalog unavailable');\n  }\n}\n\n/**\n * A rehydrated query builder from the DSL-JSON a client sent, decoded in\n * `catalog` (`undefined`: the global registry, whatever catalog is active;\n * see `resolveQueryCatalog`). The builder keeps that catalog, so\n * the access-check lowering and the store's lowering both resolve against it.\n * The result is what the store runs, so the access check and the store see\n * the same query. A body that is not a query answers 400.\n *\n * A query-context reference (`{\"@ctx\": \"user\"}`) also answers 400. Core\n * resolves one at lowering time against a process-wide context map, which on a\n * server holds whatever some code last set there, not the caller's identity,\n * and lowering runs twice (once for the access check, once in the store), so\n * the two could even resolve it differently. A query built from client JSON\n * names its nodes by id.\n *\n * Without context references, lowering a rehydrated builder is a pure function\n * of the builder (closed and never mutated after `fromJSON`) and its shape\n * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers\n * from the same builder.\n */\nexport function toQueryBuilder(query: unknown, catalog?: ShapeCatalog): any {\n  if (isLiveBuilder(query)) return query;\n  if (containsContextRef(query)) {\n    throw new ServerCallError(\n      400,\n      'Query context references (@ctx) are not accepted by the generic query endpoints'\n    );\n  }\n  try {\n    const builder = fromJSON(query as any, { catalog });\n    if (!builder || typeof builder !== 'object') throw new Error('not a query');\n    return builder;\n  } catch {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n}\n\n/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */\nexport function lowerForAccessCheck(builder: any): unknown {\n  try {\n    return lower(builder);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the\n * store access rules. Throws a `ServerCallError` (400/401/403) when the current\n * call may not run it; the caller then hands the same builder to the store.\n *\n * Deliberately returns nothing: a query builder is a thenable, so resolving an\n * async function with one would run it.\n */\nexport async function authorizeGenericQuery(\n  operation: QueryOperation,\n  query: unknown,\n  builder: any,\n  endpoint: string\n): Promise<void> {\n  await checkQueryAccess({\n    operation,\n    query,\n    ir: lowerForAccessCheck(builder),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n\n/** Check a raw SPARQL query against the `rawQueries` setting (see utils/rawQueries). */\nexport async function authorizeRawQuery(query: unknown, endpoint: string): Promise<void> {\n  if (typeof query !== 'string') {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n  await checkQueryAccess({\n    operation: 'select',\n    query,\n    ir: undefined,\n    raw: true,\n    rawQueries: getRawQueriesMode(),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n"]}

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "3.0.0",
+  "version": "3.2.0",
   "packageManager": "npm@12.2.0",
   "linkedPackage": true,
   "type": "module",
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "@_linked/cli": "^1.45.5",
-    "@_linked/core": "^2.28.0",
+    "@_linked/core": "^2.35.0",
     "@_linked/server-utils": "^1.12.0",
     "autoprefixer": "^10.4.18",
     "compression": "^1.7.4",

package/readme.md

@@ -23,6 +23,7 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Without `url`](#without-url)
   - [With `url`](#with-url)
   - [`ping`](#ping)
+  - [Shape catalog per request](#shape-catalog-per-request)
 - [API-only servers (`server.apiOnly`)](#api-only-servers-serverapionly)
 - [Provider lifecycle and HMR](#provider-lifecycle-and-hmr)
   - [When a provider throws, and refusing to start](#when-a-provider-throws-and-refusing-to-start)
@@ -294,6 +295,17 @@ semantics are under [Error semantics](#error-semantics). `token` is ignored.
 - `init()` posts `{"args": []}` to `{url}/call/@_linked/server/ping`. A success is memoized; after
   a failure the next `init()` asks again. `LinkedStorage.setDefaultDataset` does not await
   `init()`, so a boot that must fail loudly awaits it itself before registering the store.
+- `init()` resolves the ping body, which the store also keeps as the readonly `info`
+  (`RemoteDatasetPingInfo`, frozen; `{}` when the body is not a JSON object; `undefined` before
+  a successful ping and in the no-url form). The generic ping answers `{ok: true}`; a gateway may
+  add fields naming the dataset it serves (CN's adds `projectId`, `branchName`, `dataset`,
+  `forked`), so a boot can log where its data goes:
+
+  ```ts
+  const info = await store.init();
+  console.log(`[storage] appData: RemoteDataset at ${store.url}` +
+    (typeof info?.dataset === 'string' ? ` → dataset ${info.dataset}` : ''));
+  ```
 - Errors, each carrying `url` (the base), `status` (0 when no HTTP answer came back) and `code`
   (the error body's `code`, when the server sent one). Messages name the url and the method,
   never the token.
@@ -315,6 +327,33 @@ nothing, changes nothing and answers `{ "ok": true }`. A plain linked server has
 concept; a host that serves the wire with tokens checks the token itself and answers 401 for a
 refused one.
 
+### Shape catalog per request
+
+The generic query endpoints (`/call/@_linked/server/*Query` and `/api/*`) rebuild the client's
+DSL-JSON with core's `fromJSON`. By default it decodes against the global shape registry. A
+host that serves several shape sets at once (for example one per project branch) supplies a
+`ShapeCatalog` (from `@_linked/core`) per request:
+
+```typescript
+import { setQueryCatalogResolver } from '@_linked/server/utils/queryPlane';
+
+// query: the DSL-JSON the client sent. Read the request itself through getCallContext().
+setQueryCatalogResolver(async (query) => catalogForThisRequest(query));
+```
+
+- The resolver is called once per request, before the query is decoded. `undefined` means the
+  global registry. With no resolver set, behaviour is unchanged.
+- The builder keeps the catalog it was decoded in, so the access check (`withAccess` rules) and
+  the store lower the query against the same shapes. A shape the catalog does not hold answers
+  `400 Invalid query`.
+- A resolver that throws a `ServerCallError` answers with its status and message. Any other
+  throw is logged and answers `500 {"error": "Shape catalog unavailable"}`.
+- A live builder passed in by backend code already carries its catalog; the resolver is not
+  called for it.
+- `setQueryCatalogResolver(undefined)` removes the resolver. `resolveQueryCatalog(query)` and
+  `toQueryBuilder(query, catalog)` are exported for hosts that serve the same wire on their own
+  routes.
+
 ## API-only servers (`server.apiOnly`)
 
 A backend that serves no frontend app (e.g. started with `linked start --api-only`) can set `apiOnly` in its server config: