Admin Web UIs for Hardware

// SchemaForm.jsx: renders a form description (from the settings schema). It knows nothing about any one setting.
import { useState } from "react";

const get = (obj, path) => path.split(".").reduce((o, k) => o?.[k], obj);
const set = (obj, path, value) => {
  const copy = structuredClone(obj);
  const keys = path.split(".");
  keys.slice(0, -1).reduce((o, k) => (o[k] ??= {}), copy)[keys.at(-1)] = value;
  return copy;
};

function Field({ field, value, error, onChange }) {
  const id = `f-${field.path}`;
  const hintId = `${id}-hint`;
  const errorId = `${id}-error`;
  const describedBy = [error && errorId, field.restart && hintId].filter(Boolean).join(" ") || undefined;
  const common = { id, name: field.path, "aria-invalid": error ? true : undefined, "aria-describedby": describedBy };
  let control;
  if (field.widget === "select") {
    control = (
      <select {...common} value={value ?? ""} onChange={(e) => onChange(e.target.value)}>
        {field.options.map((o) => <option key={o} value={o}>{o}</option>)}
      </select>
    );
  } else if (field.widget === "toggle") {
    control = <input type="checkbox" {...common} checked={!!value} onChange={(e) => onChange(e.target.checked)} />;
  } else if (field.widget === "number") {
    control = <input type="number" {...common} min={field.minimum} max={field.maximum} value={value ?? ""}
      onChange={(e) => onChange(e.target.value === "" ? undefined : Number(e.target.value))} />;
  } else {
    control = <input type={field.widget === "password" ? "password" : "text"} {...common} maxLength={field.maxLength}
      autoComplete={field.widget === "password" ? "new-password" : "off"} value={value ?? ""} onChange={(e) => onChange(e.target.value)} />;
  }
  return (
    <div className="field">
      <label htmlFor={id}>{field.label}</label>
      {control}
      {error && <p id={errorId} className="error">{error}</p>}
      {field.restart && <p id={hintId} className="hint">Takes effect after a restart.</p>}
    </div>
  );
}

export function SchemaForm({ fields, initial, validate, onSave }) {
  const [values, setValues] = useState(initial);
  const [errors, setErrors] = useState({});
  const visible = fields.filter((f) => !f.showWhen || get(values, f.showWhen.path) === f.showWhen.equals);
  const groups = Map.groupBy(visible, (f) => f.group);

  function submit(event) {
    event.preventDefault();
    const found = validate(values); // the same Ajv-compiled schema the device runs
    setErrors(found);
    const first = visible.find((f) => found[f.path]);
    if (first) document.getElementById(`f-${first.path}`).focus(); // take the admin to the first problem
    else onSave(values);
  }

  return (
    <form onSubmit={submit} noValidate>
      {[...groups].map(([group, groupFields]) => (
        <fieldset key={group}>
          <legend>{group}</legend>
          {groupFields.map((f) => (
            <Field key={f.path} field={f} value={get(values, f.path)} error={errors[f.path]?.join(" ")}
              onChange={(v) => setValues((old) => set(old, f.path, v))} />
          ))}
        </fieldset>
      ))}
      <button type="submit">Save</button>
    </form>
  );
}

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import Ajv2020 from "../../../deviceapis/node_modules/ajv/dist/2020.js";
import { SchemaForm } from "./SchemaForm.jsx";
import { schema, describe as describeForm } from "./settings.js";

const ajv = new Ajv2020({ allErrors: true });
ajv.addVocabulary(["x-group", "x-restart"]);
const check = ajv.compile(schema);
function validate(values) {
  if (check(values)) return {};
  const out = {};
  for (const e of check.errors) {
    if (e.keyword === "if") continue;
    let path = e.instancePath.slice(1).replaceAll("/", ".");
    if (e.keyword === "required") path = [path, e.params.missingProperty].filter(Boolean).join(".");
    (out[path] ??= []).push(e.keyword === "required" ? "This field is required." : `Must ${e.message.replace(/^must /, "")}.`);
  }
  return out;
}

const fields = describeForm(schema);
const initial = { systemName: "Board Room", language: "en-US", provider: "poly", network: { dhcp: true } };

test("renders one fieldset per group, with static-IP fields hidden while DHCP is on", () => {
  render(<SchemaForm fields={fields} initial={initial} validate={validate} onSave={() => {}} />);
  expect(screen.getAllByRole("group").map((g) => g.querySelector("legend").textContent)).toEqual(["General", "Network", "Security"]);
  expect(screen.getByLabelText("System name")).toHaveValue("Board Room");
  const provider = screen.getByRole("combobox", { name: "Conferencing provider" });
  expect(provider).toHaveValue("poly");
  expect(provider).toHaveAccessibleDescription("Takes effect after a restart.");
  expect(screen.getByLabelText("System name")).not.toHaveAttribute("aria-describedby");
  expect(screen.queryByLabelText(/IP address/)).toBeNull();
});

