Create-link mode: pick two devices, suggest link types, then pick ports #10

Closed
opened 2026-11-08 06:07:45 +00:00 by jaylouisw · 1 comment
Owner

Problem / motivation

Cabling today is port-first. To link two devices you must already know which
socket
on each box is the right one before the engine will help you:

  1. Click a port on device A → status becomes "Now click the destination port (Esc to cancel)".
  2. Click a port on device B.
  3. POST /topologies/:id/validate-link dry-runs the pair; an impossible pair is blocked (web/app.js → PFCanvas.on.portClick).
  4. Only if the pair is legal and more than one medium fits does pickLinkMedia() offer a medium choice.

The physical model is correct; the order is backwards for how people actually
build a lab. The natural step is "these two boxes need to talk", then "how, and
through which sockets?" — but the UI forces the "which socket?" decision first.
On high-port-count devices the first click is a guess, and a wrong guess is
rejected without saying which of the other pairs would have worked.

The port-first flow is also the one that keeps breaking: #1 (ghost cable
swallows the destination-port click) and #2 (cables paint over sockets and block
them) are both symptoms of the whole interaction being built on pixel-perfect
port clicking. A device-first flow sidesteps both.

Proposed solution

Add a Create link mode as an additive flow (keep the existing click-a-port
fast path for power users):

  1. Button in the corner of the canvas. A "Create link" button in
    #canvas-toolbar, next to zoom in / out / fit (web/index.html:69). Clicking
    it arms link mode: the cursor changes, the hint becomes "Click the first
    device", and Esc cancels.
  2. Click two devices (whole device, not a port). First click highlights
    device A, second highlights device B.
  3. Suggest viable link types. On the second click the engine enumerates the
    free interfaces on both devices (iface.peer === null) and, for every
    compatible pair, reuses the existing primitives —
    derivePortHardware() + commonMedia() / canMate() / negotiateSpeed()
    in engine/media.js, and topo.mediaOptions() / topo.validateLink() in
    engine/topology.js — to aggregate the media that can carry a link. The UI
    then shows a short list of link types (not ports): "10GBASE-LR fibre",
    "10GBASE-T copper", "1000BASE-T", each with the negotiated speed and any
    warnings (rate downgrade, reach, POE).
  4. Then select the ports. After picking a link type, the UI shows the port
    pairs that support that medium ("Gi0/1 ↔ eth1", "Gi0/2 ↔ eth2", …) and the
    user clicks the two ports to commit — the existing
    POST /topologies/:id/links path does the rest.
  5. If no free pair on the two devices can mate, say so up front and why (reuse
    the existing error codes — E_CONNECTOR_MISMATCH, E_NO_COMMON_MEDIA,
    E_COMBO_OCCUPIED, …) instead of failing one port-pair at a time.

Feasibility

No new medium/cage logic is required — the physical model already lives in
engine/media.js and engine/validation.js. This is a UI orchestration change
plus one small helper on Topology, e.g. topo.linkOptions(aId, bId) returning,
per free compatible port pair, { a: {iface}, b: {iface}, media: [...], speedMbps, warnings }
(a device-level analogue of the per-port mediaOptions()). That helper is
independently unit-testable against the existing connector tests.

Gotchas to respect: combo ports report one occupied sibling (E_COMBO_OCCUPIED),
wireless ports are associations not cables, and the PON polish rule (sc-apc vs
sc-upc) must hold when ranking pairs.

Alternatives considered

  • Auto-suggest only the destination port (keep port-first). Smaller change,
    but still forces the "which socket on device A?" guess first and does not solve
    the discoverability problem on high-port-count devices.
  • Drag from device to device instead of two clicks. Same backend work, but
    drag precision on a panned/zoomed SVG canvas is fiddlier than two clicks and
    collides with the existing drag-to-move gesture.
  • Auto-cable on placement (silently connect the nearest free compatible
    ports). Rejected: the engine deliberately refuses impossible pairs for good
    reasons, and silent port choice hides exactly the decisions this feature is
    meant to surface.
  • #1 — ghost cable swallows the destination-port click
  • #2 — cables paint over sockets and block them
  • #3 — cables can't be deleted; a "Create link" mode should ship with a symmetric remove-link affordance
