@7365admin1/core 3.80.0 → 3.81.0

package/test/robot-permission.test.mjs

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ROBOT_MODULE,
+  ROBOT_PERMISSIONS,
+  allowsRobotAction,
+  allowsRobotListing,
+  robotActionsFor,
+} from "./.build/utils/robot-permission.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * Nothing on the server has ever enforced the five robot permissions - the two
+ * routes carry requireAuth and the estate check, so anybody who can reach an
+ * estate can register a robot into it. This is the missing half.
+ *
+ * The rule that needs the most care is the empty list. Seven365's own staff
+ * role is seeded with `permissions: []`, not `["*"]`, so enforcing an empty
+ * list would refuse the platform owner - while treating EVERY empty list as
+ * "everything" would hand each unconfigured client role the whole module.
+ * ----------------------------------------------------------------------- */
+
+const ALL_ACTIONS = ["seeAll", "add", "update", "seeDetails", "delete"];
+
+test("the permission strings are module:permission, on robot-mgmt", () => {
+  assert.equal(ROBOT_MODULE, "robot-mgmt");
+  assert.deepEqual(ROBOT_PERMISSIONS, {
+    seeAll: "robot-mgmt:see-all-robots",
+    add: "robot-mgmt:add-robot",
+    update: "robot-mgmt:update-robot",
+    seeDetails: "robot-mgmt:see-robot-details",
+    delete: "robot-mgmt:delete-robot",
+  });
+});
+
+/* ------------------------------------------------------------- the wildcard */
+
+test('"*" allows every action', () => {
+  const actor = { permissions: ["*"], roleType: "client" };
+  for (const action of ALL_ACTIONS) {
+    assert.equal(allowsRobotAction(actor, action), true, action);
+  }
+  assert.deepEqual(robotActionsFor(actor), ALL_ACTIONS);
+});
+
+/* -------------------------------------------------- the Seven365 Super Admin */
+
+test("an EMPTY list on a platform-admin role allows everything", () => {
+  // createDefaultUser() seeds Seven365 staff with permissions: [] - and the
+  // owner's requirement is that the Super Admin can do everything, everywhere.
+  const platformStaff = { permissions: [], roleType: "admin" };
+  for (const action of ALL_ACTIONS) {
+    assert.equal(allowsRobotAction(platformStaff, action), true, action);
+  }
+});
+
+test("an empty list on a CLIENT role allows NOTHING", () => {
+  // The other half of the rule. Widening it to every role would hand each
+  // unconfigured client role the whole module.
+  for (const roleType of ["client", "member", "", null, undefined]) {
+    const actor = { permissions: [], roleType };
+    for (const action of ALL_ACTIONS) {
+      assert.equal(
+        allowsRobotAction(actor, action),
+        false,
+        `${String(roleType)} / ${action}`
+      );
+    }
+  }
+});
+
+test("a platform-admin role with a NON-empty list is enforced like any other", () => {
+  // Once somebody has ticked a module, the list means what it says - an admin
+  // role granted only "see" cannot delete.
+  const actor = {
+    permissions: ["robot-mgmt:see-all-robots"],
+    roleType: "admin",
+  };
+  assert.equal(allowsRobotAction(actor, "seeAll"), true);
+  assert.equal(allowsRobotAction(actor, "delete"), false);
+  assert.equal(allowsRobotAction(actor, "add"), false);
+});
+
+/* ------------------------------------------------------------ explicit grant */
+
+test("a non-empty list grants exactly what it names", () => {
+  const actor = {
+    permissions: ["robot-mgmt:see-all-robots", "robot-mgmt:add-robot"],
+    roleType: "client",
+  };
+  assert.deepEqual(robotActionsFor(actor), ["seeAll", "add"]);
+  assert.equal(allowsRobotListing(actor), true);
+  assert.equal(allowsRobotAction(actor, "delete"), false);
+});
+
+test("a permission from another module does not leak across", () => {
+  const actor = {
+    permissions: ["sites:manage-site-modules", "virtual-patrol:see-all-routes"],
+    roleType: "client",
+  };
+  assert.deepEqual(robotActionsFor(actor), []);
+});
+
+test("the bare permission name without its module does not count", () => {
+  // "see-all-robots" is how the catalogue lists it; "robot-mgmt:see-all-robots"
+  // is what a role document holds. Accepting the short form would let a
+  // different module's identically-named permission through.
+  const actor = { permissions: ["see-all-robots"], roleType: "client" };
+  assert.equal(allowsRobotListing(actor), false);
+});
+
+/* ------------------------------------------------------------- fails closed */
+
+test("an unreadable actor is refused", () => {
+  for (const actor of [
+    null,
+    undefined,
+    {},
+    { permissions: null },
+    { permissions: "robot-mgmt:see-all-robots" },
+    { permissions: 5 },
+  ]) {
+    assert.equal(allowsRobotListing(actor), false, JSON.stringify(actor));
+    assert.deepEqual(robotActionsFor(actor), []);
+  }
+});
+
+test("an action that is not one of the five is refused, even with the wildcard", () => {
+  const superuser = { permissions: ["*"], roleType: "admin" };
+  for (const bogus of ["drive", "", null, undefined, "constructor", "toString"]) {
+    assert.equal(allowsRobotAction(superuser, bogus), false, String(bogus));
+  }
+});