test("turning DHCP off reveals the static fields; saving empty ones shows linked errors and moves focus", async () => {
  const user = userEvent.setup();
  const onSave = vi.fn();
  render(<SchemaForm fields={fields} initial={initial} validate={validate} onSave={onSave} />);
  await user.click(screen.getByRole("checkbox", { name: "Use DHCP" }));
  const ip = screen.getByRole("textbox", { name: "IP address" });
  await user.click(screen.getByRole("button", { name: "Save" }));
  expect(onSave).not.toHaveBeenCalled();
  expect(ip).toHaveAttribute("aria-invalid", "true");
  expect(ip).toHaveAccessibleDescription("This field is required. Takes effect after a restart.");
  expect(screen.getByRole("spinbutton", { name: "Prefix length" })).toHaveAttribute("aria-invalid", "true");
  expect(ip).toHaveFocus();
  console.log("errors shown:", [...document.querySelectorAll(".error")].map((p) => `${p.id}: ${p.textContent}`).join(" | "));
});

test("valid values are saved as one object", async () => {
  const user = userEvent.setup();
  const onSave = vi.fn();
  render(<SchemaForm fields={fields} initial={initial} validate={validate} onSave={onSave} />);
  await user.click(screen.getByRole("checkbox", { name: "Use DHCP" }));
  await user.type(screen.getByRole("textbox", { name: "IP address" }), "10.0.4.20");
  await user.type(screen.getByRole("spinbutton", { name: "Prefix length" }), "24");
  await user.click(screen.getByRole("button", { name: "Save" }));
  expect(onSave).toHaveBeenCalledWith({ ...initial, network: { dhcp: false, ipAddress: "10.0.4.20", prefixLength: 24 } });
  console.log("saved:", JSON.stringify(onSave.mock.calls[0][0]));
});

stdout | src/SchemaForm.test.jsx > turning DHCP off reveals the static fields; saving empty ones shows linked errors and moves focus
errors shown: f-network.ipAddress-error: This field is required. | f-network.prefixLength-error: This field is required.
 ✓ src/SchemaForm.test.jsx > renders one fieldset per group, with static-IP fields hidden while DHCP is on 159ms
 ✓ src/SchemaForm.test.jsx > turning DHCP off reveals the static fields; saving empty ones shows linked errors and moves focus 100ms
stdout | src/SchemaForm.test.jsx > valid values are saved as one object
saved: {"systemName":"Board Room","language":"en-US","provider":"poly","network":{"dhcp":false,"ipAddress":"10.0.4.20","prefixLength":24}}
 ✓ src/SchemaForm.test.jsx > valid values are saved as one object 134ms
 Test Files  1 passed (1)
      Tests  3 passed (3)

// The device validates with the same schema the UI uses, then adds checks only the device can make.
// The UI downloads the schema from the device it's talking to, so old firmware gets old rules.
import express from "express";
import request from "supertest";
import Ajv2020 from "ajv/dist/2020.js";

const schemaFor = (resolutions) => ({
  type: "object",
  additionalProperties: false,
  properties: {
    systemName: { type: "string", minLength: 1, maxLength: 40 },
    video: { type: "object", additionalProperties: false, properties: { maxResolution: { enum: resolutions } } },
  },
});

const merge = (cur, patch) => ({ ...cur, ...patch, video: { ...cur.video, ...patch.video } });

function deviceApp({ firmware, resolutions, display }) {
  const schema = schemaFor(resolutions);
  const validate = new Ajv2020().compile(schema); // device: stop at the first error (see the gotcha below)
  let settings = { systemName: "Board Room", video: { maxResolution: "1080p" } };
  const app = express().use(express.json({ limit: "16kb", type: ["application/json", "application/merge-patch+json"] }));
  app.get("/api/v1/settings/schema", (req, res) => res.json({ firmware, schema }));
  app.get("/api/v1/settings", (req, res) => res.json(settings));
  app.patch("/api/v1/settings", (req, res) => {
    const next = merge(settings, req.body);
    const errors = validate(next) ? [] : validate.errors.map((e) => ({ pointer: `#${e.instancePath}`, detail: e.message }));
    // A rule no schema can express: it depends on the hardware plugged in right now.
    if (!errors.length && next.video.maxResolution === "4K" && display !== "4K")
      errors.push({ pointer: "#/video/maxResolution", detail: `connected display supports up to ${display}` });
    if (errors.length)
      return res.status(422).type("application/problem+json").json({ type: "urn:device:invalid-settings", title: "Settings are not valid", errors });
    settings = next;
    res.json(settings);
  });
  return app;
}

