@7365admin1/core 3.42.2 → 3.43.0

package/test/camera-capability.util.test.mjs

@@ -0,0 +1,545 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  CAMERA_CAPABILITIES,
+  CAMERA_CAPABILITY_REASONS,
+  TRANSPORT_DEVICE_HTTP,
+  TRANSPORT_RELAY_PLAYER,
+  TRANSPORT_RTSP_FRAME,
+  cameraCapabilitiesFor,
+  cameraTransports,
+  describeCameraCapabilities,
+  deviceControlEnabled,
+  deviceHttpEnabled,
+  deviceHttpTargets,
+  deviceProbeTtlSeconds,
+  describeCameraCapabilities as describe_,
+  formatCapabilityTrace,
+  hasAnyCapability,
+  isRelayPlayerUrl,
+  registerCameraTransport,
+  resetCameraTransports,
+  resolveDeviceHttp,
+} from "./.build/utils/camera-capability.util.mjs";
+
+import {
+  publicCameraFields,
+  resolutionRefusalReason,
+  snapshotRefusalReason,
+} from "./.build/utils/camera-view.util.mjs";
+
+/**
+ * Shapes copied from the real estate, with fake addresses.
+ *
+ * The three unresolvable records are real: two `example.com` placeholders and
+ * one bare authority with no channel. They are in here because they are the
+ * cases a descriptor has to explain rather than fail on.
+ */
+const RELAY = "relay.example.net";
+
+const DEVICES = {
+  [RELAY]: {
+    host: "recorder.example.net",
+    port: 554,
+    username: "not-a-real-user",
+    password: "not-a-real-password",
+  },
+};
+
+const HTTP_TARGETS = {
+  [RELAY]: {
+    authority: RELAY,
+    baseUrl: "https://recorder.example.net:443",
+    username: "not-a-real-user",
+    password: "not-a-real-password",
+    enabled: true,
+    controlEnabled: false,
+    timeoutMs: 8000,
+    probeTtlSeconds: 900,
+  },
+};
+
+const CAMERA = {
+  type: "ip",
+  status: "active",
+  host: `https://${RELAY}/4`,
+};
+
+function target(overrides = {}) {
+  return { ...HTTP_TARGETS[RELAY], ...overrides };
+}
+
+function describeWith(overrides = {}) {
+  return describeCameraCapabilities({
+    camera: CAMERA,
+    rtspDevices: DEVICES,
+    deviceHttp: null,
+    probe: null,
+    ...overrides,
+  });
+}
+
+test.afterEach(() => resetCameraTransports());
+
+/* -------------------------------------------------------------------------- */
+/* The descriptor is total                                                     */
+/* -------------------------------------------------------------------------- */
+
+test("every capability gets an entry, always, for every camera shape", () => {
+  const shapes = [
+    CAMERA,
+    { ...CAMERA, status: "inactive" },
+    { type: "anpr", status: "active", host: "http://device.example.com:8080" },
+    { ...CAMERA, host: "http://example.com" },
+    { ...CAMERA, host: "https://other.example.org" },
+    { ...CAMERA, host: "" },
+    null,
+  ];
+
+  for (const camera of shapes) {
+    const { capabilities, trace } = describeWith({ camera });
+    assert.equal(trace.length, CAMERA_CAPABILITIES.length);
+    for (const capability of CAMERA_CAPABILITIES) {
+      const entry = capabilities[capability];
+      assert.ok(entry, `${capability} missing`);
+      assert.ok(["supported", "unsupported", "unknown"].includes(entry.state));
+      // The contract a UI renders from: a "no" always carries a code AND the
+      // sentence for it, and a "yes" always names the transport that will do it.
+      if (entry.state === "supported") {
+        assert.ok(entry.transport, `${capability} supported with no transport`);
+        assert.equal(entry.reason, null);
+      } else {
+        assert.ok(entry.reason, `${capability} refused with no reason`);
+        assert.equal(entry.detail, CAMERA_CAPABILITY_REASONS[entry.reason]);
+        assert.equal(entry.transport, null);
+      }
+    }
+  }
+});
+
+/* -------------------------------------------------------------------------- */
+/* Today's estate, exactly                                                     */
+/* -------------------------------------------------------------------------- */
+
+test("a real relay camera: live video AND stills at once, over different transports", () => {
+  const { capabilities } = describeWith();
+
+  assert.equal(capabilities.liveVideo.state, "supported");
+  assert.equal(capabilities.liveVideo.transport, TRANSPORT_RELAY_PLAYER);
+
+  assert.equal(capabilities.stillFrame.state, "supported");
+  assert.equal(capabilities.stillFrame.transport, TRANSPORT_RTSP_FRAME);
+
+  assert.equal(capabilities.digitalZoom.state, "supported");
+  assert.ok(hasAnyCapability(capabilities));
+});
+
+test("with no device HTTP configured, control names the configuration that is missing", () => {
+  const { capabilities } = describeWith();
+
+  // The actionable sentence, not an architectural one: a lead reading this is
+  // told what to set, which is the whole point of the reason code.
+  for (const capability of ["ptz", "presets", "playback", "events", "deviceInfo"]) {
+    assert.equal(capabilities[capability].state, "unsupported");
+    assert.equal(capabilities[capability].reason, "device-http-not-configured");
+  }
+});
+
+test("audio is claimed by no transport at all, and says exactly that", () => {
+  const { capabilities } = describeWith();
+  assert.equal(capabilities.audio.state, "unsupported");
+  assert.equal(capabilities.audio.reason, "no-transport");
+  assert.equal(capabilities.audio.transport, null);
+});
+
+test("a placeholder record: no live video, no still, distinct reasons", () => {
+  const { capabilities } = describeWith({
+    camera: { ...CAMERA, host: "http://example.com" },
+  });
+
+  assert.equal(capabilities.liveVideo.state, "unsupported");
+  assert.equal(capabilities.liveVideo.reason, "not-a-relay-player-url");
+  assert.equal(capabilities.stillFrame.state, "unsupported");
+  assert.equal(capabilities.stillFrame.reason, "no-recorder-configured");
+});
+
+test("a host with no channel is a data problem, not a deployment one", () => {
+  const { capabilities } = describeWith({
+    camera: { ...CAMERA, host: `https://${RELAY}/` },
+  });
+  assert.equal(capabilities.stillFrame.reason, "no-channel-in-address");
+});
+
+test("an inactive camera and an ANPR unit are refused by the record, not the transport", () => {
+  assert.equal(
+    describeWith({ camera: { ...CAMERA, status: "inactive" } }).capabilities
+      .liveVideo.reason,
+    "camera-inactive",
+  );
+  assert.equal(
+    describeWith({
+      camera: { type: "anpr", status: "active", host: `https://${RELAY}/4` },
+    }).capabilities.liveVideo.reason,
+    "not-patrol-cctv-camera",
+  );
+});
+
+/* -------------------------------------------------------------------------- */
+/* DEVICE_HTTP: the ladder from "not configured" to "supported"                */
+/* -------------------------------------------------------------------------- */
+
+test("configured but disabled: unsupported, and it names the switch", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target({ enabled: false }),
+  });
+  assert.equal(capabilities.deviceInfo.reason, "device-http-disabled");
+});
+
+test("enabled but never probed: UNKNOWN, not unsupported", () => {
+  const { capabilities } = describeWith({ deviceHttp: target() });
+
+  // The distinction that matters. "We have not asked" must not read as "the
+  // hardware cannot" — one prompts someone to switch probing on, the other
+  // makes them stop looking.
+  assert.equal(capabilities.deviceInfo.state, "unknown");
+  assert.equal(capabilities.deviceInfo.reason, "device-not-probed");
+  assert.equal(capabilities.ptz.state, "unknown");
+});
+
+test("the failure budget being spent is UNKNOWN, and it is preferred over a flat no", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target(),
+    probe: { reachable: false, lockedOut: true },
+  });
+  assert.equal(capabilities.deviceInfo.state, "unknown");
+  assert.equal(capabilities.deviceInfo.reason, "device-http-locked-out");
+});
+
+test("probed and unreachable: unsupported with the device's own reason", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target(),
+    probe: { reachable: false },
+  });
+  assert.equal(capabilities.deviceInfo.state, "unsupported");
+  assert.equal(capabilities.deviceInfo.reason, "device-http-unreachable");
+});
+
+test("probed and reachable: reads light up, PTZ still does not", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target(),
+    probe: { reachable: true, ptz: true, presets: true },
+  });
+
+  assert.equal(capabilities.deviceInfo.state, "supported");
+  assert.equal(capabilities.deviceInfo.transport, TRANSPORT_DEVICE_HTTP);
+  assert.equal(capabilities.playback.state, "supported");
+  assert.equal(capabilities.events.state, "supported");
+
+  // Reads on does NOT arm motors. This is the second flag, and it is the whole
+  // reason there are two.
+  assert.equal(capabilities.ptz.state, "unsupported");
+  assert.equal(capabilities.ptz.reason, "control-not-enabled");
+  assert.equal(capabilities.presets.reason, "control-not-enabled");
+});
+
+test("control enabled on a PTZ unit is the only way ptz becomes supported", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target({ controlEnabled: true }),
+    probe: { reachable: true, ptz: true, presets: true },
+  });
+  assert.equal(capabilities.ptz.state, "supported");
+  assert.equal(capabilities.ptz.transport, TRANSPORT_DEVICE_HTTP);
+});
+
+test("a fixed dome that answered says so, and control being on does not change it", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target({ controlEnabled: true }),
+    probe: { reachable: true, ptz: false, presets: false },
+  });
+  assert.equal(capabilities.ptz.state, "unsupported");
+  assert.equal(capabilities.ptz.reason, "device-no-ptz");
+});
+
+test("a unit that answered but would not say whether it pans is unknown", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target({ controlEnabled: true }),
+    probe: { reachable: true, ptz: null },
+  });
+  assert.equal(capabilities.ptz.state, "unknown");
+});
+
+test("stillFrame prefers the proven RTSP path even when device HTTP is up", () => {
+  const { capabilities } = describeWith({
+    deviceHttp: target(),
+    probe: { reachable: true, ptz: true },
+  });
+  assert.equal(capabilities.stillFrame.transport, TRANSPORT_RTSP_FRAME);
+});
+
+test("with no recorder configured, a reachable device HTTP still serves the still", () => {
+  const { capabilities } = describeWith({
+    rtspDevices: {},
+    deviceHttp: target(),
+    probe: { reachable: true },
+  });
+  assert.equal(capabilities.stillFrame.state, "supported");
+  assert.equal(capabilities.stillFrame.transport, TRANSPORT_DEVICE_HTTP);
+});
+
+/* -------------------------------------------------------------------------- */
+/* The registry is the extension point                                         */
+/* -------------------------------------------------------------------------- */
+
+test("a new transport lights a capability up with no change to the descriptor code", () => {
+  assert.equal(describeWith().capabilities.audio.state, "unsupported");
+
+  registerCameraTransport({
+    id: "HLS_RELAY",
+    provides: ["audio", "liveVideo"],
+    evaluate: () => ({ state: "supported", reason: null }),
+  });
+
+  const { capabilities } = describeWith();
+  assert.equal(capabilities.audio.state, "supported");
+  assert.equal(capabilities.audio.transport, "HLS_RELAY");
+  // Registered last, so it does not steal live video from the production path.
+  assert.equal(capabilities.liveVideo.transport, TRANSPORT_RELAY_PLAYER);
+});
+
+test("registering an existing id replaces it rather than shadowing it", () => {
+  const before = cameraTransports().length;
+  registerCameraTransport({
+    id: TRANSPORT_RELAY_PLAYER,
+    provides: ["liveVideo"],
+    evaluate: () => ({ state: "unsupported", reason: "no-transport" }),
+  });
+  assert.equal(cameraTransports().length, before);
+  assert.equal(describeWith().capabilities.liveVideo.state, "unsupported");
+});
+
+test("selection is deterministic: the same input gives the same trace", () => {
+  const a = formatCapabilityTrace(describeWith().trace);
+  const b = formatCapabilityTrace(describeWith().trace);
+  assert.equal(a, b);
+  assert.match(a, /liveVideo=RELAY_PLAYER/);
+  assert.match(a, /stillFrame=RTSP_FRAME/);
+  assert.match(a, /ptz=unsupported:device-http-not-configured/);
+});
+
+test("the trace carries no address and no credential", () => {
+  const line = formatCapabilityTrace(
+    describeWith({ deviceHttp: target() }).trace,
+  );
+  assert.ok(!line.includes(RELAY));
+  assert.ok(!line.includes("not-a-real-password"));
+  assert.ok(!line.includes("recorder.example.net"));
+});
+
+/* -------------------------------------------------------------------------- */
+/* Relay player URL shape                                                      */
+/* -------------------------------------------------------------------------- */
+
+test("a relay player URL is https with exactly one path segment", () => {
+  assert.ok(isRelayPlayerUrl(`https://${RELAY}/4`));
+  assert.ok(isRelayPlayerUrl(`https://${RELAY}/10`));
+  assert.ok(isRelayPlayerUrl(`https://${RELAY}/gym`));
+  assert.ok(!isRelayPlayerUrl(`http://${RELAY}/4`), "cleartext is not enforced-shape");
+  assert.ok(!isRelayPlayerUrl(`https://${RELAY}`));
+  assert.ok(!isRelayPlayerUrl(`https://${RELAY}/a/b`));
+  assert.ok(!isRelayPlayerUrl(`https://${RELAY}/4?x=1`));
+  assert.ok(!isRelayPlayerUrl(""));
+  assert.ok(!isRelayPlayerUrl(undefined));
+});
+
+/* -------------------------------------------------------------------------- */
+/* Configuration: names, validation, and no secret in the config value         */
+/* -------------------------------------------------------------------------- */
+
+test("both switches are opt-in and control cannot be on by itself", () => {
+  assert.equal(deviceHttpEnabled({}), false);
+  assert.equal(deviceHttpEnabled({ CAMERA_DEVICE_HTTP_ENABLED: "1" }), false);
+  assert.equal(deviceHttpEnabled({ CAMERA_DEVICE_HTTP_ENABLED: "true" }), true);
+
+  assert.equal(
+    deviceControlEnabled({ CAMERA_DEVICE_CONTROL_ENABLED: "true" }),
+    false,
+    "control without device access must stay off",
+  );
+  assert.equal(
+    deviceControlEnabled({
+      CAMERA_DEVICE_HTTP_ENABLED: "true",
+      CAMERA_DEVICE_CONTROL_ENABLED: "true",
+    }),
+    true,
+  );
+});
+
+test("a valid target resolves by relay authority, with the credential referenced", () => {
+  const { targets, errors } = deviceHttpTargets({
+    CAMERA_DEVICE_HTTP: JSON.stringify({
+      [RELAY]: {
+        baseUrl: "https://recorder.example.net:443",
+        credentialRef: "CAMERA_DEVICE_CRED_MAIN",
+      },
+    }),
+    CAMERA_DEVICE_CRED_MAIN: "someone:pa:ss:word",
+    CAMERA_DEVICE_HTTP_ENABLED: "true",
+  });
+
+  assert.deepEqual(errors, []);
+  const resolved = resolveDeviceHttp(`https://${RELAY}/4`, targets);
+  // Normalised to an origin, so the default port drops off and a base URL
+  // cannot smuggle in a path, query or fragment.
+  assert.equal(resolved.baseUrl, "https://recorder.example.net");
+  assert.equal(resolved.username, "someone");
+  // Split on the FIRST colon only: a password may contain colons.
+  assert.equal(resolved.password, "pa:ss:word");
+  assert.equal(resolved.enabled, true);
+  assert.equal(resolved.controlEnabled, false);
+});
+
+test("a credential pasted into credentialRef is rejected, not used", () => {
+  const { targets, errors } = deviceHttpTargets({
+    CAMERA_DEVICE_HTTP: JSON.stringify({
+      [RELAY]: {
+        baseUrl: "https://recorder.example.net",
+        credentialRef: "someone:hunter2",
+      },
+    }),
+  });
+  assert.deepEqual(targets, {});
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /environment variable NAME/);
+});
+
+test("every rejection is reported rather than silently dropped", () => {
+  const cases = [
+    [{ CAMERA_DEVICE_HTTP: "{oops" }, /not valid JSON/],
+    [{ CAMERA_DEVICE_HTTP: "[]" }, /JSON object keyed by relay authority/],
+    [
+      { CAMERA_DEVICE_HTTP: JSON.stringify({ [RELAY]: { credentialRef: "A" } }) },
+      /baseUrl must be an http\(s\) origin/,
+    ],
+    [
+      {
+        CAMERA_DEVICE_HTTP: JSON.stringify({
+          [RELAY]: { baseUrl: "https://x/some/path", credentialRef: "A" },
+        }),
+      },
+      /baseUrl must be an http\(s\) origin/,
+    ],
+    [
+      {
+        CAMERA_DEVICE_HTTP: JSON.stringify({
+          [RELAY]: { baseUrl: "rtsp://x", credentialRef: "A" },
+        }),
+      },
+      /baseUrl must be an http\(s\) origin/,
+    ],
+    [
+      {
+        CAMERA_DEVICE_HTTP: JSON.stringify({
+          [RELAY]: { baseUrl: "https://x", credentialRef: "MISSING_ONE" },
+        }),
+      },
+      /not set on this server/,
+    ],
+    [
+      {
+        CAMERA_DEVICE_HTTP: JSON.stringify({
+          [RELAY]: { baseUrl: "https://x", credentialRef: "CRED" },
+        }),
+        CRED: "no-colon-here",
+      },
+      /username:password/,
+    ],
+  ];
+
+  for (const [envVars, expected] of cases) {
+    const { targets, errors } = deviceHttpTargets(envVars);
+    assert.deepEqual(targets, {}, `${JSON.stringify(envVars)} produced a target`);
+    assert.match(errors.join(" | "), expected);
+  }
+});
+
+test("an unset CAMERA_DEVICE_HTTP is not an error, it is just no device access", () => {
+  const { targets, errors } = deviceHttpTargets({});
+  assert.deepEqual(targets, {});
+  assert.deepEqual(errors, []);
+});
+
+test("the probe TTL defaults long, because what it answers changes rarely", () => {
+  assert.equal(deviceProbeTtlSeconds({}), 900);
+  assert.equal(
+    deviceProbeTtlSeconds({ CAMERA_DEVICE_HTTP_PROBE_TTL_SECONDS: "60" }),
+    60,
+  );
+  assert.equal(
+    deviceProbeTtlSeconds({ CAMERA_DEVICE_HTTP_PROBE_TTL_SECONDS: "-1" }),
+    900,
+  );
+});
+
+/* -------------------------------------------------------------------------- */
+/* No drift between the descriptor's sentences and the legacy refusal strings   */
+/* -------------------------------------------------------------------------- */
+
+test("the descriptor explains a camera in the same words the legacy field does", () => {
+  // Two code paths, one wording. A camera that says "not active" on one screen
+  // and something else on another is the drift this pins shut.
+  assert.equal(
+    CAMERA_CAPABILITY_REASONS["camera-inactive"],
+    snapshotRefusalReason({ type: "ip", status: "inactive", host: "x" }, DEVICES),
+  );
+  assert.equal(
+    CAMERA_CAPABILITY_REASONS["no-address"],
+    snapshotRefusalReason({ type: "ip", status: "active", host: "  " }, DEVICES),
+  );
+  assert.equal(
+    CAMERA_CAPABILITY_REASONS["no-recorder-configured"],
+    resolutionRefusalReason("https://elsewhere.example.org/4", DEVICES),
+  );
+  assert.equal(
+    CAMERA_CAPABILITY_REASONS["no-channel-in-address"],
+    resolutionRefusalReason(`https://${RELAY}/`, DEVICES),
+  );
+  assert.equal(
+    CAMERA_CAPABILITY_REASONS["not-patrol-cctv-camera"],
+    snapshotRefusalReason({ type: "anpr", status: "active", host: "x" }, DEVICES),
+  );
+});
+
+/* -------------------------------------------------------------------------- */
+/* The wall's one new field                                                    */
+/* -------------------------------------------------------------------------- */
+
+test("host is returned for an IP camera and for nothing else", () => {
+  const fields = publicCameraFields({ ...CAMERA, _id: "1", host: `https://${RELAY}/4` });
+  assert.equal(fields.host, `https://${RELAY}/4`);
+
+  // ANPR records hold a real device endpoint plus a real credential, and no
+  // patrol or CCTV path may ever hand one out.
+  const anpr = publicCameraFields({
+    _id: "2",
+    type: "anpr",
+    status: "active",
+    host: "http://device.example.com:8080",
+    username: "u",
+    password: "p",
+  });
+  assert.equal("host" in anpr, false);
+  assert.equal("username" in anpr, false);
+  assert.equal("password" in anpr, false);
+});
+
+test("cameraCapabilitiesFor reads configuration but never probes", () => {
+  const { capabilities } = cameraCapabilitiesFor({
+    camera: CAMERA,
+    rtspDevices: DEVICES,
+    deviceHttpTargets: {},
+  });
+  assert.equal(capabilities.liveVideo.state, "supported");
+  assert.equal(capabilities.stillFrame.state, "supported");
+  assert.equal(typeof describe_, "function");
+});