openvibe-sdk/resources: OVRN names, a resource index over authorities and resource control; release 0.34.0 (#18)

OP OpenVibers committed 5 Oct 2026 · tag v0.34. · 0 files, +0 −0
* openvibe-sdk/resources: OVRN names, a resource index over authorities and resource control; release 0.34.0

**Changes (file:line)**
- `src/resources.js:1` — new `openvibe-sdk/resources`: `parseResourceName`/`resourceName`/`resourceNameOf` (delegate to `contracts.resources`, lazily required), `RESOURCE_KINDS:93`, `createResourceIndex:157` (fan-out GET `/api/v1/resources?project=&kind=&cursor=&limit=`, concurrency pool, per-authority `next_cursor` walk, merged pages, failed authority reported in `stale`), `createResourceClient:276` (POST `common.resource-control-request@1` to `/api/v1/resources/control`, generated/stable idempotency key, transient retries, returns refused results).
- `index.js:26` — `resources: require('./src/resources')`.
- `package.json:3` — `0.34.0`; `package.json:108` — `"./resources"` export with `"browser": null` beside `./usage`.
- `package-lock.json:3,9` — `0.34.0`.
- `src/core/index.js:11` — `SDK_VERSION = '0.34.0'`.
- `scripts/esm.js:33` — `'resources.mjs'` entry.
- `esm/resources.mjs` (new, generated), `esm/index.mjs:10` (regenerated).
- `types/resources.d.ts:1` (new) — declares all six runtime exports.
- `types/index.d.ts:17` — `export * as resources`.
- `README.md:5,12` — status/install `0.34.0`; `README.md:182` — API-table row.
- `STATUS.json:6` — `0.34.0`.
- `CHANGELOG.md:10` — new `## 0.34.0 (2026-10-05)` entry.
- `browser/openvibe-sdk.mjs:1` — regenerated (`node scripts/browser-bundle.js`; version only, `resources` is server-only).
- `docs/service.md:245` — new "The resource index and the control plane" section.
- `test/resources.test.js:1` (new) — compose/reject OVRN + catalog, merge two authorities, cursor walk, stale-on-500 (keeps pages read, reports `{authority,status,code,error}`), control posts/retries-same-key/refused, invalid request never sent.
- `test/pack.test.js:25,69` — add resources files to tarball list, subpath count 41 → 42.
- `test/browser-entries.test.js:79` — add `'./resources'` to the `browser: null` blocked list.

**Tests** — `ov test test/resources.test.js test/esm.test.js test/browser-entries.test.js test/pack.test.js test/types.test.js` → **5 passed in 3 s**. Also ran the release bookkeeping tests my version bump/bundle touch: `ov test test/version.test.js test/bundle.test.js` → **2 passed in 1 s**. Not committed or pushed.

* Resource index: bounded paging (repeat cursors, maxPages, maxMs, empty cursor); control returns refused/failed bodies, carries the idempotency key on errors, validates strictly; STATUS lists the module (review)

All six findings are fixed, each with a test in `test/resources.test.js`. No commit or push.

**Findings**

1. **Unbounded paging** — `walk()` now keeps a `Set` of seen cursors, throws `sdk.bad_response` ("cursor repeated") on a repeat/echo, adds `maxPages` (default 1000, `sdk.bad_response` "did not end after N pages") and an optional per-authority `maxMs` deadline (`sdk.timeout`); each keeps pages read and reports the authority stale (`src/resources.js:200-229`, opts `:170`, validation `:176-177`, constant `:105`). Tests: two-cursor cycle, endless new cursors at `maxPages: 3`, `maxMs` deadline (`test/resources.test.js:158,176,190`).

2. **Refused/failed on non-2xx thrown** — before throwing, a non-retryable non-2xx whose body is refused/failed with a `problem` or `confirmation_required` is returned (`src/resources.js:263-267,357-361`); a 5xx still retries first, and a plain 403/5xx still throws. Tests: 409 refused body returned, 503 refused body retries then throws, 403 without a result still throws (`test/resources.test.js:213,227,242`).

3. **Idempotency key lost on throw** — every error thrown from `control()` (network/timeout, HTTP, bad response) now carries `err.idempotencyKey` (`src/resources.js:349,360,366`), documented at `:301-311`. `idempotency_key` is now optional and documented in `types/resources.d.ts:31-32,92`. Tests: generated key returned to caller and matched to what the authority saw (`test/resources.test.js:254`).

4. **Validation degrading to weak check** — `checkControlRequest` catches only `MODULE_NOT_FOUND` around the `require`; a real throw from `contracts.resources.checkControlRequest` propagates, and the shape check (`shapeCheckControlRequest`) runs only when the module is absent (`src/resources.js:269-295`). Tests: a patched validator throw propagates with no request sent; the project-tenancy rule rejects a cross-project resource (`test/resources.test.js:270,288`).

5. **STATUS.json missing module** — added the `resources (openvibe-sdk/resources)` capability entry (`STATUS.json:31`); test asserts it and that `version` matches `package.json` (`test/resources.test.js:300`).

6. **Empty cursor passed on** — `next === ''` ends the walk, and `page()` never sends `cursor=` for an empty string (`src/resources.js:218,185`); test asserts one request and no stale (`test/resources.test.js:202`).

Docs kept accurate: CHANGELOG 0.34.0 entry (index bounds, non-2xx refused/failed, `idempotencyKey` on thrown errors) and the README option list (`maxPages`, `maxMs`). No export change, so `esm/resources.mjs` needed no regeneration. Fixture keys are plain words (`conflict-refused-key`, `busy-refused-key`, `forbidden-test-key`, `validator-test-key`, `tenancy-test-key`).

**Tests** — `ov test test/resources.test.js test/types.test.js test/pack.test.js test/esm.test.js`: 4 passed in 2 s (esm 0.3 s, pack 1.7 s, resources 0.7 s, types 0.1 s).
This commit has no diff to show.