// The UI side: fetch the device's own schema, pre-validate, then send and map the device's answer to fields.
async function save(app, label, patch) {
  const { body } = await request(app).get("/api/v1/settings/schema");
  const check = new Ajv2020({ allErrors: true }).compile(body.schema); // UI: every error, for the form
  const current = (await request(app).get("/api/v1/settings")).body;
  if (!check(merge(current, patch))) {
    const where = check.errors.map((e) => `${e.instancePath} ${e.message}`).join("; ");
    return console.log(`${label.padEnd(26)} blocked in the UI   ${where}`);
  }
  const res = await request(app).patch("/api/v1/settings").set("Content-Type", "application/merge-patch+json").send(patch);
  const detail = res.status === 200 ? JSON.stringify(res.body.video) : res.body.errors.map((e) => `${e.pointer} ${e.detail}`).join("; ");
  console.log(`${label.padEnd(26)} device said ${res.status}     ${detail}`);
}

const newUnit = deviceApp({ firmware: "5.0.0", resolutions: ["720p", "1080p", "4K"], display: "4K" });
const roomWith1080 = deviceApp({ firmware: "5.0.0", resolutions: ["720p", "1080p", "4K"], display: "1080p" });
const oldUnit = deviceApp({ firmware: "4.2.1", resolutions: ["720p", "1080p"], display: "4K" });

await save(newUnit, "5.0.0, 4K display", { video: { maxResolution: "4K" } });
await save(roomWith1080, "5.0.0, 1080p display", { video: { maxResolution: "4K" } });
await save(oldUnit, "4.2.1 firmware", { video: { maxResolution: "4K" } });
await save(newUnit, "empty name", { systemName: "" });

// A script that skips the UI still meets the device's validator.
const direct = await request(oldUnit).patch("/api/v1/settings").send({ video: { maxResolution: "4K" } });
console.log(`${"4.2.1, script, no UI".padEnd(26)} device said ${direct.status}     ${direct.body.errors.map((e) => `${e.pointer} ${e.detail}`)}`);

5.0.0, 4K display          device said 200     {"maxResolution":"4K"}
5.0.0, 1080p display       device said 422     #/video/maxResolution connected display supports up to 1080p
4.2.1 firmware             blocked in the UI   /video/maxResolution must be equal to one of the allowed values
empty name                 blocked in the UI   /systemName must NOT have fewer than 1 characters
4.2.1, script, no UI       device said 422     #/video/maxResolution must be equal to one of the allowed values

// Ajv's messages are English developer text. Build user messages from the error's keyword and params instead,
// so they can be translated and can name the field. Also: a real IPv4 check as a named format.
import Ajv2020 from "ajv/dist/2020.js";

const schema = {
  type: "object",
  properties: {
    systemName: { type: "string", maxLength: 12, title: "System name" },
    ipAddress: { type: "string", format: "ipv4", title: "IP address" },
    prefixLength: { type: "integer", minimum: 8, maximum: 30, title: "Prefix length" },
  },
};

try {
  new Ajv2020().compile(schema);
} catch (e) {
  console.log("without addFormat:", e.message);
}

const ajv = new Ajv2020({ allErrors: true });
const octet = "(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
ajv.addFormat("ipv4", new RegExp(`^${octet}(\\.${octet}){3}$`));
const validate = ajv.compile(schema);

const catalog = {
  "en-US": {
    maxLength: "{field} can be at most {limit} characters.",
    format: "{field} must be a valid IPv4 address, for example 192.168.1.20.",
    maximum: "{field} can't be more than {limit}.",
  },
  "fr-FR": {
    maxLength: "{field} : {limit} caractères au maximum.",
    format: "{field} : saisissez une adresse IPv4 valide, par exemple 192.168.1.20.",
    maximum: "{field} : la valeur maximale est {limit}.",
  },
};
const titles = { "fr-FR": { "System name": "Nom du système", "IP address": "Adresse IP", "Prefix length": "Longueur du préfixe" } };

function messagesFor(errors, locale) {
  return errors.map((e) => {
    const key = e.instancePath.slice(1);
    const title = schema.properties[key].title;
    const field = titles[locale]?.[title] ?? title;
    const text = catalog[locale][e.keyword].replace(/\{(\w+)\}/g, (_, k) => (k === "field" ? field : e.params[k]));
    return `${key}: ${text}`;
  });
}

