@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/resources.js

@@ -0,0 +1,408 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const { fail, isObject } = require('./errors');
+const { normalizeCameraBlock } = require('./camera');
+
+/**
+ * Account-scoped reads and the optional pre-registration write.
+ *
+ * Contract: `docs/architecture/account-client-sdk-contract.zh-CN.md` §6.4 (the
+ * method surface), §6.5 (camelCase at the boundary), §7.2–§7.4 (the endpoints)
+ * and §7.9 (the `camera` block); decisions in `docs/ACCOUNT_CLIENT_SDK_PLAN.md`
+ * §0.2 and §0.4.
+ *
+ * Two properties are load-bearing and both are the reason this module exists as
+ * a separate, dependency-injected unit rather than five methods pasted onto the
+ * client:
+ *
+ * 1. **Nothing here is cached.** §1.2 and plan §0.2 make the SDK stateless: it
+ *    holds an installation identity and nothing else — no camera list, no
+ *    station list, no key→uid map. `listCameras()` is an ordinary query whose
+ *    answer is stale the moment it returns, because the account can gain, lose
+ *    or disable a camera on the web console without rebinding anything. A
+ *    memoized list would silently become an authorization snapshot, which is
+ *    exactly the model §1.2 exists to forbid. Every call is a fresh request.
+ * 2. **No caller ever names an owner.** §7.3 and §10.4: the server narrows every
+ *    query from the token subject's `ownerUserId` and `tenantId`. A query key
+ *    that looks like a principal is refused here, locally, rather than being
+ *    forwarded for the server to ignore — forwarding teaches integrators a
+ *    parameter that does nothing, and the day it stops being ignored it is a
+ *    cross-tenant read.
+ *
+ * The module takes its request performer by injection (`createResources`)
+ * because `index.js` owns the authenticated `_request` — token minting, DPoP,
+ * retry and 401 re-assert — and requiring `index.js` from `lib/` would close a
+ * cycle.
+ */
+
+/** Mirrors `DEVICE_ROOT` in index.js; duplicated rather than imported to keep this module acyclic. */
+const DEVICE_ROOT = '/cloud/device-api/mscloud';
+
+const CAMERA_UID_RE = /^cam_[0-9a-f]{32}$/;
+const STATION_UID_RE = /^st_[0-9a-f]{32}$/;
+/**
+ * §7.9: `camera.key` is 1–64 safe ASCII and carries no PII. "Safe" is read here
+ * as the same alphabet `clientRequestKey` already uses in index.js, so the key
+ * survives a URL path, a log line and a SQL identifier column untouched. A host
+ * app that would rather use its channel name may — as long as it is in this
+ * alphabet, and as long as it accepts that renaming the channel creates a new
+ * camera (§0.2).
+ */
+const CAMERA_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+/**
+ * Filter values are checked for shape, never against an enum. §6.5 wrote
+ * `status` as `active|disabled`, and the server has neither: stations are
+ * `active|revoked|archived` (`MsCloudStationSaveReqVO`,
+ * `MsCloudStationKinds.STATUS_ARCHIVED`) and cameras `active|revoked`
+ * (`MsCloudCameraSaveReqVO`). That drift is the argument for shape-only: a
+ * client-side allowlist of values would have refused a filter the server
+ * accepts, and would turn every future server state into an SDK bug. The server
+ * judges meaning.
+ */
+const FILTER_VALUE_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+/**
+ * `PageParam`'s own ceiling (`@Min(1) @Max(200)` on `pageSize`), mirrored so a
+ * caller asking for 1000 rows learns it here rather than from a Bean Validation
+ * 400 whose message is a localized "每页条数最大值为 200".
+ *
+ * Not a paging strategy of ours: the SDK caches nothing and iterates nothing on
+ * the caller's behalf, so this only rejects a number the server would.
+ */
+const MAX_PAGE_SIZE = 200;
+
+/** Query keys each list endpoint accepts, in the order they are emitted. */
+const STATION_QUERY_KEYS = Object.freeze(['pageNo', 'pageSize', 'status']);
+const CAMERA_QUERY_KEYS = Object.freeze(['pageNo', 'pageSize', 'stationUid', 'status']);
+
+/** Anything smelling of a principal. Refused with a message that says why. */
+const PRINCIPAL_KEY_RE = /(owner|tenant|user|account|subject|creator|dept|member)/i;
+
+const OK = new Set([200]);
+/** `cameras/ensure` upserts: 200 when it found one, 201 when it created one. */
+const OK_OR_CREATED = new Set([200, 201]);
+
+/**
+ * Deep key rewriting stops here. The summaries in §6.5 are flat records, so
+ * nothing legitimate is anywhere near this depth — but `decodeEnvelope` accepts
+ * a 2 MiB body from a server that may be having a bad day, and a stack overflow
+ * inside normalization would escape as a raw RangeError. That breaks the
+ * SDK-wide invariant that MeteorCloudError is the only error thrown, and any
+ * retry classifier that keys off `instanceof MeteorCloudError` then guesses.
+ * Past the cap the subtree is passed through untouched rather than rejected:
+ * the payload is still the server's answer, it is just not renamed.
+ */
+const MAX_NORMALIZE_DEPTH = 32;
+
+/** Truncated so a hostile or fat-fingered key cannot bloat a logged error. */
+function describeKey(key) {
+  const text = String(key);
+  return text.length > 64 ? `${text.slice(0, 61)}...` : text;
+}
+
+/**
+ * `camera_uid` → `cameraUid`, `elevation_m` → `elevationM`.
+ *
+ * Only keys that actually contain an interior `_` are rewritten, so a key that
+ * is already camelCase — which is what §7.4's own example response shows — is
+ * returned by identity, and a leading/trailing/doubled underscore (`_meta`) is
+ * left alone rather than mangled into `Meta`.
+ */
+function camelizeKey(key) {
+  if (typeof key !== 'string' || !key.includes('_')) return key;
+  if (key.startsWith('_') || key.endsWith('_') || key.includes('__')) return key;
+  const [head, ...rest] = key.split('_');
+  return head + rest.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}
+
+/**
+ * Rewrites keys to camelCase everywhere in a decoded payload.
+ *
+ * §6.5 is explicit that a developer must never read `camera_uid` and write back
+ * `cameraUid`, and the server is free to answer in either dialect. So this
+ * renames rather than projects: unknown keys survive (camelCased) instead of
+ * being dropped, and absent fields stay absent — `positionSigmaHorizontalM` and
+ * the `validFrom|ToUtc` pair are `undefined` until a later track ships them, and
+ * a fabricated `null` would be indistinguishable from a server that answered
+ * one. `kind` likewise passes through verbatim: §7.9 and plan §0.4 have it
+ * carrying the real value from day one.
+ *
+ * Recursion is safe on these payloads because they are records, not maps keyed
+ * by caller-supplied strings; there is nothing here whose *key* is data.
+ */
+function camelizeKeys(value, depth = 0) {
+  if (Array.isArray(value)) {
+    return depth >= MAX_NORMALIZE_DEPTH ? value : value.map((item) => camelizeKeys(item, depth + 1));
+  }
+  if (!isObject(value)) return value;
+  if (depth >= MAX_NORMALIZE_DEPTH) return value;
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    const camel = camelizeKey(key);
+    // A server answering both dialects for one field (`cameraUid` *and*
+    // `camera_uid`) must not have a populated value clobbered by an empty one.
+    if (result[camel] !== undefined && result[camel] !== null) continue;
+    result[camel] = camelizeKeys(item, depth + 1);
+  }
+  return result;
+}
+
+function normalizeRecord(data, what) {
+  if (!isObject(data)) fail(`${what} response was not an object`, { kind: 'device_api' });
+  return camelizeKeys(data);
+}
+
+/** §7.2 `AccountSummary`. */
+function normalizeAccount(data) {
+  return normalizeRecord(data, 'account');
+}
+
+/** §6.5 `StationSummary`. */
+function normalizeStation(data) {
+  return normalizeRecord(data, 'station');
+}
+
+/** §6.5 `CameraSummary`. */
+function normalizeCamera(data) {
+  return normalizeRecord(data, 'camera');
+}
+
+/**
+ * The `{list, total}` page both list endpoints return (§7.4).
+ *
+ * `list` defaults to `[]` when the server omits it — the method's whole contract
+ * is "a page", and every caller iterates the result — but `total` is passed
+ * through exactly as sent, including absent. Any other container key survives,
+ * camelCased, so a later `hasMore`/`nextCursor` reaches callers without an SDK
+ * release.
+ */
+function normalizePage(data, what) {
+  const page = normalizeRecord(data, what);
+  if (page.list !== undefined && page.list !== null && !Array.isArray(page.list)) {
+    fail(`${what} response carried a non-array list`, { kind: 'device_api' });
+  }
+  return { ...page, list: page.list == null ? [] : page.list };
+}
+
+/**
+ * Turns a caller's filter object into a query string against a strict allowlist.
+ *
+ * Strict is the point. §8's parameter table gives the resource queries exactly
+ * one job — "query 只放分页和过滤" — and §10.4 forbids a caller-supplied owner.
+ * An unknown key is therefore an error rather than a silently dropped field: a
+ * developer who passes `ownerUserId` has a wrong mental model of the trust
+ * boundary, and dropping it quietly lets them keep it.
+ */
+function buildQuery(query, allowed, methodName) {
+  if (query === undefined || query === null) return '';
+  if (!isObject(query)) fail(`${methodName} query must be an object`);
+
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(query)) {
+    if (allowedSet.has(key)) continue;
+    // Checked before the value: `{ownerUserId: undefined}` is still a caller who
+    // believes owner scoping is theirs to set.
+    if (PRINCIPAL_KEY_RE.test(key)) {
+      fail(
+        `${methodName} does not accept ${describeKey(key)}: the server derives owner and tenant `
+        + 'from the token, and the query carries pagination and filters only'
+      );
+    }
+    fail(`${methodName} does not accept the query key ${describeKey(key)}; allowed: ${allowed.join(', ')}`);
+  }
+
+  // Emitted in allowlist order, not caller order, so the request line is
+  // reproducible across callers and easy to assert on.
+  const params = new URLSearchParams();
+  for (const key of allowed) {
+    const value = query[key];
+    if (value === undefined) continue;
+    if (key === 'pageNo' || key === 'pageSize') {
+      if (!Number.isSafeInteger(value) || value < 1) fail(`${methodName} ${key} must be a positive integer`);
+      if (key === 'pageSize' && value > MAX_PAGE_SIZE) {
+        fail(`${methodName} pageSize must be at most ${MAX_PAGE_SIZE}`);
+      }
+      params.set(key, String(value));
+      continue;
+    }
+    if (key === 'stationUid') {
+      if (!STATION_UID_RE.test(value || '')) fail(`${methodName} stationUid is not canonical`);
+      params.set(key, value);
+      continue;
+    }
+    if (typeof value !== 'string' || !FILTER_VALUE_RE.test(value)) {
+      fail(`${methodName} ${key} filter is not a safe token`);
+    }
+    params.set(key, value);
+  }
+  return params.toString();
+}
+
+function withQuery(path, search) {
+  return search ? `${path}?${search}` : path;
+}
+
+/**
+ * A stable key for one host-app channel. Pure local, no network, no state.
+ *
+ * §7.9 makes camera identity `(tenant, owner, originClientId, camera.key)`, and
+ * plan §0.2 puts the key in the *host application's* own configuration: it is
+ * generated once per channel, persisted by the host, and replayed on every
+ * upload. Changing it means "a different camera", so this is called once and
+ * written down — never on each start, and never derived from a hostname, MAC or
+ * anything else identifying (the key must carry no PII).
+ *
+ * 128 bits of `randomBytes` because two independently installed stations must
+ * not collide inside one account.
+ *
+ * @returns {string} 32 lowercase hex characters
+ */
+function newCameraKey() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+/**
+ * Validates the §7.9 `camera` block and returns the exact body to send.
+ *
+ * Delegates to `lib/camera.js`, which is the single definition of these rules.
+ * This module used to carry its own copy as a fallback, and the two drifted
+ * exactly the way duplicated validators do: the copy here accepted `+08:00` as a
+ * timezone, a non-integer `elevationM`, and unbounded names. `index.js` injects
+ * the strict one, so nothing shipped was affected — but a caller who builds
+ * `createResources()` without `validateCamera` would have registered offset
+ * "zones" as permanent station identity, which is the precise failure
+ * `camera.js`'s timezone rule exists to stop. A delegating default cannot drift.
+ */
+function validateCameraBlock(camera, what = 'camera') {
+  return normalizeCameraBlock(camera, what);
+}
+
+/**
+ * Binds the five account-scoped calls to an authenticated request performer.
+ *
+ * @param {object} options
+ * @param {(method: string, path: string, payload: unknown, expected: Set<number>) => Promise<any>}
+ *   options.request the client's authenticated call, returning the decoded envelope `data`
+ * @param {string} [options.root] Device API root, for tests and alternate mounts
+ * @param {(camera: object, what?: string) => object} [options.validateCamera] the canonical
+ *   `camera` block validator. Injected so `ensureCamera()` and `uploadEvent()` can share one
+ *   implementation: §7.9 requires the pre-registration path to behave *identically* to the
+ *   upsert that happens during an upload, and two copies of the rules drift.
+ */
+function createResources(options = {}) {
+  const request = options.request;
+  if (typeof request !== 'function') fail('createResources requires a request performer');
+  const root = options.root || DEVICE_ROOT;
+  const validateCamera = options.validateCamera || validateCameraBlock;
+
+  /**
+   * §7.2. The minimum summary of the authorized account — no phone number, no
+   * department, no roles (§10.4).
+   *
+   * @returns {Promise<{accountId: string, nickname: string, tenantId?: string}>}
+   */
+  async function getAccount() {
+    return normalizeAccount(await request('GET', `${root}/account`, undefined, OK));
+  }
+
+  /**
+   * §7.3. The stations already registered under this account.
+   *
+   * Not a snapshot and not cached: call it when the host application's UI needs
+   * the list, and not on connect, renewal or upload.
+   *
+   * @param {{pageNo?: number, pageSize?: number, status?: string}} [query]
+   */
+  async function listStations(query) {
+    const search = buildQuery(query, STATION_QUERY_KEYS, 'listStations');
+    return normalizePage(
+      await request('GET', withQuery(`${root}/stations`, search), undefined, OK),
+      'stations'
+    );
+  }
+
+  /**
+   * §7.4. The cameras already registered under this account.
+   *
+   * "Query the cameras this account has on MeteorCloud" — never "scan the
+   * machine's cameras" (§7.4 is explicit about the wording, because the two got
+   * confused once already). A host app that already holds a valid `cameraUid`,
+   * or that reports with a `camera` block, never needs this at all.
+   *
+   * @param {{pageNo?: number, pageSize?: number, stationUid?: string, status?: string}} [query]
+   */
+  async function listCameras(query) {
+    const search = buildQuery(query, CAMERA_QUERY_KEYS, 'listCameras');
+    return normalizePage(
+      await request('GET', withQuery(`${root}/cameras`, search), undefined, OK),
+      'cameras'
+    );
+  }
+
+  /**
+   * §7.4. One camera by uid.
+   *
+   * The shape is checked locally first so a typo costs nothing, and the uid is
+   * interpolated unescaped only because that check leaves nothing but `cam_`
+   * and hex. A 404 is deliberately allowed to surface: §9.4 has the server
+   * answer 404 for both "does not exist" and "is not yours" precisely so the
+   * two cannot be told apart, and softening it to `null` would erase the one
+   * signal an integrator needs — that this uid is not usable by this account.
+   */
+  async function getCamera(cameraUid) {
+    if (!CAMERA_UID_RE.test(cameraUid || '')) fail('cameraUid is not canonical');
+    return normalizeCamera(await request('GET', `${root}/cameras/${cameraUid}`, undefined, OK));
+  }
+
+  /**
+   * §7.9's optional pre-registration endpoint. The request body *is* the
+   * `camera` block; the upsert is the same one an upload performs.
+   *
+   * Optional means optional: the supported path is to carry the block on each
+   * `uploadEvent()` and let the server register on first sight (plan §0.2). This
+   * exists for a host app that wants a uid before it has an event to send — and
+   * even then the returned uid does not have to be stored, because the block
+   * alone identifies the camera forever after.
+   *
+   * @param {{key: string, name?: string, station: {latitude: number, longitude: number,
+   *   elevationM: number, timezone: string, name?: string}}} input
+   * @returns {Promise<{cameraUid: string, stationUid: string, createdCamera?: boolean,
+   *   createdStation?: boolean}>}
+   */
+  async function ensureCamera(input) {
+    // The likeliest mistake, named rather than met with "key must be 1-64…":
+    // the block is nested under `camera` in an uploadEvent request, and flat
+    // here.
+    if (isObject(input) && input.camera !== undefined) {
+      fail('ensureCamera takes the camera block itself ({key, name?, station}), not {camera: {...}}');
+    }
+    const body = validateCamera(input, 'camera');
+    return normalizeRecord(
+      await request('POST', `${root}/cameras/ensure`, body, OK_OR_CREATED),
+      'ensureCamera'
+    );
+  }
+
+  return { getAccount, listStations, listCameras, getCamera, ensureCamera, newCameraKey };
+}
+
+module.exports = {
+  DEVICE_ROOT,
+  CAMERA_UID_RE,
+  STATION_UID_RE,
+  CAMERA_KEY_RE,
+  MAX_PAGE_SIZE,
+  STATION_QUERY_KEYS,
+  CAMERA_QUERY_KEYS,
+  createResources,
+  newCameraKey,
+  validateCameraBlock,
+  camelizeKey,
+  camelizeKeys,
+  normalizeAccount,
+  normalizeStation,
+  normalizeCamera,
+  normalizePage
+};