## Problem / motivation Cabling today is **port-first**. To link two devices you must already know *which socket* on each box is the right one before the engine will help you: 1. Click a port on device A → status becomes "Now click the destination port (Esc to cancel)". 2. Click a port on device B. 3. `POST /topologies/:id/validate-link` dry-runs the pair; an impossible pair is blocked (`web/app.js` → `PFCanvas.on.portClick`). 4. Only if the pair is legal *and* more than one medium fits does `pickLinkMedia()` offer a medium choice. The physical model is correct; the *order* is backwards for how people actually build a lab. The natural step is "these two boxes need to talk", then "how, and through which sockets?" — but the UI forces the "which socket?" decision first. On high-port-count devices the first click is a guess, and a wrong guess is rejected without saying *which* of the other pairs would have worked. The port-first flow is also the one that keeps breaking: #1 (ghost cable swallows the destination-port click) and #2 (cables paint over sockets and block them) are both symptoms of the whole interaction being built on pixel-perfect port clicking. A device-first flow sidesteps both. ## Proposed solution Add a **Create link** mode as an additive flow (keep the existing click-a-port fast path for power users): 1. **Button in the corner of the canvas.** A "Create link" button in `#canvas-toolbar`, next to zoom in / out / fit (`web/index.html:69`). Clicking it arms link mode: the cursor changes, the hint becomes "Click the first device", and `Esc` cancels. 2. **Click two devices** (whole device, not a port). First click highlights device A, second highlights device B. 3. **Suggest viable link types.** On the second click the engine enumerates the *free* interfaces on both devices (`iface.peer === null`) and, for every compatible pair, reuses the existing primitives — `derivePortHardware()` + `commonMedia()` / `canMate()` / `negotiateSpeed()` in `engine/media.js`, and `topo.mediaOptions()` / `topo.validateLink()` in `engine/topology.js` — to aggregate the media that can carry a link. The UI then shows a short list of **link types** (not ports): "10GBASE-LR fibre", "10GBASE-T copper", "1000BASE-T", each with the negotiated speed and any warnings (rate downgrade, reach, POE). 4. **Then select the ports.** After picking a link type, the UI shows the port pairs that support that medium ("Gi0/1 ↔ eth1", "Gi0/2 ↔ eth2", …) and the user clicks the two ports to commit — the existing `POST /topologies/:id/links` path does the rest. 5. If no free pair on the two devices can mate, say so up front and *why* (reuse the existing error codes — `E_CONNECTOR_MISMATCH`, `E_NO_COMMON_MEDIA`, `E_COMBO_OCCUPIED`, …) instead of failing one port-pair at a time. ### Feasibility No new medium/cage logic is required — the physical model already lives in `engine/media.js` and `engine/validation.js`. This is a UI orchestration change plus one small helper on `Topology`, e.g. `topo.linkOptions(aId, bId)` returning, per free compatible port pair, `{ a: {iface}, b: {iface}, media: [...], speedMbps, warnings }` (a device-level analogue of the per-port `mediaOptions()`). That helper is independently unit-testable against the existing connector tests. Gotchas to respect: combo ports report one occupied sibling (`E_COMBO_OCCUPIED`), wireless ports are associations not cables, and the PON polish rule (`sc-apc` vs `sc-upc`) must hold when ranking pairs. ## Alternatives considered - **Auto-suggest only the destination port (keep port-first).** Smaller change, but still forces the "which socket on device A?" guess first and does not solve the discoverability problem on high-port-count devices. - **Drag from device to device** instead of two clicks. Same backend work, but drag precision on a panned/zoomed SVG canvas is fiddlier than two clicks and collides with the existing drag-to-move gesture. - **Auto-cable on placement** (silently connect the nearest free compatible ports). Rejected: the engine deliberately refuses impossible pairs for good reasons, and silent port choice hides exactly the decisions this feature is meant to surface. ## Related - #1 — ghost cable swallows the destination-port click - #2 — cables paint over sockets and block them - #3 — cables can't be deleted; a "Create link" mode should ship with a symmetric remove-link affordance
Author
Owner

Shipped as create-link mode: pick two devices, get the link types the pair can actually support, then pick ports. It is in the app now and test/link-mode-ui.test.js (20 checks) covers arming, selecting, the suggestions and the port picker.

The port-first path still exists for people who already know the socket — this added the other order rather than replacing it.

Shipped as create-link mode: pick two devices, get the link types the pair can actually support, then pick ports. It is in the app now and `test/link-mode-ui.test.js` (20 checks) covers arming, selecting, the suggestions and the port picker. The port-first path still exists for people who already know the socket — this added the other order rather than replacing it.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge#10
No description provided.