validate({ systemName: "Main Boardroom 3", ipAddress: "10.0.300.4", prefixLength: 31 });
console.log("Ajv says:", validate.errors.map((e) => e.message).join(" | "));
for (const locale of ["en-US", "fr-FR"]) for (const m of messagesFor(validate.errors, locale)) console.log(`${locale} ${m}`);
console.log("10.0.30.4 valid?", validate({ ipAddress: "10.0.30.4" }), "| 999.1.1.1 valid?", validate({ ipAddress: "999.1.1.1" }));

without addFormat: unknown format "ipv4" ignored in schema at path "#/properties/ipAddress"
Ajv says: must NOT have more than 12 characters | must match format "ipv4" | must be <= 30
en-US systemName: System name can be at most 12 characters.
en-US ipAddress: IP address must be a valid IPv4 address, for example 192.168.1.20.
en-US prefixLength: Prefix length can't be more than 30.
fr-FR systemName: Nom du système : 12 caractères au maximum.
fr-FR ipAddress: Adresse IP : saisissez une adresse IPv4 valide, par exemple 192.168.1.20.
fr-FR prefixLength: Longueur du préfixe : la valeur maximale est 30.
10.0.30.4 valid? true | 999.1.1.1 valid? false

// Compile the settings validator at build time, so the browser runs plain generated code:
// no Ajv compiler in the bundle, no compiling at startup, no `new Function` under a strict CSP.
import Ajv2020 from "ajv/dist/2020.js";
import standaloneCode from "ajv/dist/standalone/index.js";
import { writeFileSync } from "node:fs";

const schema = {
  type: "object",
  additionalProperties: false,
  properties: {
    systemName: { type: "string", minLength: 1, maxLength: 13 },
    speakerVolume: { type: "integer", minimum: 0, maximum: 100 },
  },
};

async function build(file, esm) {
  const ajv = new Ajv2020({ code: { source: true, esm }, allErrors: true });
  const source = standaloneCode(ajv, ajv.compile(schema));
  writeFileSync(file, source); // in a real build: written into the UI's source tree, then bundled
  console.log(`${file}: ${source.length} chars, new Function: ${/new Function/.test(source)}, needs: ${source.match(/require\("[^"]+"\)/g)}`);
  return (await import(`./${file}`)).default;
}

try {
  await build("validate-settings.mjs", true);
} catch (e) {
  console.log("  loading it:", e.constructor.name, "-", e.message.split(",")[0]);
}
const validate = await build("validate-settings.cjs", false);
console.log("  loaded:", typeof validate);

console.log(validate({ systemName: "Lab", speakerVolume: 40 }), validate({ systemName: "", speakerVolume: 140, mode: 1 }));
console.log(validate.errors.map((e) => `${e.instancePath || "/"} ${e.message}`).join(" | "));
// Ajv counts characters (code points), not UTF-16 units like String.length (and Java/Kotlin's length()).
const name = "Huddle 🎥 Room";
console.log(`"${name}": .length ${name.length}, code points ${[...name].length}, maxLength 13 valid? ${validate({ systemName: name })}`);

validate-settings.mjs: 3304 chars, new Function: false, needs: require("ajv/dist/runtime/ucs2length")
  loading it: ReferenceError - require is not defined in ES module scope
validate-settings.cjs: 3307 chars, new Function: false, needs: require("ajv/dist/runtime/ucs2length")
  loaded: function
true false
/ must NOT have additional properties | /systemName must NOT have fewer than 1 characters | /speakerVolume must be <= 100
"Huddle 🎥 Room": .length 14, code points 13, maxLength 13 valid? true

// Two admins edit the same device. The second save fails with 412 (stale ETag). Instead of throwing the
// admin's edits away, the UI rebases them onto the device's current settings and shows only real conflicts.
let version = 7;
let settings = { systemName: "Board Room", provider: "poly", language: "en-US", volume: 60 };
const device = {
  get: () => ({ etag: `"${version}"`, body: structuredClone(settings) }),
  patch(ifMatch, patch) {
    if (ifMatch !== `"${version}"`) return { status: 412 };
    settings = { ...settings, ...patch };
    version++;
    return { status: 200, etag: `"${version}"` };
  },
};

// Admin A loads the page and starts editing.
const a = device.get();
const aEdits = { systemName: "Board Room East", provider: "teams", volume: 70 };

// Meanwhile admin B (or a provisioning server) saves first.
const b = device.get();
console.log("B saves:", device.patch(b.etag, { provider: "zoom", volume: 70 }).status);

