@oneuptime/common 12.0.31 → 12.0.33

package/Utils/Monitor/NetworkTopologyUtil.ts

@@ -1,4 +1,5 @@
 import NetworkTopology, {
+  NetworkTopologyDeviceRole,
   NetworkTopologyEdge,
   NetworkTopologyEdgeEndpoint,
   NetworkTopologyLinkProtocol,
@@ -13,6 +14,13 @@ import {
   classifyEndpointRole,
   resolveDeviceRole,
 } from "./NetworkDeviceRoleUtil";
+import {
+  TopologyDeviceRoleInput,
+  applyRoleStamp,
+  buildDeviceRoleIndex,
+  roleKeyForNode,
+  stampForRoleKey,
+} from "./NetworkDeviceRoleCatalog";
 import DeviceReachabilityUtil, {
   NetworkDeviceReachability,
 } from "../NetworkDevice/DeviceReachabilityUtil";
@@ -34,6 +42,21 @@ export interface TopologyDeviceInput {
   lastPolledAt?: Date | undefined;
   lastSeenAt?: Date | undefined;
   pollingIntervalInMinutes?: number | undefined;
+  /*
+   * How this device's health is established. NULL, empty and anything
+   * unrecognised read as Probe — see NetworkDeviceMonitoringMethodUtil.parse,
+   * which is why an omitted value keeps every existing caller on the poll
+   * rule unchanged.
+   *
+   * Read only when `monitorStatus` below is absent, and load-bearing there:
+   * a monitor-backed device (monitoringMethod "Monitor") with nothing
+   * stamped yet is drawn "unknown", which is what the device list says
+   * about it too. Without this the poll columns above would decide — and on
+   * a device switched over from SNMP they hold the last thing a probe found
+   * before it stopped asking, so a months-old lastSeenAt would draw the node
+   * red while its row in the device list reads Pending.
+   */
+  monitoringMethod?: string | null | undefined;
   interfacesUp?: number | undefined;
   interfacesDown?: number | undefined;
   vendor?: string | undefined;
@@ -45,11 +68,18 @@ export interface TopologyDeviceInput {
   sysDescr?: string | undefined;
   sysObjectId?: string | undefined;
   /*
-   * The operator's own answer to what this device is, when they gave one.
-   * Outranks the classifier below, because it is the only statement about
-   * the role that is not an inference — and on a device nothing walks it
-   * is the ONLY statement available at all, the classifier having nothing
-   * but a hostname to go on.
+   * The KEY of the role the operator assigned this device, when they
+   * assigned one. Outranks the classifier below, because it is the only
+   * statement about the role that is not an inference — and on a device
+   * nothing walks it is the ONLY statement available at all, the classifier
+   * having nothing but a hostname to go on.
+   *
+   * A key, not a name: roles are per-project rows an operator can rename, so
+   * the caller reads it off the assigned row (NetworkDevice.networkDeviceRole)
+   * rather than passing a label. It may be a key outside the built-in twelve
+   * — a role the project invented — in which case `role` on the node falls
+   * back to the classifier and the node's roleKey/roleLabel/roleShape carry
+   * the configured answer instead. See buildTopology's deviceRoles argument.
    */
   deviceRole?: string | undefined;
   /*
@@ -329,9 +359,19 @@ export default class NetworkTopologyUtil {
     endpoints: Array<TopologyEndpointInput> = [],
     manualLinks: Array<TopologyManualLinkInput> = [],
     suppressedNodeKeys: ReadonlySet<string> = new Set<string>(),
+    deviceRoles: ReadonlyArray<TopologyDeviceRoleInput> = [],
   ): TopologyBuildResult {
     const nodes: Array<NetworkTopologyNode> = [];
 
+    /*
+     * The project's configured roles, indexed by key. Passing none is a
+     * supported case - the nodes then carry no role stamp and every consumer
+     * falls back to the built-in labels, shapes and core set, which is exactly
+     * the map drawn before roles were configurable.
+     */
+    const roleIndex: Map<string, TopologyDeviceRoleInput> =
+      buildDeviceRoleIndex(deviceRoles);
+
     /*
      * Index managed devices by every identifier a neighbor entry could
      * reference. A key TWO devices both claim is deleted rather than
@@ -384,26 +424,47 @@ export default class NetworkTopologyUtil {
         device.id,
         device.isNeighborDiscoveryEnabled,
       );
-      nodes.push({
-        id: device.id,
-        name: device.name,
-        isManaged: true,
-        kind: "device",
-        role: resolveDeviceRole(device.deviceRole, {
+      const deviceRole: NetworkTopologyDeviceRole = resolveDeviceRole(
+        device.deviceRole,
+        {
           sysDescr: device.sysDescr,
           sysObjectId: device.sysObjectId,
           vendor: device.vendor,
           deviceModel: device.deviceModel,
           name: device.name,
           sysName: device.sysName || device.hostname,
-        }),
+        },
+      );
+
+      const deviceNode: NetworkTopologyNode = {
+        id: device.id,
+        name: device.name,
+        isManaged: true,
+        kind: "device",
+        role: deviceRole,
         status: NetworkTopologyUtil.deviceStatus(device, now),
         interfacesUp: device.interfacesUp,
         interfacesDown: device.interfacesDown,
         sysName: device.sysName,
         vendor: device.vendor,
         deviceModel: device.deviceModel,
-      });
+      };
+
+      /*
+       * The configured role, when the project has one for this key. The
+       * assignment is looked up ahead of the classifier's answer, so a device
+       * an operator gave a CUSTOM role ("PoS Terminal") is drawn as that role
+       * even though `role` above can only ever be one of the built-in twelve.
+       */
+      applyRoleStamp(
+        deviceNode,
+        stampForRoleKey(
+          roleKeyForNode(device.deviceRole, deviceRole),
+          roleIndex,
+        ),
+      );
+
+      nodes.push(deviceNode);
     }
 
     const edgeByKey: Map<string, NetworkTopologyEdge> = new Map();
@@ -465,7 +526,11 @@ export default class NetworkTopologyUtil {
       NetworkTopologyUtil.propagateMatchesAcrossPeerGroups(resolvedClaims);
 
     const peerNodeIdByClaim: Map<ResolvedClaim, string> =
-      NetworkTopologyUtil.buildUnmanagedPeerNodes(settledClaims, nodes);
+      NetworkTopologyUtil.buildUnmanagedPeerNodes(
+        settledClaims,
+        nodes,
+        roleIndex,
+      );
 
     for (const resolved of settledClaims) {
       const device: TopologyDeviceInput = resolved.device;
@@ -780,16 +845,18 @@ export default class NetworkTopologyUtil {
         endpoint.vendor ||
         endpoint.ipAddress ||
         endpoint.macAddress;
-      nodes.push({
+      const endpointRole: NetworkTopologyDeviceRole = classifyEndpointRole({
+        classification: endpoint.classification,
+        vendor: endpoint.vendor,
+        name: endpointName,
+      });
+
+      const endpointNode: NetworkTopologyNode = {
         id: nodeId,
         name: endpointName,
         isManaged: false,
         kind: "endpoint",
-        role: classifyEndpointRole({
-          classification: endpoint.classification,
-          vendor: endpoint.vendor,
-          name: endpointName,
-        }),
+        role: endpointRole,
         status: NetworkTopologyUtil.statusFromLastSeen(
           endpoint.lastSeenAt,
           now,
@@ -799,7 +866,21 @@ export default class NetworkTopologyUtil {
         ipAddress: endpoint.ipAddress,
         classification: endpoint.classification,
         vlanId: endpoint.vlanId,
-      });
+      };
+
+      /*
+       * Endpoints are stamped too, so a project that renamed "IP phone" sees
+       * the new name on the handsets its switches learned. It cannot change
+       * where they sit: the layouts put every endpoint in its switch's group
+       * box before they ever look at a role, so isCoreLayerRole is inert here
+       * by construction rather than by omission.
+       */
+      applyRoleStamp(
+        endpointNode,
+        stampForRoleKey(roleKeyForNode(undefined, endpointRole), roleIndex),
+      );
+
+      nodes.push(endpointNode);
 
       // Port label + interface state on the switch end, when identifiable.
       let switchInterface: TopologyInterfaceInput | undefined = undefined;
@@ -1264,6 +1345,10 @@ export default class NetworkTopologyUtil {
   private static buildUnmanagedPeerNodes(
     resolvedClaims: Array<ResolvedClaim>,
     nodes: Array<NetworkTopologyNode>,
+    roleIndex: Map<string, TopologyDeviceRoleInput> = new Map<
+      string,
+      TopologyDeviceRoleInput
+    >(),
   ): Map<ResolvedClaim, string> {
     const unmanagedClaims: Array<ResolvedClaim> = resolvedClaims.filter(
       (resolved: ResolvedClaim) => {
@@ -1359,21 +1444,22 @@ export default class NetworkTopologyUtil {
       usedNodeIds.add(nodeId);
 
       const unmanagedName: string = displayName || "Unknown device";
-      nodes.push({
+      /*
+       * Classified from the whole group rather than from whichever
+       * report happened to be first: the platform string is usually the
+       * only real evidence about a peer, and it may well arrive on the
+       * second report of it.
+       */
+      const unmanagedRole: NetworkTopologyDeviceRole = classifyDeviceRole({
+        platform: platform,
+        name: unmanagedName,
+      });
+      const unmanagedNode: NetworkTopologyNode = {
         id: nodeId,
         name: unmanagedName,
         isManaged: false,
         kind: "unmanaged",
-        /*
-         * Classified from the whole group rather than from whichever
-         * report happened to be first: the platform string is usually the
-         * only real evidence about a peer, and it may well arrive on the
-         * second report of it.
-         */
-        role: classifyDeviceRole({
-          platform: platform,
-          name: unmanagedName,
-        }),
+        role: unmanagedRole,
         status: "unknown",
         deviceModel: platform,
         /*
@@ -1383,7 +1469,19 @@ export default class NetworkTopologyUtil {
          * they can only look at.
          */
         ipAddress: ipAddress,
-      });
+      };
+
+      /*
+       * Stamped for the adopt-a-neighbour flow above all: isSnmpWalkableRole
+       * is what decides whether adopting this peer opens on SNMP polling or on
+       * a monitor, and a peer is exactly the node an operator adopts.
+       */
+      applyRoleStamp(
+        unmanagedNode,
+        stampForRoleKey(roleKeyForNode(undefined, unmanagedRole), roleIndex),
+      );
+
+      nodes.push(unmanagedNode);
 
       for (const resolved of groupClaims) {
         nodeIdByClaim.set(resolved, nodeId);
@@ -1571,9 +1669,13 @@ export default class NetworkTopologyUtil {
 
   /*
    * The shared reachability rule (DeviceReachabilityUtil), mapped onto the
-   * graph's three node states. "Pending" — never polled — is the graph's
-   * "unknown", which is what keeps a device nothing walks from being drawn
-   * as a failure.
+   * graph's three node states. "Pending" — never polled, or monitor-backed
+   * with nothing reported yet — is the graph's "unknown", which is what
+   * keeps a device nothing walks from being drawn as a failure.
+   *
+   * Only reached with no stamped status (deviceStatus took every stamped
+   * one), so the monitoring method is the one fact left that tells the rule
+   * whether the poll columns are evidence or leftovers.
    */
   private static statusFromPoll(
     device: TopologyDeviceInput,
@@ -1585,6 +1687,7 @@ export default class NetworkTopologyUtil {
         lastPolledAt: device.lastPolledAt,
         lastSeenAt: device.lastSeenAt,
         pollingIntervalInMinutes: device.pollingIntervalInMinutes,
+        monitoringMethod: device.monitoringMethod,
       },
       now,
     );

package/Utils/NetworkDevice/DeviceHealthStateUtil.ts

@@ -1,6 +1,7 @@
 import DeviceReachabilityUtil, {
   NetworkDeviceReachability,
 } from "./DeviceReachabilityUtil";
+import { NetworkDeviceMonitoringMethodUtil } from "../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
 
 /*
  * The one place that decides how healthy a single NetworkDevice is, and how
@@ -15,10 +16,12 @@ import DeviceReachabilityUtil, {
  *
  * So the rule moves here, and both halves read it:
  *
- *   status  — a monitor-stamped status wins outright; otherwise the shared
- *             reachability rule (the OUTCOME of the last poll, never its
- *             age) decides, and a device nothing has ever polled is
- *             `unknown` rather than a failure.
+ *   status  — for a MONITOR-BACKED device the stamped monitor status is the
+ *             verdict; for a probe-polled device the shared reachability
+ *             rule (the OUTCOME of the last poll, never its age) decides and
+ *             the stamp is informational only (see the input docs); a device
+ *             nothing has ever polled — or a monitor-backed device nothing
+ *             has yet reported on — is `unknown` rather than a failure.
  *   degraded — an up device with dark ports. A switch that answers every
  *             poll while three of its interfaces are down is not down, but
  *             it is exactly what somebody is looking for.
@@ -55,9 +58,18 @@ export type NetworkDeviceHealthState =
  * The columns the classifier reads. Every caller selects exactly these.
  *
  * `monitorStatusIsOffline` is the OFFLINE end of the device's stamped
- * MonitorStatus row — `undefined` when no monitor backs the device (the
- * ordinary case for an SNMP-walked switch), which is what sends the
- * decision down to reachability.
+ * MonitorStatus row — `undefined` when nothing has stamped one, which is
+ * what sends the decision down to reachability.
+ *
+ * It is CONSULTED ONLY FOR A MONITOR-BACKED DEVICE (monitoringMethod
+ * "Monitor"). A probe-polled device can carry a stamp too — a Network
+ * Device monitor watching its walk writes one, and an "interface down →
+ * Offline" criterion will happily stamp Offline on a switch that answers
+ * every ping — but its health source is the poll: `isReachable` is what its
+ * pill, the summary tiles and the Status chip all read, and a classifier
+ * that let the stamp outrank it would colour the site card and the map red
+ * over a device whose own row reads Up. So for a probe-polled device the
+ * stamp stays informational and reachability decides.
  *
  * The offline end and not the operational end, because MonitorStatus is a
  * ladder rather than a pair: the seeded rows run Operational (1) ...
@@ -74,6 +86,24 @@ export interface DeviceHealthStateInput {
   lastPolledAt?: Date | string | null | undefined;
   lastSeenAt?: Date | string | null | undefined;
   pollingIntervalInMinutes?: number | null | undefined;
+  /*
+   * How this device's health is established. NULL, empty and anything
+   * unrecognised read as Probe — see NetworkDeviceMonitoringMethodUtil.parse,
+   * which is why an omitted value keeps every existing caller on the poll
+   * rule unchanged.
+   *
+   * Load-bearing twice. It decides whether `monitorStatusIsOffline` above is
+   * read at all (only for a monitor-backed device). And when a monitor-backed
+   * device has NO stamped status to read — nothing bound yet, or bound and
+   * never evaluated — the shared rule answers Pending ("unknown" here)
+   * rather than falling through to the poll columns, which on such a device
+   * are either NULL or, worse, the last thing a probe found before it
+   * stopped asking: a device switched from Probe to Monitor keeps its old
+   * lastSeenAt until the switch-over clears it, and a caller that dropped
+   * this field would let that months-old timestamp call the device "down" on
+   * the site card while its own row in the device list reads Pending.
+   */
+  monitoringMethod?: string | null | undefined;
   interfacesDown?: number | null | undefined;
 }
 
@@ -96,11 +126,13 @@ export interface DeviceHealthCounts {
 /**
  * The state of one device.
  *
- * Order is load-bearing. A stamped monitor status is the operator's own
- * system of record and beats everything; then hard-down beats everything
- * else, because a device that does not answer has interface counts that
- * are by definition stale; then — and only for a device known to be up —
- * dark ports make it degraded.
+ * Order is load-bearing. On a monitor-backed device the stamped monitor
+ * status is the operator's own system of record and beats everything; on a
+ * probe-polled one the poll's outcome does (the stamp is informational —
+ * see the input docs); then hard-down beats everything else, because a
+ * device that does not answer has interface counts that are by definition
+ * stale; then — and only for a device known to be up — dark ports make it
+ * degraded.
  *
  * Note what this means for a device stamped "Degraded": the ladder does not
  * call it offline, so it is up, and it lands in "degraded" only if it also
@@ -119,9 +151,19 @@ export function deviceHealthState(
 
   let isUp: boolean;
 
+  /*
+   * The stamp is read for a monitor-backed device and nothing else. The
+   * shared reachability rule below applies the same gate, so the two
+   * branches cannot be reached with different ideas of what kind of device
+   * this is.
+   */
+  const isMonitorBacked: boolean =
+    NetworkDeviceMonitoringMethodUtil.isMonitorBacked(device.monitoringMethod);
+
   if (
-    device.monitorStatusIsOffline === true ||
-    device.monitorStatusIsOffline === false
+    isMonitorBacked &&
+    (device.monitorStatusIsOffline === true ||
+      device.monitorStatusIsOffline === false)
   ) {
     // Anything the ladder does not call OFFLINE is up. See the input docs.
     isUp = !device.monitorStatusIsOffline;
@@ -133,6 +175,15 @@ export function deviceHealthState(
           lastPolledAt: device.lastPolledAt,
           lastSeenAt: device.lastSeenAt,
           pollingIntervalInMinutes: device.pollingIntervalInMinutes,
+          /*
+           * Carried so the shared rule knows whether the poll columns above
+           * mean anything. A monitor-backed device only reaches this branch
+           * with NO stamped status (the one above took every stamped one),
+           * so for it this is exactly the "Pending" case — see the input
+           * docs. A probe-polled device always reaches it, stamp or no
+           * stamp, and is judged by its poll.
+           */
+          monitoringMethod: device.monitoringMethod,
         },
         now,
       );

package/Utils/NetworkDevice/DeviceReachabilityUtil.ts

@@ -1,5 +1,6 @@
 import OneUptimeDate from "../../Types/Date";
 import { NetworkDeviceMonitoringMethodUtil } from "../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
+import ObjectID from "../../Types/ObjectID";
 
 /*
  * The one place that decides whether a NetworkDevice is reachable.
@@ -21,13 +22,15 @@ import { NetworkDeviceMonitoringMethodUtil } from "../../Types/NetworkDevice/Net
  * window.
  *
  * So reachability is now the OUTCOME of the most recent poll —
- * NetworkDevice.isReachable, stamped by the walk pipeline on every ingested
- * walk — and freshness is only a backstop for "the polling pipeline itself
- * stopped", measured generously against the device's own interval.
+ * NetworkDevice.isReachable, stamped by the poll pipeline on every ingested
+ * poll (a ping, plus the SNMP walk on a device that has credentials; the
+ * device is reachable when either answers) — and freshness is only a
+ * backstop for "the polling pipeline itself stopped", measured generously
+ * against the device's own interval.
  *
  * All of which is about a device that gets POLLED. A monitor-backed device
- * (monitoringMethod "Monitor") is never polled at all: no probe, no
- * credentials, no walk. Every poll column on such a row is NULL forever, so
+ * (monitoringMethod "Monitor") is never polled at all: no probe, no ping,
+ * no walk. Every poll column on such a row is NULL forever, so
  * the rule above can only ever answer "Pending" for it — which is
  * OneUptime/oneuptime#3392, a correctly bound ping-only device stuck on
  * Pending. Its health comes from the Monitor bound to it, stamped onto
@@ -69,12 +72,13 @@ export const DEVICE_MIN_STALE_WINDOW_IN_MINUTES: number = 60;
 // The columns this util reads. Every caller selects exactly these.
 export interface DeviceReachabilityInput {
   /*
-   * Outcome of the most recent poll: true = the device answered, false = the
-   * probe could not reach it, null/undefined = never polled, or a row
-   * written before this column existed.
+   * Outcome of the most recent poll: true = the device answered (ping, or
+   * the SNMP walk — either is enough), false = the probe could not reach it
+   * by any means, null/undefined = never polled, or a row written before
+   * this column existed.
    */
   isReachable?: boolean | null | undefined;
-  // When the probe last ATTEMPTED a walk, whatever the outcome.
+  // When the probe last ATTEMPTED a poll, whatever the outcome.
   lastPolledAt?: Date | string | null | undefined;
   // When the device last ANSWERED one.
   lastSeenAt?: Date | string | null | undefined;
@@ -82,7 +86,7 @@ export interface DeviceReachabilityInput {
   pollingIntervalInMinutes?: number | null | undefined;
   /*
    * How this device's health is established. NULL, empty and anything
-   * unrecognised read as SNMP — see NetworkDeviceMonitoringMethodUtil.parse,
+   * unrecognised read as Probe — see NetworkDeviceMonitoringMethodUtil.parse,
    * which is why an omitted value keeps every existing caller on the poll
    * rule unchanged.
    */
@@ -102,6 +106,31 @@ export interface DeviceReachabilityInput {
    * way for the same reason.
    */
   monitorStatusIsOffline?: boolean | null | undefined;
+
+  /*
+   * QUALIFIER inputs. None of the four below moves the Up / Down / Pending
+   * verdict — the rule above is deliberately decided by `isReachable` alone,
+   * so the pill, the summary tiles and the Status chip (all SQL over that one
+   * column) can never disagree. They ride on the same input so a surface can
+   * hand its whole row over once and put the second, explanatory pill
+   * ("SNMP failing", "No probe") beside the verdict; see the predicates in
+   * the dashboard's DeviceStatusUtil.
+   *
+   * `isSnmpReachable`: the outcome of the last SNMP WALK, separate from the
+   * ping — false is a device that answers ping but not SNMP (credentials, or
+   * SNMP disabled on the box), NULL is "no walk was attempted": no usable
+   * credentials, or never polled.
+   */
+  isSnmpReachable?: boolean | null | undefined;
+  // When the last SUCCESSFUL walk completed; only moves on a success.
+  lastSnmpSeenAt?: Date | string | null | undefined;
+  /*
+   * Which probe polls the device, and whether it is allowed to. A probe-polled
+   * device with no probe, or with polling switched off, can never be polled
+   * and is Pending for as long as that stays true.
+   */
+  probeId?: ObjectID | string | null | undefined;
+  isPollingEnabled?: boolean | null | undefined;
 }
 
 export interface DeviceReachabilityResult {
@@ -119,10 +148,10 @@ export interface DeviceReachabilityResult {
   // Latest of lastPolledAt / lastSeenAt; null when neither is set.
   lastContactAt: Date | null;
   /*
-   * True when this verdict came from the bound Monitor rather than from an
-   * SNMP poll. Carried so a surface can word its pill and its tooltip for
-   * what actually decided the answer — "the last SNMP poll reached this
-   * device" is a lie on a device nothing polls.
+   * True when this verdict came from the bound Monitor rather than from a
+   * probe's poll. Carried so a surface can word its pill and its tooltip for
+   * what actually decided the answer — "the last poll reached this device"
+   * is a lie on a device nothing polls.
    */
   isMonitorBacked: boolean;
 }

package/Utils/NetworkDevice/DeviceRoleKeyUtil.ts

@@ -0,0 +1,137 @@
+/*
+ * Turns a device role's NAME into its stable KEY.
+ *
+ * Device roles are per-project rows an operator can rename at will, which is
+ * exactly why nothing may identify one by its name. The key is what does the
+ * identifying: it is what the SNMP classifier's answer is matched against,
+ * what a topology payload carries, and what survives the role being renamed.
+ *
+ * The shape is lowerCamelCase, because the eleven built-in roles seeded into
+ * every project already use it ("wirelessAccessPoint", "loadBalancer") and a
+ * key derived from the name "Wireless AP" must be able to look like one of
+ * them. Anything that is not a letter or a digit is a word boundary, so
+ * "PoS Terminal", "pos-terminal" and "POS  terminal!" all derive "posTerminal"
+ * - near-duplicates collapse rather than multiplying.
+ *
+ * Pure and dependency-free: the service derives keys with it on the server and
+ * the tests exercise it directly.
+ */
+
+// Keys are stored in a ShortText column; nothing sensible is this long.
+const MAX_KEY_LENGTH: number = 100;
+
+/*
+ * A name of nothing but punctuation ("---") has no letters to build a key
+ * from. Rather than returning an empty string - which would fail the column's
+ * NOT NULL and surface as a database error - it falls back to this, and the
+ * caller's uniqueness suffixing turns the second one into "role2".
+ */
+export const FALLBACK_DEVICE_ROLE_KEY: string = "role";
+
+export type DeriveDeviceRoleKeyFunction = (name: string) => string;
+
+/**
+ * The key for a role named `name`. Deterministic and case-insensitive over
+ * word separators: it is safe to call twice and get the same answer.
+ */
+export const deriveDeviceRoleKey: DeriveDeviceRoleKeyFunction = (
+  name: string,
+): string => {
+  const words: Array<string> = (name || "")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((word: string) => {
+      return word.length > 0;
+    });
+
+  if (words.length === 0) {
+    return FALLBACK_DEVICE_ROLE_KEY;
+  }
+
+  /*
+   * A ONE-WORD name is only re-cased at its first letter. A MULTI-word name
+   * has its first word lowercased whole, and every later word capitalised at
+   * the front with its interior left alone.
+   *
+   * Both halves are load-bearing, and for different reasons.
+   *
+   * Lowercasing the head of a multi-word name is what makes the key readable.
+   * Re-casing only its first letter turns "PoS Terminal" into "poSTerminal"
+   * and "IP phone" into "iPPhone", and this key is a column an operator reads
+   * on the settings page. Later words keep their interior for the opposite
+   * reason: "Wireless AP" should read as "wirelessAP" and "SD-WAN Edge" as
+   * "sdWANEdge", because those acronyms are the boundaries a reader navigates
+   * by.
+   *
+   * Leaving a one-word name alone is what makes every derived key a FIXED
+   * POINT of this function. A derived key is always a single run of letters
+   * and digits, so re-deriving it takes this branch and returns it unchanged -
+   * "wirelessAccessPoint" stays "wirelessAccessPoint", and a key that is
+   * accidentally fed back in as a name cannot silently move a role's identity.
+   * It is also honest: a name with no word boundaries has no boundaries to
+   * normalise.
+   */
+  const key: string =
+    words.length === 1
+      ? words[0]!.charAt(0).toLowerCase() + words[0]!.slice(1)
+      : words
+          .map((word: string, index: number): string => {
+            if (index === 0) {
+              return word.toLowerCase();
+            }
+            return word.charAt(0).toUpperCase() + word.slice(1);
+          })
+          .join("");
+
+  /*
+   * A key starting with a digit ("5gRouter") is still a fine identifier here -
+   * it is a lookup key, not a JavaScript name - so only the length is capped.
+   */
+  return key.slice(0, MAX_KEY_LENGTH);
+};
+
+export type BuildUniqueDeviceRoleKeyFunction = (
+  name: string,
+  takenKeys: ReadonlySet<string>,
+) => string;
+
+/**
+ * The key for a role named `name` that no other role in the project holds.
+ *
+ * Two differently-named roles can derive the same key ("PoS Terminal" and
+ * "pos_terminal" both give "posTerminal"), and the column is unique per
+ * project, so the second one has to move. It gets a numeric suffix rather than
+ * a random one so the result stays readable and stable for a given project
+ * state - "posTerminal2", not "posTerminal-f3a9".
+ *
+ * Comparison is case-insensitive because that is how the key is matched when
+ * a role is looked up; two keys differing only in case would collide there.
+ */
+export const buildUniqueDeviceRoleKey: BuildUniqueDeviceRoleKeyFunction = (
+  name: string,
+  takenKeys: ReadonlySet<string>,
+): string => {
+  const taken: Set<string> = new Set<string>();
+  for (const key of takenKeys) {
+    taken.add(key.trim().toLowerCase());
+  }
+
+  const base: string = deriveDeviceRoleKey(name);
+
+  if (!taken.has(base.toLowerCase())) {
+    return base;
+  }
+
+  /*
+   * Bounded so a pathological project cannot spin here. Past the bound the
+   * caller gets the base key back and the database's unique constraint
+   * rejects the create - a loud, correct failure rather than a hang.
+   */
+  for (let suffix: number = 2; suffix < 1000; suffix++) {
+    const candidate: string = `${base}${suffix}`;
+    if (!taken.has(candidate.toLowerCase())) {
+      return candidate;
+    }
+  }
+
+  return base;
+};