@_linked/server 2.25.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @\_linked/server
 
+## 3.0.0
+
+### Major Changes
+
+- [#179](https://github.com/linked-fw/server/pull/179) [`0a032fb`](https://github.com/linked-fw/server/commit/0a032fbc830fd001ccb27330072090019259c206) Thanks [@flyon](https://github.com/flyon)! - `BackendAPIStore` is renamed `RemoteDataset` and gains a `url`/`token` form for a remote data server; `GatewayStore` is removed; new public `ping` method.
+
+  Migration:
+
+  - **`BackendAPIStore` users:** replace the import path `@_linked/server/shapes/quadstores/BackendAPIStore` with `@_linked/server/shapes/quadstores/RemoteDataset` and the class name `BackendAPIStore` with `RemoteDataset` (in code and in the `store` of `linked.{frontend,backend}.datasets.json`). Without `url` the behaviour is unchanged; there is no alias.
+  - **`GatewayStore` users:** point `RemoteDataset` at the server's `/call` base instead: config `{ "url": "<base>", "token": "<bearer token>" }` (was `{ endpoint, credential }`). It posts `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with `Authorization: Bearer <token>`; the `{v, op, query}` envelope, `/query` and `/health` routes and the `fetch` config override are gone.
+  - **Config:** `RemoteDatasetConfig` is `{ url?, token?, name?, id? }`. A `url` that is present but empty never falls back to the no-url form.
+  - **`init()`:** with `url`, it posts to `{url}/call/@_linked/server/ping` (memoized on success) and throws a typed error. Await it before registering the store.
+  - **Errors:** `GatewayStoreError` / `GatewayUnreachableError` are replaced by `RemoteDatasetError` (`url`, `status`, optional `code`) and its subclasses `RemoteDatasetUnreachableError` (no answer, empty url, or nothing at the url speaks the wire) and `RemoteDatasetUnauthorizedError` (401 or 403).
+  - **`ping`:** `POST /call/@_linked/server/ping` is a new `public` method that answers `{ "ok": true }`.
+
 ## 2.25.0
 
 ### Minor Changes

package/lib/esm/backend.d.ts

@@ -1,6 +1,14 @@
 import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';
 export default class LincdServerBackendProvider extends BackendProvider {
     setupBeforeControllers(): Promise<void>;
+    /**
+     * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes
+     * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;
+     * a host that serves the wire with tokens answers 401 for a refused one.
+     */
+    ping(): Promise<{
+        ok: true;
+    }>;
     selectQuery(json: any): Promise<unknown>;
     askQuery(json: any): Promise<boolean>;
     updateQuery(json: any): Promise<unknown>;

package/lib/esm/backend.js

@@ -30,22 +30,25 @@ export default class LincdServerBackendProvider extends BackendProvider {
             });
         }
     }
-    // ── BackendAPIStore query execution ──────────────────────────────────────
-    //
-    // These answer the frontend `BackendAPIStore`, which calls
-    // `Server.call(packageName, {method}, json)` — the PACKAGE form, so the request
-    // arrives here on the generic provider rather than through Shape resolution.
+    /**
+     * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes
+     * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;
+     * a host that serves the wire with tokens answers 401 for a refused one.
+     */
+    async ping() {
+        return { ok: true };
+    }
+    // ── Generic query execution ──────────────────────────────────────────────
     //
-    // They used to live on `BackendAPIStoreProvider`, a `ShapeProvider`, whose methods
-    // took the store as a first argument and never read it. Reaching that provider meant
-    // the transport had to carry a `shapeURI` and an `instanceNode`, and the server had to
-    // rebuild the store with `new (providerShapeClass)({id})` — instantiating a Shape only
-    // to discard it. Addressing by package removes all of that.
+    // These answer `RemoteDataset`: a browser's store calls
+    // `Server.call(packageName, {method}, json)` (the PACKAGE form), and a remote app's store
+    // posts the same `{args}` body to `{url}/call/@_linked/server/<method>`. Either way the
+    // request arrives here on the generic provider rather than through Shape resolution.
     //
-    // A query cannot cross the wire live (core 2.10.0 contract flip), 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, and always was, what
-    // decides the target dataset. The store instance never participated.
+    // 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.
     //
     // 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
@@ -79,6 +82,12 @@ export default class LincdServerBackendProvider extends BackendProvider {
         return LinkedStorage.deleteQuery(query);
     }
 }