// A saves with the ETag A loaded.
console.log("A saves:", device.patch(a.etag, aEdits).status);

// Rebase: compare each of A's edits with A's baseline and with the device's current value.
const now = device.get();
const keep = {}, conflicts = [], alreadyThere = [];
for (const [key, mine] of Object.entries(aEdits)) {
  const base = a.body[key], theirs = now.body[key];
  if (theirs === base) keep[key] = mine; // nobody else touched it: still safe to apply
  else if (theirs === mine) alreadyThere.push(key); // someone made the same change
  else conflicts.push(`${key}: you chose ${JSON.stringify(mine)}, it's now ${JSON.stringify(theirs)} (was ${JSON.stringify(base)})`);
}
console.log("still pending:", JSON.stringify(keep));
console.log("already applied by someone else:", alreadyThere.join(", "));
for (const c of conflicts) console.log("conflict →", c);
console.log("A saves the non-conflicting part:", device.patch(now.etag, keep).status, JSON.stringify(device.get().body));

B saves: 200
A saves: 412
still pending: {"systemName":"Board Room East"}
already applied by someone else: volume
conflict → provider: you chose "teams", it's now "zoom" (was "poly")
A saves the non-conflicting part: 200 {"systemName":"Board Room East","provider":"zoom","language":"en-US","volume":70}

// "Apply, then confirm or it reverts": the safe way to change a setting that can cut you off from the device
// (IP address, VLAN, HTTPS certificate, firewall). Fake clock; times are seconds after Apply.
function clock() {
  let now = 0;
  const timers = [];
  return {
    now: () => now,
    at: (t, fn) => timers.push({ t, fn }),
    cancel: (fn) => timers.splice(timers.findIndex((x) => x.fn === fn), 1),
    runUntil(end) {
      timers.sort((x, y) => x.t - y.t);
      while (timers.length && timers[0].t <= end) { const x = timers.shift(); now = x.t; x.fn(); timers.sort((p, q) => p.t - q.t); }
      now = end;
    },
  };
}

function device(c, log) {
  let address = "10.0.4.20", previous = null, revert = null, upAt = 0;
  return {
    // The network interface takes 8 s to come back up on a new address.
    reachableAt: (addr, newNetworkWorks) => addr === address && c.now() >= upAt && (addr === "10.0.4.20" || newNetworkWorks),
    confirmed: () => previous !== null && revert === null && address !== previous,
    applyNetwork(newAddress, confirmWithin) {
      previous = address;
      address = newAddress;
      upAt = c.now() + 8;
      log(`device: now on ${address}, reverting to ${previous} at t=${c.now() + confirmWithin}s unless confirmed`);
      revert = () => { log(`device: no confirmation, back on ${previous}`); address = previous; upAt = c.now() + 8; revert = null; };
      c.at(c.now() + confirmWithin, revert);
    },
    confirm() { c.cancel(revert); revert = null; log(`device: confirmed at t=${c.now()}s, keeping ${address}`); },
  };
}

function scenario(title, newNetworkWorks) {
  console.log(`— ${title}`);
  const c = clock();
  const log = (m) => console.log(`  t=${String(c.now()).padStart(2)}  ${m}`);
  const d = device(c, log);
  d.applyNetwork("10.0.9.20", 60);
  // The UI polls the NEW address every 5 s; reaching it from the browser proves the new setting works.
  for (let t = 5; t <= 55; t += 5) c.at(t, () => {
    if (!d.confirmed() && d.reachableAt("10.0.9.20", newNetworkWorks)) { log("ui: reached the new address"); d.confirm(); }
  });
  c.runUntil(70);
  log(`ui: 10.0.4.20 reachable? ${d.reachableAt("10.0.4.20", newNetworkWorks)}, 10.0.9.20 reachable? ${d.reachableAt("10.0.9.20", newNetworkWorks)}`);
}

scenario("new address routes from the admin's network", true);
scenario("typo in the gateway: new address unreachable", false);

— new address routes from the admin's network
  t= 0  device: now on 10.0.9.20, reverting to 10.0.4.20 at t=60s unless confirmed
  t=10  ui: reached the new address
  t=10  device: confirmed at t=10s, keeping 10.0.9.20
  t=70  ui: 10.0.4.20 reachable? false, 10.0.9.20 reachable? true
— typo in the gateway: new address unreachable
  t= 0  device: now on 10.0.9.20, reverting to 10.0.4.20 at t=60s unless confirmed
  t=60  device: no confirmation, back on 10.0.4.20
  t=70  ui: 10.0.4.20 reachable? true, 10.0.9.20 reachable? false