@7365admin1/core 3.80.0 → 3.82.0

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`);
+});