+__decorate([
+    callable('public'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], LincdServerBackendProvider.prototype, "ping", null);
 __decorate([
     callable('public'),
     __metadata("design:type", Function),

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  // ── BackendAPIStore query execution ──────────────────────────────────────\n  //\n  // These answer the frontend `BackendAPIStore`, which calls\n  // `Server.call(packageName, {method}, json)` — the PACKAGE form, so the request\n  // arrives here on the generic provider rather than through Shape resolution.\n  //\n  // They used to live on `BackendAPIStoreProvider`, a `ShapeProvider`, whose methods\n  // took the store as a first argument and never read it. Reaching that provider meant\n  // the transport had to carry a `shapeURI` and an `instanceNode`, and the server had to\n  // rebuild the store with `new (providerShapeClass)({id})` — instantiating a Shape only\n  // to discard it. Addressing by package removes all of that.\n  //\n  // A query cannot cross the wire live (core 2.10.0 contract flip), so the client ships\n  // `toJSON()` and `fromJSON()` rehydrates it here into a live, closed query.\n  // `LinkedStorage` then routes it by the QUERY's shape — which is, and always was, what\n  // decides the target dataset. The store instance never participated.\n\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 { 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"]}

package/lib/esm/index.d.ts

@@ -1,7 +1,7 @@
 import './types.js';
 import './ontologies/server.register.js';
 import './shapes/index.js';
-import './shapes/quadstores/BackendAPIStore.js';
+import './shapes/quadstores/RemoteDataset.js';
 import './shapes/filestores/LocalFileStore.js';
 import './utils/accessUrl.js';
 export { FatalStartupError, isFatalError } from './utils/fatalError.js';

package/lib/esm/index.js

@@ -3,7 +3,7 @@ import './ontologies/server.register.js';
 //SHAPES FIRST
 import './shapes/index.js';
 // Not shapes (plain store classes); kept so the entry's module graph is unchanged.
-import './shapes/quadstores/BackendAPIStore.js';
+import './shapes/quadstores/RemoteDataset.js';
 import './shapes/filestores/LocalFileStore.js';
 //THEN COMPONENTS
 import './utils/accessUrl.js';

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,iCAAiC,CAAC;AAEzC,cAAc;AACd,OAAO,mBAAmB,CAAC;AAC3B,mFAAmF;AACnF,OAAO,wCAAwC,CAAC;AAChD,OAAO,uCAAuC,CAAC;AAE/C,iBAAiB;AACjB,OAAO,sBAAsB,CAAC;AAE9B,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["import './types.js';\nimport './ontologies/server.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n// Not shapes (plain store classes); kept so the entry's module graph is unchanged.\nimport './shapes/quadstores/BackendAPIStore.js';\nimport './shapes/filestores/LocalFileStore.js';\n\n//THEN COMPONENTS\nimport './utils/accessUrl.js';\n\n// The fatal-error contract a provider uses to refuse to let the server start.\nexport { FatalStartupError, isFatalError } from './utils/fatalError.js';\nexport type { FatalError } from './utils/fatalError.js';\n\n//TYPES — re-exported from @_linked/server-utils (canonical location)\nexport type {\n  RouteConfig,\n  RoutesConfig,\n  RoutesModule,\n} from '@_linked/server-utils/types/RouteConfig';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,iCAAiC,CAAC;AAEzC,cAAc;AACd,OAAO,mBAAmB,CAAC;AAC3B,mFAAmF;AACnF,OAAO,sCAAsC,CAAC;AAC9C,OAAO,uCAAuC,CAAC;AAE/C,iBAAiB;AACjB,OAAO,sBAAsB,CAAC;AAE9B,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["import './types.js';\nimport './ontologies/server.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n// Not shapes (plain store classes); kept so the entry's module graph is unchanged.\nimport './shapes/quadstores/RemoteDataset.js';\nimport './shapes/filestores/LocalFileStore.js';\n\n//THEN COMPONENTS\nimport './utils/accessUrl.js';\n\n// The fatal-error contract a provider uses to refuse to let the server start.\nexport { FatalStartupError, isFatalError } from './utils/fatalError.js';\nexport type { FatalError } from './utils/fatalError.js';\n\n//TYPES — re-exported from @_linked/server-utils (canonical location)\nexport type {\n  RouteConfig,\n  RoutesConfig,\n  RoutesModule,\n} from '@_linked/server-utils/types/RouteConfig';\n"]}

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

@@ -0,0 +1,100 @@
+import type { IDataset } from '@_linked/core/interfaces/IDataset';
+import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
+import type { CountQuery } from '@_linked/core/queries/CountQuery';
+import type { AskQuery } from '@_linked/core/queries/AskQuery';
+import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
+import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
+import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
+import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
+/**
+ * Constructor argument for `new RemoteDataset(config)`: the `config` object of a
+ * `linked.{frontend,backend}.datasets.json` entry, passed verbatim.
+ */
+export interface RemoteDatasetConfig {
+    /**
+     * Base URL of the data server, e.g. `http://localhost:4040/gateway`; routes are appended
+     * to it. Without it, queries go to this process's own backend through `Server.call`.
+     * Present but empty is an error, never the no-url form.
+     */
+    url?: string;
+    /** Sent as `Authorization: Bearer <token>` when set and `url` is set. */
+    token?: string;
+    /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */
+    name?: string;
+    /** Or pass a fully-qualified URI directly. */
+    id?: string;
+}
+/**
+ * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP
+ * answer came back); `code` is the error body's `code` when the server sent one.
+ */
+export declare class RemoteDatasetError extends Error {
+    /** The data server base url ('' when the configured url is empty). */
+    readonly url: string;
+    /** The HTTP status; 0 = no HTTP answer. */
+    readonly status: number;
+    /** The error body's `code`, when the server sent one. */
+    readonly code?: string;
+    constructor(message: string, url: string, status: number, code?: string);
+}
+/**
+ * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an
+ * answer that is not the server's. A boot that gets this should stop.
+ */
+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 {
+}
+/**
+ * An {@link IDataset} whose queries are answered by a linked server.
+ *
+ * - **Without `url`** the server is this app's own backend: every query goes through
+ *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),
+ *   and on a backend `Server`'s local shortcut answers it in process. This is the store a
+ *   browser uses to talk to its backend.
+ * - **With `url`** the server is a remote data server: every query posts
+ *   `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer
+ *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the
+ *   app's own provider) and never retried (a retried write could apply twice). `init()` asks
+ *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or
+ *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.
+ *
+ * A store is not a Shape: it addresses the backend by package name, so nothing about the
+ * 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.
+ */
+export declare class RemoteDataset implements IDataset {
+    /**
+     * Kept so the config form is still accepted and a store can be named; it is not an
+     * addressing mechanism, nothing transmits or resolves it.
+     */
+    readonly id?: string;
+    /** The data server base url, trailing slashes trimmed; undefined in the no-url form. */
+    readonly url?: string;
+    private readonly token?;
+    private initialized?;
+    constructor(config?: RemoteDatasetConfig | string);
+    init(): Promise<void>;
+    selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;
+    askQuery(query: AskQuery): Promise<boolean>;
+    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
+    createQuery(query: CreateQuery): Promise<CreateResult>;
+    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
+    private call;
+    /**
+     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
+     * provider on the backend) rejects with a `ServerCallError` carrying the
+     * status and the server's message instead of reading as an empty result.
+     * Whatever a successful call returns, `undefined` included, resolves as is.
+     */
+    private callBackend;
+    /**
+     * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed
+     * body (`null` is a valid result: a method that returned `undefined`). Messages name the
+     * url and the method, never the token.
+     */
+    private post;
+}

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

@@ -0,0 +1,188 @@
+import { packageName } from '../../package.js';
+import { Server } from '@_linked/server-utils/utils/Server';
+/**
+ * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP
+ * answer came back); `code` is the error body's `code` when the server sent one.
+ */
+export class RemoteDatasetError extends Error {
+    constructor(message, url, status, code) {
+        super(message);
+        this.name = new.target.name;
+        this.url = url;
+        this.status = status;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+/**
+ * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an
+ * answer that is not the server's. A boot that gets this should stop.
+ */
+export class RemoteDatasetUnreachableError extends RemoteDatasetError {
+}
+/** The data server answered 401 or 403: it refused this dataset's token. */
+export class RemoteDatasetUnauthorizedError extends RemoteDatasetError {
+}
+/** On `ping`, these statuses mean nothing at that url serves the query wire. */
+const PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);
+/**
+ * An {@link IDataset} whose queries are answered by a linked server.
+ *
+ * - **Without `url`** the server is this app's own backend: every query goes through
+ *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),
+ *   and on a backend `Server`'s local shortcut answers it in process. This is the store a
+ *   browser uses to talk to its backend.
+ * - **With `url`** the server is a remote data server: every query posts
+ *   `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer
+ *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the
+ *   app's own provider) and never retried (a retried write could apply twice). `init()` asks
+ *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or
+ *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.
+ *
+ * A store is not a Shape: it addresses the backend by package name, so nothing about the
+ * 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.
+ */
+export class RemoteDataset {
+    constructor(config) {
+        if (!config)
+            return;
+        if (typeof config === 'string') {
+            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;
+            return;
+        }
+        if (typeof config.url === 'string') {
+            this.url = config.url.trim().replace(/\/+$/, '');
+            const token = typeof config.token === 'string' ? config.token.trim() : '';
+            if (token)
+                this.token = token;
+        }
+        if (config.id) {
+            this.id = config.id;
+            return;
+        }
+        if (config.name) {
+            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;
+        }
+    }
+    init() {
+        // No initialization needed when queries are routed to the app's own backend.
+        if (this.url === undefined)
+            return Promise.resolve();
+        if (!this.initialized) {
+            this.initialized = this.post('ping', []).then(() => undefined, (err) => {
+                // Not memoized: the next init() asks again.
+                this.initialized = undefined;
+                throw err;
+            });
+        }
+        return this.initialized;
+    }
+    // Queries serialize to DSL-JSON for the wire: the live (closed) query can't cross a call
+    // as-is, so we ship `toJSON()` and the server's generic provider rehydrates it with
+    // `fromJSON()`.
+    selectQuery(query) {
+        return this.call('selectQuery', query.toJSON());
+    }
+    askQuery(query) {
+        return this.call('askQuery', query.toJSON());
+    }
+    updateQuery(query) {
+        return this.call('updateQuery', query.toJSON());
+    }
+    createQuery(query) {
+        return this.call('createQuery', query.toJSON());
+    }
+    deleteQuery(query) {
+        return this.call('deleteQuery', query.toJSON());
+    }
+    call(method, json) {
+        if (this.url === undefined)
+            return this.callBackend(method, json);
+        return this.post(method, [json]);
+    }
+    /**
+     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
+     * provider on the backend) rejects with a `ServerCallError` carrying the
+     * status and the server's message instead of reading as an empty result.
+     * Whatever a successful call returns, `undefined` included, resolves as is.
+     */
+    callBackend(method, json) {
+        // The PACKAGE form, not the shape form. It posts to
+        // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,
+        // no `instanceNode` — and the backend answers from this package's generic
+        // provider without resolving or instantiating any Shape.
+        return Server.call(packageName, { method, rejectOnError: true }, json);
+    }
+    /**
+     * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed
+     * body (`null` is a valid result: a method that returned `undefined`). Messages name the
+     * url and the method, never the token.
+     */
+    async post(method, args) {
+        var _a;
+        const base = (_a = this.url) !== null && _a !== void 0 ? _a : '';
+        if (!base) {
+            throw new RemoteDatasetUnreachableError(`RemoteDataset: no data server url is set (the configured url is empty); cannot ${method}`, '', 0);
+        }
+        const target = `${base}/call/${packageName}/${method}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        let response;
+        try {
+            response = await globalThis.fetch(target, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ args }),
+            });
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            throw new RemoteDatasetUnreachableError(`RemoteDataset: cannot reach the data server at ${base} (${method}): ${cause}`, base, 0);
+        }
+        const text = await response.text();
+        let body = undefined;
+        let isJson = false;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+                isJson = true;
+            }
+            catch (_b) {
+                body = text;
+            }
+        }
+        if (response.ok) {
+            if (isJson)
+                return body;
+            if (method === 'ping') {
+                throw new RemoteDatasetUnreachableError(`RemoteDataset: the data server at ${base} answered ping with a body that is not JSON`, base, response.status);
+            }
+            if (!text)
+                return undefined;
+            throw new RemoteDatasetError(`RemoteDataset: the data server at ${base} answered ${method} with a body that is not JSON`, base, response.status);
+        }
+        const record = body && typeof body === 'object' ? body : undefined;
+        const code = typeof (record === null || record === void 0 ? void 0 : record.code) === 'string' ? record.code : undefined;
+        const detail = typeof (record === null || record === void 0 ? void 0 : record.error) === 'string'
+            ? record.error
+            : typeof body === 'string' && body
+                ? body
+                : response.statusText;
+        const message = `RemoteDataset: the data server at ${base} answered ${method} with ${response.status}${code ? ` (${code})` : ''}${detail ? `: ${detail}` : ''}`;
+        if (response.status === 401 || response.status === 403) {
+            throw new RemoteDatasetUnauthorizedError(message, base, response.status, code);
+        }
+        if (method === 'ping' && (PING_UNREACHABLE_STATUSES.has(response.status) || !isJson)) {
+            throw new RemoteDatasetUnreachableError(message, base, response.status, code);
+        }
+        throw new RemoteDatasetError(message, base, response.status, code);
+    }
+}
+//# sourceMappingURL=RemoteDataset.js.map

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

@@ -0,0 +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"]}

package/package.json

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

package/readme.md

@@ -20,8 +20,9 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Gotchas](#gotchas)
   - [Error semantics](#error-semantics)
 - [Query stores](#query-stores)
-  - [BackendAPIStore](#backendapistore)
-  - [GatewayStore](#gatewaystore)
+  - [Without `url`](#without-url)
+  - [With `url`](#with-url)
+  - [`ping`](#ping)
 - [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)
@@ -233,73 +234,86 @@ What the caller sees depends on how it calls:
 - **`Server.call` on the backend.** Here it calls the `LinkedServer` directly.
   - A provider method that throws always rejects.
   - An unmatched call resolves `undefined` by default and rejects with a 501 `ServerCallError` when `rejectOnError` is set.
-- **`BackendAPIStore`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
+- **`RemoteDataset` without `url`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
 
 ## Query stores
 
-Two `IDataset` implementations in this package forward Linked Queries over HTTP instead of
-answering them. Both ship `query.toJSON()` and resolve with the plain JSON rows the other side
-returns; neither offers raw SPARQL (`rawQuery`), dataset administration or a change feed.
+`RemoteDataset` is an `IDataset` whose Linked Queries are answered by a linked server instead of
+by the store itself. It ships `query.toJSON()` and resolves with the plain JSON the server
+returns; it offers no raw SPARQL (`rawQuery`), dataset administration or change feed.
 
-| | `BackendAPIStore` | `GatewayStore` |
+Export path `@_linked/server/shapes/quadstores/RemoteDataset` (named export `RemoteDataset`, so
+`loadStores` resolves it by the last path segment). One class, two forms:
+
+| | no `url` | with `url` |
 | --- | --- | --- |
-| Runs in | the browser (or any client of this package's `/call` routes) | a backend process |
-| Sends to | this app's own backend, through `Server.call` (`/call/<package>/<method>`) | a gateway of another service: `POST {endpoint}/query` |
-| Authenticated by | the user's session | a bearer credential the gateway issued to this process |
-| Who picks the dataset | the backend's `LinkedStorage` | the gateway, from the credential |
+| Answered by | this app's own backend | a remote data server, e.g. a host's gateway |
+| Sends through | `Server.call`'s package form (`/call/@_linked/server/<method>`); on a backend, `Server`'s local shortcut | `globalThis.fetch` to `{url}/call/@_linked/server/<method>`, never `Server` |
+| Authenticated by | the user's session | `Authorization: Bearer <token>` |
+| `init()` | resolves at once | posts `ping`, throws a typed error when the server cannot be used |
+| Typical config | `linked.frontend.datasets.json` | `linked.backend.datasets.json` |
+
+```typescript
+export interface RemoteDatasetConfig {
+  url?: string;   // data server base, e.g. http://localhost:4040/gateway; routes are appended
+  token?: string; // sent as Authorization: Bearer <token> when set and url is set
+  name?: string;  // id = ${DATA_ROOT}/backend-api-store/<name>; does not affect routing
+  id?: string;
+}
+```
 
-### BackendAPIStore
+`new RemoteDataset('main')` is the `name` form.
 
-Export path `@_linked/server/shapes/quadstores/BackendAPIStore`. Selected in
-`linked.frontend.datasets.json`; `config` may carry a `name` or `id`, neither of which affects
-routing. Its error semantics are under [Error semantics](#error-semantics).
+### Without `url`
 
-### GatewayStore
+Every query is `Server.call(packageName, { method, rejectOnError: true }, query.toJSON())`, and
+this package's generic provider answers it from the backend's `LinkedStorage`. Its error
+semantics are under [Error semantics](#error-semantics). `token` is ignored.
 
-Export path `@_linked/server/shapes/quadstores/GatewayStore` (named export `GatewayStore`, so
-`loadStores` resolves it by the last path segment). It is for a backend whose data lives behind
-a gateway run by the host that started it — for example an app process started by Create Now,
-whose queries go to CN's gateway so that branch forks, authorization and audit apply to app
-traffic.
+### With `url`
 
 ```json
 {
   "datasets": {
-    "gateway": {
-      "store": "@_linked/server/shapes/quadstores/GatewayStore",
-      "config": { "endpoint": "${CN_EG_GATEWAY:-}", "credential": "${CN_APP_SERVICE_SECRET:-}" }
+    "appData": {
+      "store": "@_linked/server/shapes/quadstores/RemoteDataset",
+      "config": { "url": "${DATA_SERVER_URL:-}", "token": "${DATA_SERVER_TOKEN:-}" }
     }
   }
 }
 ```
 
-```typescript
-export interface GatewayStoreConfig {
-  endpoint: string;   // base URL of the gateway, routes are appended: `${endpoint}/query`, `${endpoint}/health`
-  credential: string; // sent as `Authorization: Bearer <credential>`
-  fetch?: typeof fetch; // transport override, default `globalThis.fetch`
-}
-```
-
-- The constructor throws at once when `endpoint` or `credential` is empty. The `:-` defaults in
-  the JSON keep `parseDatasetsConfig` from throwing when the variables are unset; a storage file
-  instantiates the alias only when the host set them (the presence of `CN_EG_GATEWAY` is the
-  mode switch; `CN_APP_SERVICE_SECRET` is injected into the process environment, never written
-  to `.env`).
-- `init()` is `GET {endpoint}/health` and resolves with the gateway's answer
-  (`{projectId, branchName, dataset}`). It throws `GatewayUnreachableError` when the gateway
-  cannot be reached or refuses the credential. `LinkedStorage.setDefaultDataset` does not await
-  `init()`, so a boot that must fail loudly awaits `init()` itself before registering the store.
-  Calling it again is harmless.
-- Every query method posts `{ "v": 1, "op": "select" | "ask" | "update" | "create" | "delete", "query": <query.toJSON()> }`
-  and resolves with the body's `result`. A count arrives through `selectQuery` with `op: "select"`
-  (the gateway dispatches on the query's own `op`). Nothing about the project, branch or actor is
-  in the body: the credential decides all three.
-- Errors: a network failure and a `401` reject with `GatewayUnreachableError` (`status` 0 or 401);
-  any other non-2xx answer rejects with `GatewayStoreError`, whose `code` is the body's `code`
-  (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),
-  else `http-<status>`, with the parsed body on `body`. `GatewayUnreachableError extends
-  GatewayStoreError`.
+- Each method posts `{"args": [<query.toJSON()>]}` to `{url}/call/@_linked/server/<method>`
+  (`selectQuery`, which also carries counts, `askQuery`, `updateQuery`, `createQuery`,
+  `deleteQuery`) with `Content-Type` and `Accept` set to `application/json` and, when `token` is
+  non-empty, `Authorization: Bearer <token>`. It resolves the parsed body; `null` is a valid
+  result. No other headers are sent and nothing is retried, so a write is never applied twice.
+- Trailing slashes are trimmed from `url`. A `url` that is present but empty (an unset
+  `${DATA_SERVER_URL:-}`) never falls back to the no-url form: `init()` and every method throw
+  `RemoteDatasetUnreachableError` with `url: ''`.
+- `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.
+- 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.
+
+  | Answer | Error |
+  | --- | --- |
+  | no HTTP answer | `RemoteDatasetUnreachableError` (status 0) |
+  | 401 or 403 | `RemoteDatasetUnauthorizedError` |
+  | on `ping` only: 404, 501, 502, 503, 504, or a body that is not JSON | `RemoteDatasetUnreachableError` |
+  | any other non-2xx | `RemoteDatasetError` |
+
+  `RemoteDatasetUnreachableError` and `RemoteDatasetUnauthorizedError` extend
+  `RemoteDatasetError`, which extends `Error`; match them with `instanceof`.
+
+### `ping`
+
+`POST /call/@_linked/server/ping` (a `public` method of this package's generic provider) reads
+nothing, changes nothing and answers `{ "ok": true }`. A plain linked server has no token
+concept; a host that serves the wire with tokens checks the token itself and answers 401 for a
+refused one.
 
 ## API-only servers (`server.apiOnly`)
 

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

@@ -1,58 +0,0 @@
-import type { IDataset } from '@_linked/core/interfaces/IDataset';
-import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
-import type { AskQuery } from '@_linked/core/queries/AskQuery';
-import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
-import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
-import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
-import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
-/**
- * Constructor argument for `new BackendAPIStore(config)`. Per the
- * docs/backlog/016-ejection-export-flow.md spec — a single JSON object
- * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.
- */
-export interface BackendAPIStoreConfig {
-    /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */
-    name?: string;
-    /** Or pass a fully-qualified URI directly. */
-    id?: string;
-}
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export declare class BackendAPIStore implements IDataset {
-    /**
-     * Kept so the config form is still accepted and a store can be named, but it is no
-     * longer an addressing mechanism — nothing transmits or resolves it. Retained because
-     * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.
-     */
-    readonly id?: string;
-    constructor(config?: BackendAPIStoreConfig | string | {
-        id?: string;
-    });
-    init(): Promise<void>;
-    selectQuery(query: SelectQuery): Promise<SelectResult>;
-    askQuery(query: AskQuery): Promise<boolean>;
-    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
-    createQuery(query: CreateQuery): Promise<CreateResult>;
-    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    private callBackend;
-}

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

@@ -1,71 +0,0 @@
-import { packageName } from '../../package.js';
-import { Server } from '@_linked/server-utils/utils/Server';
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export class BackendAPIStore {
-    constructor(config) {
-        if (!config)
-            return;
-        if (typeof config === 'string') {
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;
-            return;
-        }
-        if (config.id) {
-            this.id = config.id;
-            return;
-        }
-        if (config.name) {
-            const name = config.name;
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;
-        }
-    }
-    async init() {
-        // No initialization needed — queries are routed to the backend
-    }
-    // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the
-    // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and
-    // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.
-    selectQuery(query) {
-        return this.callBackend('selectQuery', query.toJSON());
-    }
-    askQuery(query) {
-        return this.callBackend('askQuery', query.toJSON());
-    }
-    updateQuery(query) {
-        return this.callBackend('updateQuery', query.toJSON());
-    }
-    createQuery(query) {
-        return this.callBackend('createQuery', query.toJSON());
-    }
-    deleteQuery(query) {
-        return this.callBackend('deleteQuery', query.toJSON());
-    }
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    callBackend(method, json) {
-        // The PACKAGE form, not the shape form. It posts to
-        // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,
-        // no `instanceNode` — and the backend answers from this package's generic
-        // provider without resolving or instantiating any Shape.
-        return Server.call(packageName, { method, rejectOnError: true }, json);
-    }
-}
-//# sourceMappingURL=BackendAPIStore.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"BackendAPIStore.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/BackendAPIStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AA4B5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAQ1B,YAAY,MAAyD;QACnE,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,MAAM,EAAE,CAAC;YACjE,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,EAAE,GAAI,MAAgC,CAAC,EAAG,CAAC;YAChD,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAI,MAAgC,CAAC,IAAK,CAAC;YACrD,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,IAAI,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,+DAA+D;IACjE,CAAC;IAED,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAI,MAAc,EAAE,IAAa;QAClD,oDAAoD;QACpD,+EAA+E;QAC/E,0EAA0E;QAC1E,yDAAyD;QACzD,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;CACF","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 { 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 BackendAPIStore(config)`. Per the\n * docs/backlog/016-ejection-export-flow.md spec — a single JSON object\n * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.\n */\nexport interface BackendAPIStoreConfig {\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 * Frontend-side store that routes all queries to the backend via `Server.call()`.\n * The backend's generic provider for this package executes them against the real store.\n *\n * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`\n * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the\n * transport derived the target from `shape instanceof Shape && shape.id` (the instance)\n * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend\n * provider never read the store it was handed, and query routing is decided by the\n * QUERY's shape, not the store's.\n *\n * It now uses `Server.call`'s package form instead, which addresses the backend by\n * package name and sends no shape fields at all. That removes the last reason for this\n * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had\n * to perform to rebuild a store instance nobody used.\n */\nexport class BackendAPIStore implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named, but it is no\n   * longer an addressing mechanism — nothing transmits or resolves it. Retained because\n   * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.\n   */\n  readonly id?: string;\n\n  constructor(config?: BackendAPIStoreConfig | string | { id?: 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 ((config as BackendAPIStoreConfig).id) {\n      this.id = (config as BackendAPIStoreConfig).id!;\n      return;\n    }\n    if ((config as BackendAPIStoreConfig).name) {\n      const name = (config as BackendAPIStoreConfig).name!;\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;\n    }\n  }\n\n  async init(): Promise<void> {\n    // No initialization needed — queries are routed to the backend\n  }\n\n  // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the\n  // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and\n  // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.\n  selectQuery(query: SelectQuery): Promise<SelectResult> {\n    return this.callBackend('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.callBackend('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.callBackend('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.callBackend('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.callBackend('deleteQuery', query.toJSON());\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"]}

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

@@ -1,85 +0,0 @@
-import type { IDataset } from '@_linked/core/interfaces/IDataset';
-import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
-import type { CountQuery } from '@_linked/core/queries/CountQuery';
-import type { AskQuery } from '@_linked/core/queries/AskQuery';
-import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
-import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
-import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
-import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
-/**
- * Constructor argument for `new GatewayStore(config)` — the `config` object of a
- * `linked.backend.datasets.json` entry, passed verbatim by `loadStores`.
- */
-export interface GatewayStoreConfig {
-    /** Base URL of the gateway, e.g. `http://localhost:4040/gateway`. Routes are appended to it. */
-    endpoint: string;
-    /** The bearer credential the gateway issued to this process. */
-    credential: string;
-    /** Transport override; defaults to `globalThis.fetch`. */
-    fetch?: typeof fetch;
-}
-/** The op names on the wire; each is the `IDataset` method the store was called on. */
-export type GatewayOp = 'select' | 'ask' | 'update' | 'create' | 'delete';
-/** The wire version this store speaks. The gateway refuses any other with `code: "wire-version"`. */
-export declare const GATEWAY_WIRE_VERSION = 1;
-/**
- * A non-2xx answer from the gateway. `code` is the body's `code` when the gateway sent one
- * (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),
- * else a generic one; `body` is the parsed response when it was JSON.
- */
-export declare class GatewayStoreError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly body?: unknown;
-    constructor(message: string, status: number, code: string, body?: unknown);
-}
-/**
- * The gateway could not be used at all: the request never got an HTTP answer (network error,
- * `status` 0), or the gateway refused the credential (401). Thrown by `init()` and by every
- * query method; a process that gets this at boot should stop rather than carry on without data.
- */
-export declare class GatewayUnreachableError extends GatewayStoreError {
-}
-/** What `GET {endpoint}/health` answers with a valid credential. */
-export interface GatewayHealth {
-    projectId: string;
-    branchName: string;
-    dataset: string;
-}
-/**
- * An {@link IDataset} that forwards every Linked Query to a gateway over HTTP and returns
- * the gateway's result as is.
- *
- * Each query method posts `{v, op, query: query.toJSON()}` to `POST {endpoint}/query` with
- * `Authorization: Bearer <credential>` and resolves with the body's `result` — the same plain
- * JSON rows `BackendAPIStore` returns. The gateway decides which dataset the query runs on
- * from the credential; the store carries no project, branch or actor.
- *
- * Unlike `BackendAPIStore` it does not go through `Server.call` and has no dependency on
- * the process's own HTTP server: it is meant for a backend whose data lives behind another
- * service, selected from `linked.backend.datasets.json` by the host that started it.
- *
- * The store offers no raw SPARQL (`rawQuery`), no dataset administration and no change feed.
- */
-export declare class GatewayStore implements IDataset {
-    readonly endpoint: string;
-    private readonly credential;
-    private readonly fetchImpl;
-    constructor(config: GatewayStoreConfig);
-    /**
-     * Checks the gateway answers for this credential: `GET {endpoint}/health`. Resolves with the
-     * gateway's answer; throws {@link GatewayUnreachableError} when the gateway cannot be reached
-     * or refuses the credential. Safe to call more than once; it changes nothing on either side.
-     *
-     * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
-     * fail loudly awaits `init()` itself before registering the store.
-     */
-    init(): Promise<GatewayHealth>;
-    selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;
-    askQuery(query: AskQuery): Promise<boolean>;
-    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
-    createQuery(query: CreateQuery): Promise<CreateResult>;
-    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
-    private send;
-    private request;
-}

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

@@ -1,143 +0,0 @@
-/** The wire version this store speaks. The gateway refuses any other with `code: "wire-version"`. */
-export const GATEWAY_WIRE_VERSION = 1;
-/**
- * A non-2xx answer from the gateway. `code` is the body's `code` when the gateway sent one
- * (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),
- * else a generic one; `body` is the parsed response when it was JSON.
- */
-export class GatewayStoreError extends Error {
-    constructor(message, status, code, body) {
-        super(message);
-        this.name = new.target.name;
-        this.status = status;
-        this.code = code;
-        this.body = body;
-    }
-}
-/**
- * The gateway could not be used at all: the request never got an HTTP answer (network error,
- * `status` 0), or the gateway refused the credential (401). Thrown by `init()` and by every
- * query method; a process that gets this at boot should stop rather than carry on without data.
- */
-export class GatewayUnreachableError extends GatewayStoreError {
-}
-/**
- * An {@link IDataset} that forwards every Linked Query to a gateway over HTTP and returns
- * the gateway's result as is.
- *
- * Each query method posts `{v, op, query: query.toJSON()}` to `POST {endpoint}/query` with
- * `Authorization: Bearer <credential>` and resolves with the body's `result` — the same plain
- * JSON rows `BackendAPIStore` returns. The gateway decides which dataset the query runs on
- * from the credential; the store carries no project, branch or actor.
- *
- * Unlike `BackendAPIStore` it does not go through `Server.call` and has no dependency on
- * the process's own HTTP server: it is meant for a backend whose data lives behind another
- * service, selected from `linked.backend.datasets.json` by the host that started it.
- *
- * The store offers no raw SPARQL (`rawQuery`), no dataset administration and no change feed.
- */
-export class GatewayStore {
-    constructor(config) {
-        var _a;
-        const endpoint = typeof (config === null || config === void 0 ? void 0 : config.endpoint) === 'string' ? config.endpoint.trim() : '';
-        const credential = typeof (config === null || config === void 0 ? void 0 : config.credential) === 'string' ? config.credential.trim() : '';
-        if (!endpoint) {
-            throw new Error('GatewayStore: `endpoint` is empty. A gateway store needs the URL of the gateway ' +
-                '(the host that started this process sets it, e.g. through CN_EG_GATEWAY).');
-        }
-        if (!credential) {
-            throw new Error('GatewayStore: `credential` is empty. A gateway store needs the bearer credential ' +
-                'the gateway issued to this process (e.g. CN_APP_SERVICE_SECRET).');
-        }
-        const fetchImpl = (_a = config.fetch) !== null && _a !== void 0 ? _a : globalThis.fetch;
-        if (typeof fetchImpl !== 'function') {
-            throw new Error('GatewayStore: no `fetch` available; pass one in the config.');
-        }
-        this.endpoint = endpoint.replace(/\/+$/, '');
-        this.credential = credential;
-        this.fetchImpl = fetchImpl;
-    }
-    /**
-     * Checks the gateway answers for this credential: `GET {endpoint}/health`. Resolves with the
-     * gateway's answer; throws {@link GatewayUnreachableError} when the gateway cannot be reached
-     * or refuses the credential. Safe to call more than once; it changes nothing on either side.
-     *
-     * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
-     * fail loudly awaits `init()` itself before registering the store.
-     */
-    async init() {
-        return (await this.request('GET', '/health'));
-    }
-    selectQuery(query) {
-        return this.send('select', query.toJSON());
-    }
-    askQuery(query) {
-        return this.send('ask', query.toJSON());
-    }
-    updateQuery(query) {
-        return this.send('update', query.toJSON());
-    }
-    createQuery(query) {
-        return this.send('create', query.toJSON());
-    }
-    deleteQuery(query) {
-        return this.send('delete', query.toJSON());
-    }
-    async send(op, query) {
-        const body = (await this.request('POST', '/query', {
-            v: GATEWAY_WIRE_VERSION,
-            op,
-            query,
-        }));
-        if (!body || typeof body !== 'object' || !('result' in body)) {
-            throw new GatewayStoreError(`GatewayStore: the gateway answered ${op} without a result`, 200, 'bad-response', body);
-        }
-        return body.result;
-    }
-    async request(method, route, json) {
-        const url = this.endpoint + route;
-        const headers = {
-            Authorization: `Bearer ${this.credential}`,
-            Accept: 'application/json',
-        };
-        const init = { method, headers };
-        if (json !== undefined) {
-            headers['Content-Type'] = 'application/json';
-            init.body = JSON.stringify(json);
-        }
-        let response;
-        try {
-            response = await this.fetchImpl(url, init);
-        }
-        catch (err) {
-            const cause = err instanceof Error ? err.message : String(err);
-            throw new GatewayUnreachableError(`GatewayStore: cannot reach the gateway at ${url}: ${cause}`, 0, 'unreachable');
-        }
-        const text = await response.text();
-        let body = undefined;
-        if (text) {
-            try {
-                body = JSON.parse(text);
-            }
-            catch (_a) {
-                body = text;
-            }
-        }
-        if (response.ok)
-            return body;
-        const code = body && typeof body === 'object' && typeof body.code === 'string'
-            ? body.code
-            : `http-${response.status}`;
-        const detail = body && typeof body === 'object' && typeof body.error === 'string'
-            ? body.error
-            : typeof body === 'string' && body
-                ? body
-                : response.statusText;
-        const message = `GatewayStore: ${method} ${url} answered ${response.status} (${code})${detail ? `: ${detail}` : ''}`;
-        if (response.status === 401) {
-            throw new GatewayUnreachableError(message, 401, code, body);
-        }
-        throw new GatewayStoreError(message, response.status, code, body);
-    }
-}
-//# sourceMappingURL=GatewayStore.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"GatewayStore.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/GatewayStore.ts"],"names":[],"mappings":"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","sourcesContent":["import 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 GatewayStore(config)` — the `config` object of a\n * `linked.backend.datasets.json` entry, passed verbatim by `loadStores`.\n */\nexport interface GatewayStoreConfig {\n  /** Base URL of the gateway, e.g. `http://localhost:4040/gateway`. Routes are appended to it. */\n  endpoint: string;\n  /** The bearer credential the gateway issued to this process. */\n  credential: string;\n  /** Transport override; defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n}\n\n/** The op names on the wire; each is the `IDataset` method the store was called on. */\nexport type GatewayOp = 'select' | 'ask' | 'update' | 'create' | 'delete';\n\n/** The wire version this store speaks. The gateway refuses any other with `code: \"wire-version\"`. */\nexport const GATEWAY_WIRE_VERSION = 1;\n\n/**\n * A non-2xx answer from the gateway. `code` is the body's `code` when the gateway sent one\n * (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),\n * else a generic one; `body` is the parsed response when it was JSON.\n */\nexport class GatewayStoreError extends Error {\n  readonly status: number;\n  readonly code: string;\n  readonly body?: unknown;\n\n  constructor(message: string, status: number, code: string, body?: unknown) {\n    super(message);\n    this.name = new.target.name;\n    this.status = status;\n    this.code = code;\n    this.body = body;\n  }\n}\n\n/**\n * The gateway could not be used at all: the request never got an HTTP answer (network error,\n * `status` 0), or the gateway refused the credential (401). Thrown by `init()` and by every\n * query method; a process that gets this at boot should stop rather than carry on without data.\n */\nexport class GatewayUnreachableError extends GatewayStoreError {}\n\n/** What `GET {endpoint}/health` answers with a valid credential. */\nexport interface GatewayHealth {\n  projectId: string;\n  branchName: string;\n  dataset: string;\n}\n\n/**\n * An {@link IDataset} that forwards every Linked Query to a gateway over HTTP and returns\n * the gateway's result as is.\n *\n * Each query method posts `{v, op, query: query.toJSON()}` to `POST {endpoint}/query` with\n * `Authorization: Bearer <credential>` and resolves with the body's `result` — the same plain\n * JSON rows `BackendAPIStore` returns. The gateway decides which dataset the query runs on\n * from the credential; the store carries no project, branch or actor.\n *\n * Unlike `BackendAPIStore` it does not go through `Server.call` and has no dependency on\n * the process's own HTTP server: it is meant for a backend whose data lives behind another\n * service, selected from `linked.backend.datasets.json` by the host that started it.\n *\n * The store offers no raw SPARQL (`rawQuery`), no dataset administration and no change feed.\n */\nexport class GatewayStore implements IDataset {\n  readonly endpoint: string;\n  private readonly credential: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: GatewayStoreConfig) {\n    const endpoint = typeof config?.endpoint === 'string' ? config.endpoint.trim() : '';\n    const credential = typeof config?.credential === 'string' ? config.credential.trim() : '';\n    if (!endpoint) {\n      throw new Error(\n        'GatewayStore: `endpoint` is empty. A gateway store needs the URL of the gateway ' +\n          '(the host that started this process sets it, e.g. through CN_EG_GATEWAY).',\n      );\n    }\n    if (!credential) {\n      throw new Error(\n        'GatewayStore: `credential` is empty. A gateway store needs the bearer credential ' +\n          'the gateway issued to this process (e.g. CN_APP_SERVICE_SECRET).',\n      );\n    }\n    const fetchImpl = config.fetch ?? globalThis.fetch;\n    if (typeof fetchImpl !== 'function') {\n      throw new Error('GatewayStore: no `fetch` available; pass one in the config.');\n    }\n    this.endpoint = endpoint.replace(/\\/+$/, '');\n    this.credential = credential;\n    this.fetchImpl = fetchImpl;\n  }\n\n  /**\n   * Checks the gateway answers for this credential: `GET {endpoint}/health`. Resolves with the\n   * gateway's answer; throws {@link GatewayUnreachableError} when the gateway cannot be reached\n   * or refuses the credential. Safe to call more than once; it changes nothing on either side.\n   *\n   * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must\n   * fail loudly awaits `init()` itself before registering the store.\n   */\n  async init(): Promise<GatewayHealth> {\n    return (await this.request('GET', '/health')) as GatewayHealth;\n  }\n\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number> {\n    return this.send('select', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.send('ask', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.send('update', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.send('create', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.send('delete', query.toJSON());\n  }\n\n  private async send<T>(op: GatewayOp, query: unknown): Promise<T> {\n    const body = (await this.request('POST', '/query', {\n      v: GATEWAY_WIRE_VERSION,\n      op,\n      query,\n    })) as { result?: T } | null;\n    if (!body || typeof body !== 'object' || !('result' in body)) {\n      throw new GatewayStoreError(\n        `GatewayStore: the gateway answered ${op} without a result`,\n        200,\n        'bad-response',\n        body,\n      );\n    }\n    return body.result as T;\n  }\n\n  private async request(method: 'GET' | 'POST', route: string, json?: unknown): Promise<unknown> {\n    const url = this.endpoint + route;\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${this.credential}`,\n      Accept: 'application/json',\n    };\n    const init: RequestInit = { method, headers };\n    if (json !== undefined) {\n      headers['Content-Type'] = 'application/json';\n      init.body = JSON.stringify(json);\n    }\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(url, init);\n    } catch (err) {\n      const cause = err instanceof Error ? err.message : String(err);\n      throw new GatewayUnreachableError(\n        `GatewayStore: cannot reach the gateway at ${url}: ${cause}`,\n        0,\n        'unreachable',\n      );\n    }\n\n    const text = await response.text();\n    let body: unknown = undefined;\n    if (text) {\n      try {\n        body = JSON.parse(text);\n      } catch {\n        body = text;\n      }\n    }\n\n    if (response.ok) return body;\n\n    const code =\n      body && typeof body === 'object' && typeof (body as any).code === 'string'\n        ? ((body as any).code as string)\n        : `http-${response.status}`;\n    const detail =\n      body && typeof body === 'object' && typeof (body as any).error === 'string'\n        ? (body as any).error\n        : typeof body === 'string' && body\n          ? body\n          : response.statusText;\n    const message = `GatewayStore: ${method} ${url} answered ${response.status} (${code})${\n      detail ? `: ${detail}` : ''\n    }`;\n\n    if (response.status === 401) {\n      throw new GatewayUnreachableError(message, 401, code, body);\n    }\n    throw new GatewayStoreError(message, response.status, code, body);\n  }\n}\n"]}