package/test/robot-tracking.test.mjs

@@ -0,0 +1,231 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  TRACKING_IDLE_TIMEOUT_MS,
+  applyTrackingFrame,
+  createSseParser,
+  decodeTrackingFrame,
+  disconnectedState,
+  isAvailableForWork,
+  isTrackingStale,
+  trackingBackoffMs,
+} from "./.build/utils/robot-tracking.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * What these guard.
+ *
+ * The tracking stream is the only thing that says where a robot is and whether
+ * it is working. It is also the only part of the integration with no safety net
+ * from the vendor: no heartbeat, no sequence number, no command id. So the
+ * failure modes worth testing are the quiet ones - an event split across two TCP
+ * reads, a connection that died while the robot happened to be idle, and a
+ * reconnect storm we cause ourselves.
+ * ----------------------------------------------------------------------- */
+
+const frame = (o) => `data: ${JSON.stringify(o)}\n\n`;
+const POSE = { status: 2, x: 0.203, y: -0.063, theta: 0.041 };
+
+/* ------------------------------------------------------------ SSE parsing */
+
+test("a whole event in one chunk decodes", () => {
+  const p = createSseParser();
+  const { events } = p.push(frame(POSE));
+  assert.equal(events.length, 1);
+  assert.deepEqual(JSON.parse(events[0].data), POSE);
+});
+
+test("an event split across chunks is reassembled, not lost", () => {
+  // The defect this exists for: splitting each TCP chunk on its own drops or
+  // corrupts whatever event straddles the boundary.
+  const whole = frame(POSE);
+  const p = createSseParser();
+
+  for (let cut = 1; cut < whole.length; cut++) {
+    const q = createSseParser();
+    const first = q.push(whole.slice(0, cut));
+    const second = q.push(whole.slice(cut));
+    const events = [...first.events, ...second.events];
+
+    assert.equal(events.length, 1, `split at ${cut}`);
+    assert.deepEqual(JSON.parse(events[0].data), POSE, `split at ${cut}`);
+  }
+
+  // and the single-chunk case still behaves
+  assert.equal(p.push(whole).events.length, 1);
+});
+
+test("several events in one chunk all decode, in order", () => {
+  const p = createSseParser();
+  const { events } = p.push(
+    frame({ ...POSE, x: 1 }) + frame({ ...POSE, x: 2 }) + frame({ ...POSE, x: 3 })
+  );
+  assert.deepEqual(
+    events.map((e) => JSON.parse(e.data).x),
+    [1, 2, 3]
+  );
+});
+
+test("a comment line is keep-alive: activity, but not an event", () => {
+  const p = createSseParser();
+  const { events, sawActivity } = p.push(": keep-alive\n\n");
+  assert.equal(events.length, 0);
+  assert.equal(sawActivity, true, "the watchdog must count this as alive");
+});
+
+test("an incomplete event is held back until it completes", () => {
+  const p = createSseParser();
+  assert.equal(p.push('data: {"status": 1,').events.length, 0);
+  assert.equal(p.push('"x": 0, "y": 0,').events.length, 0);
+
+  const { events } = p.push('"theta": 0}\n\n');
+  assert.equal(events.length, 1);
+  assert.deepEqual(JSON.parse(events[0].data), {
+    status: 1,
+    x: 0,
+    y: 0,
+    theta: 0,
+  });
+});
+
+test("CRLF framing decodes the same as LF", () => {
+  const p = createSseParser();
+  const { events } = p.push(`data: ${JSON.stringify(POSE)}\r\n\r\n`);
+  assert.equal(events.length, 1);
+  assert.deepEqual(JSON.parse(events[0].data), POSE);
+});
+
+test("reset drops a half-received event so a reconnect cannot splice it", () => {
+  const p = createSseParser();
+  p.push('data: {"status": 1, "x": 0');
+  p.reset();
+
+  // Without the reset, this would join the dead socket's fragment and parse.
+  const { events } = p.push(frame(POSE));
+  assert.equal(events.length, 1);
+  assert.deepEqual(JSON.parse(events[0].data), POSE);
+});
+
+/* ---------------------------------------------------------- pose decoding */
+
+test("a good frame decodes to a pose with its normalised mode", () => {
+  const pose = decodeTrackingFrame(JSON.stringify(POSE));
+  assert.deepEqual(pose, {
+    x: 0.203,
+    y: -0.063,
+    theta: 0.041,
+    statusFlag: 2,
+    mode: "WORKING",
+  });
+});
+
+test("a partial pose is rejected whole, never defaulted to the origin", () => {
+  // (0,0) is a real location on these maps, so a missing field must not become
+  // a position.
+  for (const missing of ["x", "y", "theta", "status"]) {
+    const o = { ...POSE };
+    delete o[missing];
+    assert.equal(decodeTrackingFrame(JSON.stringify(o)), null, `no ${missing}`);
+  }
+});
+
+test("a malformed frame returns null instead of throwing", () => {
+  // One bad frame must not tear down a connection that is otherwise healthy.
+  for (const bad of ['{"status":', "", "null", "[]", '"a string"', "{}"]) {
+    assert.equal(decodeTrackingFrame(bad), null, JSON.stringify(bad));
+  }
+});
+
+test("non-numeric and non-finite coordinates are refused", () => {
+  assert.equal(decodeTrackingFrame('{"status":1,"x":"0","y":0,"theta":0}'), null);
+  assert.equal(decodeTrackingFrame('{"status":1,"x":null,"y":0,"theta":0}'), null);
+  // NaN and Infinity are not JSON literals, so they arrive as these:
+  assert.equal(decodeTrackingFrame('{"status":1,"x":1e999,"y":0,"theta":0}'), null);
+});
+
+/* ------------------------------------------------------------- staleness */
+
+test("silence past the idle timeout is stale", () => {
+  assert.equal(isTrackingStale(0, TRACKING_IDLE_TIMEOUT_MS - 1), false);
+  assert.equal(isTrackingStale(0, TRACKING_IDLE_TIMEOUT_MS), true);
+  assert.equal(isTrackingStale(0, TRACKING_IDLE_TIMEOUT_MS + 5_000), true);
+});
+
+test("a robot whose stream died while IDLE is NOT offered work", () => {
+  // The branch that matters. Holding the last known mode would leave this robot
+  // advertised as ready forever, and the dispatcher would keep sending it jobs
+  // nothing is listening for.
+  const idle = applyTrackingFrame(
+    disconnectedState("CASDF03456", 0),
+    decodeTrackingFrame(JSON.stringify({ ...POSE, status: 1 })),
+    0
+  );
+
+  assert.equal(isAvailableForWork(idle, 0), true, "fresh and idle");
+  assert.equal(
+    isAvailableForWork(idle, TRACKING_IDLE_TIMEOUT_MS),
+    false,
+    "same state, stream gone silent"
+  );
+});
+
+test("a disconnected robot is never available, however recent", () => {
+  assert.equal(isAvailableForWork(disconnectedState("R1", 1_000), 1_000), false);
+});
+
+test("a connected, fresh, but WORKING robot is not available", () => {
+  const working = applyTrackingFrame(
+    disconnectedState("R1", 0),
+    decodeTrackingFrame(JSON.stringify(POSE)), // status 2 = cleaning
+    0
+  );
+  assert.equal(isAvailableForWork(working, 0), false);
+});
+
+test("a pose update does not invent a floor", () => {
+  // The stream carries no floorNo. Anything dispatching to a floor must see
+  // floorKnown: false rather than a defaulted number.
+  const state = applyTrackingFrame(
+    disconnectedState("R1", 0),
+    decodeTrackingFrame(JSON.stringify(POSE)),
+    0
+  );
+  assert.equal(state.floorNo, null);
+  assert.equal(state.floorKnown, false);
+});
+
+/* -------------------------------------------------------------- reconnect */
+
+test("backoff grows exponentially and then stops at the cap", () => {
+  const always1 = () => 1; // full jitter at its maximum = the ceiling itself
+  assert.equal(trackingBackoffMs(0, always1), 1_000);
+  assert.equal(trackingBackoffMs(1, always1), 2_000);
+  assert.equal(trackingBackoffMs(2, always1), 4_000);
+  assert.equal(trackingBackoffMs(6, always1), 60_000, "capped");
+  assert.equal(trackingBackoffMs(50, always1), 60_000, "still capped");
+});
+
+test("a huge attempt count cannot produce NaN and a hot retry loop", () => {
+  // 2 ** 1e9 is Infinity, and Infinity * random() is NaN; setTimeout(NaN) fires
+  // immediately - a retry storm precisely when the cloud is least able to take
+  // it. The exponent is capped before the power is taken.
+  for (const attempt of [1e6, 1e9, Number.MAX_SAFE_INTEGER]) {
+    const delay = trackingBackoffMs(attempt);
+    assert.equal(Number.isFinite(delay), true, `attempt ${attempt}`);
+    assert.ok(delay >= 0 && delay <= 60_000, `attempt ${attempt} -> ${delay}`);
+  }
+});
+
+test("a negative or fractional attempt is treated as the first", () => {
+  const always1 = () => 1;
+  assert.equal(trackingBackoffMs(-5, always1), 1_000);
+  assert.equal(trackingBackoffMs(0.9, always1), 1_000);
+});
+
+test("jitter actually spreads reconnects apart", () => {
+  // Without this, every robot dropped by one cloud restart retries in the same
+  // millisecond, repeatedly - we become the reason it struggles to come back.
+  const delays = new Set();
+  for (let i = 0; i < 200; i++) delays.add(trackingBackoffMs(5));
+  assert.ok(delays.size > 50, `too clustered: ${delays.size} distinct values`);
+});