stratus-db 0.2.1 → 0.4.0

package/README.md

@@ -57,22 +57,22 @@ Gateway's 403 Forbidden for a brand-new key, which works within a minute or two
 - Catalog: `listDbs({deleted})`, `dbByName(name)`, `dbRecord(id)`, `createDb({name, primaryKey})`,
   `renameDb(id, name)`, `deleteDb(id)`.
 - A database: `status(id)`, `transact(id, {tx, retract, delete, txId, match})`, `query(id, q)`,
-  `queryAll(id, q)` (async iterator), `pull(id, pks, {asOf})` (and `asOf: t` in a query: the database as it stood after t), `requestIndex(id, att)`,
+  `queryAll(id, q)` (async iterator), `pull(id, pks, {asOf})` (and `asOf: t` in a query: the database as it stood after t), `requestIndex(id, att, {required})` (att an attribute, or an array of 2 to 8 for a
+  multi-attribute index: queried by tuples, `["=", ["a", "b"], [x, y]]`; docs/query.md),
   `awaitIndex(id, att)`, `dropIndex(id, att)`, `history(id, {from, limit})`, `historyAll`,
-  `fork(id, {t, name})` (hosted: a new database, this one as of t), `excise(id, {rows,
+  `fork(id, {t, name})` (a new database, this one as of t), `excise(id, {rows,
   attributes})` (erasure: rows and {pk, att} out of the state, indexes, history and forks),
   `setHistoryRetention(id, days)` (history kept 30 to 36500 days, or `null` for forever).
-- Keys (hosted, with a key reaching every database): `listKeys()`, `createKey({name, scope})`,
+- Keys (with a key reaching every database): `listKeys()`, `createKey({name, scope})`,
   `revokeKey(keyId)`.
 - Codec: `encode`, `decode` (typed-JSON text), `toJSONValue`, `fromJSONValue`.
 
-Queries: docs/query.md ("JSON"). Addressing: `"hosted"` (default: `<url>/v1/dbs/<id>/...`,
-`Authorization: Bearer <apiKey>`) or `"function-urls"` (the internal service's Function URLs,
-resolved through its catalog; `caller` for a local service).
+Queries: docs/query.md ("JSON"). Requests go to `<url>/v1/dbs/<id>/...` with `Authorization:
+Bearer <apiKey>`.
 
 ## Tests
 
 `node --test test/ejson.test.js` (the codec: velojity's own output in
 `clients/fixtures/velojity-ejson.json`, which stratus's client-fixtures-test keeps current), and
-`scripts/test-js-client` from the repo root: the codec, then the client against the local
-service.
+`scripts/test-js-client` from the repo root: the codec, then the client against the hosted
+product run locally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratus-db",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "The stratus-db service from JavaScript: typed JSON over fetch, no dependencies.",
   "homepage": "https://stratus-db.com",
   "license": "Apache-2.0",

package/stratus-db.js

@@ -11,14 +11,11 @@
 //   await s.transact(id, { tx: [{ "order/id": squuid(), "order/status": kw("status/new") }] });
 //   const { rows } = await s.query(id, { where: ["=", "order/status", kw("status/new")] });
 //
-// Addressing: "hosted" (the default) - the catalog at <url>/v1/dbs, a database at
-// <url>/v1/dbs/<id>/..., the API key as "Authorization: Bearer <key>". "function-urls" - the
-// internal service: the catalog at url, each database at the Function URL its catalog record
-// names (looked up, cached for resolveMs, and again when one answers 403 or 404); for testing
-// against a local service, opts.caller names the caller (x-stratus-caller).
+// Addressing: the catalog at <url>/v1/dbs, a database at <url>/v1/dbs/<id>/..., the API key as
+// "Authorization: Bearer <key>".
 
 /** The client's version: package.json's, which release-js.yml checks against it. */
-export const VERSION = "0.2.1";
+export const VERSION = "0.4.0";
 
 const USER_AGENT = `stratus-db-js/${VERSION}`;
 const IN_NODE = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
@@ -532,6 +529,15 @@ function queryString(params) {
 
 function attName(att) { return att instanceof Keyword ? att.fullName : String(att).replace(/^:/, ""); }
 
+// An index's name: an attribute's, or a multi-attribute index's (an array) joined by commas -
+// how the status keys it, and the DELETE path names it.
+function indexName(att) { return Array.isArray(att) ? att.map(attName).join(",") : attName(att); }
+
+// The DELETE path of an index: each name's parts encoded, its slashes and commas kept.
+function indexPath(att) {
+  return indexName(att).split(",").map((n) => n.split("/").map(encodeURIComponent).join("/")).join(",");
+}
+
 /** A client of the stratus service at opts.url (see the module's comment for opts). */
 export function connect(opts) {
   return new Client(opts);
@@ -542,28 +548,20 @@ const GATEWAY_FORBIDDEN = /^\s*\{\s*"message"\s*:\s*"Forbidden"\s*\}\s*$/;
 export class Client {
   /**
    * @param {object} opts
-   * @param {string} opts.url            the service's base URL (hosted), or the catalog's URL (function-urls)
+   * @param {string} opts.url            the service's base URL
    * @param {string} [opts.apiKey]       sent as "Authorization: Bearer <key>"
-   * @param {"hosted"|"function-urls"} [opts.addressing]
-   * @param {string} [opts.caller]       x-stratus-caller, for a local service
    * @param {number} [opts.retries]      attempts after a 429 (default 10)
    * @param {number} [opts.newKeyWaitMs] how long to keep retrying API Gateway's own 403 Forbidden, which a
    *                                     brand-new key gets for its first minute or so (default 120000; 0: never)
-   * @param {number} [opts.resolveMs]    function-urls: how long a database's URL is cached (5 minutes)
    * @param {typeof fetch} [opts.fetch]  default globalThis.fetch
    */
   constructor(opts) {
     if (!opts?.url) throw new TypeError("connect needs { url }");
     this.url = trimSlash(opts.url);
-    this.addressing = opts.addressing ?? "hosted";
-    if (!["hosted", "function-urls"].includes(this.addressing)) throw new TypeError(`addressing: ${this.addressing}`);
     this.apiKey = opts.apiKey;
-    this.caller = opts.caller;
     this.retries = opts.retries ?? 10;
     this.newKeyWaitMs = opts.newKeyWaitMs ?? 120000;
-    this.resolveMs = opts.resolveMs ?? 300000;
     this.fetch = opts.fetch ?? globalThis.fetch;
-    this.urls = { at: 0, byId: new Map() };
   }
 
   // -- requests
@@ -574,7 +572,6 @@ export class Client {
     if (IN_NODE) headers["user-agent"] = USER_AGENT;
     if (body !== undefined) headers["content-type"] = "application/json";
     if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
-    if (this.caller) headers["x-stratus-caller"] = this.caller;
     const started = Date.now();
     for (let attempt = 0, forbidden = 0; ; attempt++) {
       const r = await this.fetch(url, { method, headers, body: body === undefined ? undefined : encode(body) });
@@ -606,42 +603,14 @@ export class Client {
     throw new StratusError(r.status, isObj ? b.error : null, isObj ? b.message : String(b ?? ""), b);
   }
 
-  catalogUrl(path) {
-    return this.addressing === "hosted" ? `${this.url}/v1${path}` : `${this.url}${path}`;
-  }
-
   /** method path body to the catalog: { status, body }. */
   callCatalog(method, path, body) {
-    return this.send(this.catalogUrl(path), method, body);
-  }
-
-  async resolve() {
-    const recs = Client.ok(await this.callCatalog("GET", "/dbs"));
-    const byId = new Map();
-    for (const r of recs) if (r.url) byId.set(String(r.id), r.url);
-    this.urls = { at: Date.now(), byId };
-    return byId;
-  }
-
-  async dbBase(id) {
-    const key = String(id);
-    if (this.addressing === "hosted") return `${this.url}/v1/dbs/${encodeURIComponent(key)}`;
-    const { at, byId } = this.urls;
-    if (byId.has(key) && Date.now() - at < this.resolveMs) return trimSlash(byId.get(key));
-    const u = (await this.resolve()).get(key);
-    return u === undefined ? null : trimSlash(u);
+    return this.send(`${this.url}/v1${path}`, method, body);
   }
 
   /** method path body to database id: { status, body }. */
-  async callDb(id, method, path, body) {
-    const base = await this.dbBase(id);
-    if (base === null) return { status: 404, body: { error: "no-database", message: `No database ${id}` } };
-    const r = await this.send(base + path, method, body);
-    if (this.addressing === "function-urls" && (r.status === 403 || r.status === 404)) {
-      const again = (await this.resolve()).get(String(id));
-      if (again !== undefined && trimSlash(again) !== base) return this.send(trimSlash(again) + path, method, body);
-    }
-    return r;
+  callDb(id, method, path, body) {
+    return this.send(`${this.url}/v1/dbs/${encodeURIComponent(String(id))}${path}`, method, body);
   }
 
   // -- the catalog
@@ -676,7 +645,7 @@ export class Client {
     return Client.ok(await this.callCatalog("DELETE", `/dbs/${encodeURIComponent(String(id))}`));
   }
 
-  // -- keys (hosted: an account's keys, managed with a key whose scope is every database)
+  // -- keys (an account's keys, managed with a key whose scope is every database)
 
   /** The account's keys' records (no secrets). */
   async listKeys() {
@@ -700,7 +669,7 @@ export class Client {
 
   /** The database's state: { id, "primary-key", t, "checkpoint-t", indexes, "index-errors", status }. */
   async status(id) {
-    return Client.ok(await this.callDb(id, "GET", this.addressing === "hosted" ? "/status" : "/"));
+    return Client.ok(await this.callDb(id, "GET", "/status"));
   }
 
   /**
@@ -743,18 +712,26 @@ export class Client {
     return (Client.ok(await this.callDb(id, "POST", "/pull", asOf === undefined ? { pks } : { pks, "as-of": asOf }))).rows;
   }
 
-  /** Requests a value index on att: { att, state } ("building" until a checkpoint builds it). */
-  async requestIndex(id, att) {
-    return Client.ok(await this.callDb(id, "POST", "/indexes", { att: attName(att) }));
+  /**
+   * Requests a value index on att: { att, state } ("building" until a checkpoint builds it).
+   * att is an attribute, or an array of 2 to 8 for a multi-attribute index (its rows keyed by
+   * the tuple of their values; queried by tuple predicates), with { required }: the attributes
+   * a row needs a value of to be in it.
+   */
+  async requestIndex(id, att, { required } = {}) {
+    const body = { att: Array.isArray(att) ? att.map(attName) : attName(att) };
+    if (required !== undefined) body.required = required.map(attName);
+    return Client.ok(await this.callDb(id, "POST", "/indexes", body));
   }
 
+  /** Drops att's index (an attribute, or a multi-attribute index's array). */
   async dropIndex(id, att) {
-    return Client.ok(await this.callDb(id, "DELETE", `/indexes/${attName(att).split("/").map(encodeURIComponent).join("/")}`));
+    return Client.ok(await this.callDb(id, "DELETE", `/indexes/${indexPath(att)}`));
   }
 
   /** Waits until att's index is ready (rejects if it failed, or after timeoutMs). */
   async awaitIndex(id, att, { timeoutMs = 60000, intervalMs = 200 } = {}) {
-    const name = attName(att);
+    const name = indexName(att);
     const deadline = Date.now() + timeoutMs;
     for (;;) {
       const s = await this.status(id);
@@ -767,7 +744,7 @@ export class Client {
   }
 
   /**
-   * Forks database id (hosted): a new database, this one as of t (default its latest), recorded
+   * Forks database id: a new database, this one as of t (default its latest), recorded
    * in both logs. The fork's record ({ id, "fork-of": { db, t }, ... }).
    */
   async fork(id, { t, name } = {}) {
@@ -779,7 +756,7 @@ export class Client {
 
   /**
    * Excises rows (primary keys) and attributes ({ pk, att }) - erasure: gone from the current
-   * state, its indexes and history (and, hosted, the database's forks): { t, rows, attributes }.
+   * state, its indexes and history (and the database's forks): { t, rows, attributes }.
    */
   async excise(id, { rows, attributes } = {}) {
     const body = {};