@_linked/server 2.24.11 → 2.25.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @\_linked/server
 
+## 2.25.0
+
+### Minor Changes
+
+- [#177](https://github.com/linked-fw/server/pull/177) [`781e5d0`](https://github.com/linked-fw/server/commit/781e5d0f41a8fa7a2e0984f9740003968511c759) Thanks [@flyon](https://github.com/flyon)! - GatewayStore: an IDataset that forwards Linked Queries to a gateway. Exported at `@_linked/server/shapes/quadstores/GatewayStore` so an app can select it from `linked.backend.datasets.json`; it posts each query as DSL-JSON with a bearer credential and throws `GatewayUnreachableError` from `init()` when the gateway does not answer.
+
 ## 2.24.11
 
 ### Patch Changes

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

@@ -0,0 +1,85 @@
+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

@@ -0,0 +1,143 @@
+/** 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

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

package/package.json

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

package/readme.md

@@ -19,6 +19,9 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Generic backend providers](#generic-backend-providers)
   - [Gotchas](#gotchas)
   - [Error semantics](#error-semantics)
+- [Query stores](#query-stores)
+  - [BackendAPIStore](#backendapistore)
+  - [GatewayStore](#gatewaystore)
 - [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)
@@ -232,6 +235,72 @@ What the caller sees depends on how it calls:
   - 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.
 
+## 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.
+
+| | `BackendAPIStore` | `GatewayStore` |
+| --- | --- | --- |
+| 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 |
+
+### BackendAPIStore
+
+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).
+
+### GatewayStore
+
+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.
+
+```json
+{
+  "datasets": {
+    "gateway": {
+      "store": "@_linked/server/shapes/quadstores/GatewayStore",
+      "config": { "endpoint": "${CN_EG_GATEWAY:-}", "credential": "${CN_APP_SERVICE_SECRET:-}" }
+    }
+  }
+}
+```
+
+```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`.
+
 ## 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: