ccdeck 3.29.11 → 3.31.0

package/src/server/lan-reach.mjs

@@ -212,6 +212,67 @@ export function fixSteps({ category, alias, exePath, rules = [] }) {
   return steps;
 }
 
+/**
+ * Whether other decks can reach this Windows machine, from what the probe read:
+ * the network the deck is on, the firewall profile that network answers to,
+ * and the rules for this program.
+ *
+ * Null for a probe that did not come back, for a network that is not Public,
+ * Private or Domain, and for rules that could not be read on a network that is
+ * not Public — see below for why that last one is silence rather than a guess.
+ */
+function windowsReach({ probe = null, aliases = [], exePath = "", inbound = null } = {}) {
+  if (!probe) return null;
+  // The broadcast route first, then the interfaces the deck holds an address
+  // on. The routing table is the authority on where a beacon goes; the deck's
+  // own addresses are the fallback for a machine where that read came back
+  // empty, and the probe's first connected network is the fallback for that.
+  const net = lanNet(probe.nets, [probe.bcast, ...aliases]);
+  const category = net?.category ?? "";
+  const name = profileFor(category);
+  if (!name) return null;
+  // MEASURED BEATS READ, here as on Linux: a connection from another machine
+  // has arrived on the sync listener, so the path is open whatever rule this
+  // was about to fail to find. See inboundAt in lan-inbound.mjs.
+  if (inbound) return { blocked: false, why: "inbound seen", category, alias: net?.alias ?? "" };
+  const prof = probe.profiles.find(p => p.name.toLowerCase() === name.toLowerCase());
+  // A firewall that is off blocks nothing, and saying otherwise would send
+  // somebody to add a rule that changes nothing.
+  if (prof && !prof.enabled) return { blocked: false, why: "firewall off", category, alias: net?.alias ?? "" };
+  if (ruleCovers(probe.rules, name)) {
+    return { blocked: false, why: "rule present", category, alias: net?.alias ?? "" };
+  }
+  // COULD NOT READ THE RULES, SO CANNOT SAY THERE IS NONE. An empty list here
+  // is "Access is denied", not "no rule" (see PROBE_PS), so claiming a missing
+  // rule would be a guess dressed as a read — and the command that guess hands
+  // over adds a duplicate rule on a machine that may already be covered. On a
+  // Public network the fix is the category, which was read reliably, so that
+  // verdict still stands; anywhere else the honest answer is the measurement,
+  // which `refreshReach` falls back to when this returns null.
+  // Only an EMPTY list is ambiguous — a rule in hand was plainly readable,
+  // whatever the flag says.
+  if (!probe.rulesReadable && probe.rules.length === 0 && name !== "Public") return null;
+  return {
+    blocked: true,
+    why: "no inbound rule",
+    category,
+    alias: net?.alias ?? "",
+    // Which shell the steps are written in, so the panel says where to paste
+    // them without asking what platform it is drawing for. Every other field
+    // here is already the verdict's to choose; this is one more.
+    shell: "powershell",
+    // The reason in the reader's terms, not the registry's. What they need to
+    // know is which half is broken, because the other half is what makes the
+    // workaround below obvious rather than magic.
+    text: name === "Public"
+      ? "This network is set to Public, and Windows drops what other decks send. They can still hear this deck — that is why one of them may already show it."
+      : name === "Domain" && probe.rules.length
+        ? "Windows lets this deck in on Private networks only, and this one is a company (Domain) network, so it drops what other decks send. They can still hear it — that is why one of them may already show this machine."
+        : "Windows has no inbound rule for this deck, so it drops what other decks send. They can still hear it — that is why one of them may already show this machine.",
+    steps: fixSteps({ category, alias: net?.alias ?? "", exePath, rules: probe.rules }),
+  };
+}
+
 // ── linux ───────────────────────────────────────────────────────────────────
 //
 // THE SAME FAILURE, ONE DISTRIBUTION FURTHER. Reported from a pair of decks on
@@ -230,8 +291,8 @@ export function fixSteps({ category, alias, exePath, rules = [] }) {
 //
 // SO THE MEASUREMENT CARRIES THE VERDICT AND THE CONFIGURATION ONLY RAISES
 // THE QUESTION. `inbound` is when a connection from another machine last
-// arrived on the sync listener (see lan-engine's inboundAt). If one ever has,
-// the path is open and nothing here has an opinion, whatever the rule files
+// arrived on the sync listener (see inboundAt in lan-inbound.mjs). If one ever
+// has, the path is open and nothing here has an opinion, whatever the rule files
 // say. Only when the firewall is on, its inbound default drops, and nothing
 // has ever got in does this speak — and it says what it measured, in those
 // terms, rather than claiming to have read a rule it cannot read.
@@ -472,75 +533,9 @@ export function reachability({ platform, probe, aliases = [], exePath = "", inbo
   if (platform === "linux") return linux ? linuxReach({ ...linux, inbound }) : null;
   if (platform === "darwin") return mac ? macReach({ probe: mac, exePath, inbound }) : null;
   if (platform !== "win32") return null;
-  if (!probe) return null;
-  // The broadcast route first, then the interfaces the deck holds an address
-  // on. The routing table is the authority on where a beacon goes; the deck's
-  // own addresses are the fallback for a machine where that read came back
-  // empty, and the probe's first connected network is the fallback for that.
-  const net = lanNet(probe.nets, [probe.bcast, ...aliases]);
-  const category = net?.category ?? "";
-  const name = profileFor(category);
-  if (!name) return null;
-  // MEASURED BEATS READ, here as on Linux: a connection from another machine
-  // has arrived on the sync listener, so the path is open whatever rule this
-  // was about to fail to find. See lan-engine's inboundAt.
-  if (inbound) return { blocked: false, why: "inbound seen", category, alias: net?.alias ?? "" };
-  const prof = probe.profiles.find(p => p.name.toLowerCase() === name.toLowerCase());
-  // A firewall that is off blocks nothing, and saying otherwise would send
-  // somebody to add a rule that changes nothing.
-  if (prof && !prof.enabled) return { blocked: false, why: "firewall off", category, alias: net?.alias ?? "" };
-  if (ruleCovers(probe.rules, name)) {
-    return { blocked: false, why: "rule present", category, alias: net?.alias ?? "" };
-  }
-  // COULD NOT READ THE RULES, SO CANNOT SAY THERE IS NONE. An empty list here
-  // is "Access is denied", not "no rule" (see PROBE_PS), so claiming a missing
-  // rule would be a guess dressed as a read — and the command that guess hands
-  // over adds a duplicate rule on a machine that may already be covered. On a
-  // Public network the fix is the category, which was read reliably, so that
-  // verdict still stands; anywhere else the honest answer is the measurement,
-  // which `refreshReach` falls back to when this returns null.
-  // Only an EMPTY list is ambiguous — a rule in hand was plainly readable,
-  // whatever the flag says.
-  if (!probe.rulesReadable && probe.rules.length === 0 && name !== "Public") return null;
-  return {
-    blocked: true,
-    why: "no inbound rule",
-    category,
-    alias: net?.alias ?? "",
-    // Which shell the steps are written in, so the panel says where to paste
-    // them without asking what platform it is drawing for. Every other field
-    // here is already the verdict's to choose; this is one more.
-    shell: "powershell",
-    // The reason in the reader's terms, not the registry's. What they need to
-    // know is which half is broken, because the other half is what makes the
-    // workaround below obvious rather than magic.
-    text: name === "Public"
-      ? "This network is set to Public, and Windows drops what other decks send. They can still hear this deck — that is why one of them may already show it."
-      : name === "Domain" && probe.rules.length
-        ? "Windows lets this deck in on Private networks only, and this one is a company (Domain) network, so it drops what other decks send. They can still hear it — that is why one of them may already show this machine."
-        : "Windows has no inbound rule for this deck, so it drops what other decks send. They can still hear it — that is why one of them may already show this machine.",
-    steps: fixSteps({ category, alias: net?.alias ?? "", exePath, rules: probe.rules }),
-  };
+  return windowsReach({ probe, aliases, exePath, inbound });
 }
 
-/**
- * The way out that needs no rule at all, and the reason this module is not the
- * whole answer.
- *
- * A round is one OUTBOUND connection — `roundWith` dials, both sides prove
- * themselves over that socket, and the manifest and any transfer ride it home.
- * Nothing in a round needs this machine to accept a connection. So a deck that
- * cannot be reached can still do every part of this by dialling first, and the
- * two controls that make it dial are an address somebody typed and an invite
- * somebody else minted.
- *
- * WHICH WAY THE INVITE GOES IS THE WHOLE OF IT, and nothing said so before.
- * An invite carries the addresses of the deck that MINTED it, and the deck that
- * PASTES it dials them. So a blocked machine that mints an invite is asking to
- * be called, which is the one thing it cannot receive; the same pair works on
- * the first try if the invite is minted at the other end and pasted here. Same
- * two controls, opposite order, and only one of the orders works.
- */
 // ── the machine nothing can be asked about ──────────────────────────────────
 //
 // Every block above depends on the operating system answering a question.
@@ -598,6 +593,24 @@ export function silentInbound({ heard = 0, listeningSince = null, inbound = null
   };
 }
 
+/**
+ * The way out that needs no rule at all, and the reason this module is not the
+ * whole answer.
+ *
+ * A round is one OUTBOUND connection — `roundWith` dials, both sides prove
+ * themselves over that socket, and the manifest and any transfer ride it home.
+ * Nothing in a round needs this machine to accept a connection. So a deck that
+ * cannot be reached can still do every part of this by dialling first, and the
+ * two controls that make it dial are an address somebody typed and an invite
+ * somebody else minted.
+ *
+ * WHICH WAY THE INVITE GOES IS THE WHOLE OF IT, and nothing said so before.
+ * An invite carries the addresses of the deck that MINTED it, and the deck that
+ * PASTES it dials them. So a blocked machine that mints an invite is asking to
+ * be called, which is the one thing it cannot receive; the same pair works on
+ * the first try if the invite is minted at the other end and pasted here. Same
+ * two controls, opposite order, and only one of the orders works.
+ */
 export function workaround(blocked) {
   if (!blocked) return null;
   return {

package/src/server/lan-requests.mjs

@@ -0,0 +1,249 @@
+// The decks waiting on somebody here: the ones that asked, the ones only heard,
+// and the ones somebody told no — and when each is answered for the owner by a
+// switch rather than a press. Lifted out of createEngine in lan-engine.mjs with
+// the three lists only these read and write. What an answer DOES — pinning a
+// key, or putting an address on the dial list — stays the engine's accept;
+// this decides who is on which list and when that accept is pressed.
+
+import { pairable } from "./lan-sync.mjs";
+
+/**
+ * The two permissions that answer for one route.
+ *
+ * READ OFF WHICHEVER SETTINGS ARE ASKED ABOUT, because two places ask. A beacon
+ * or a request asks of the settings in force; `apply` asks of the settings
+ * before a write and after it, to tell which switch the write turned on. The
+ * second used to spell the same conditions out again as its own pair, and a
+ * switch read one way here and another way there would answer a request in
+ * one place and leave it waiting in the other.
+ */
+export const asksOn = (cfg, via) => cfg.pairingMode !== "invite" && (via === "tailscale" ? !!cfg.tailscale && cfg.tailscaleAsk !== false : !!cfg.autoAsk);
+export const saysYesOn = (cfg, via) => cfg.pairingMode !== "invite" && (via === "tailscale" ? !!cfg.tailscale && cfg.tailscaleAccept !== false : !!cfg.autoAccept);
+
+/**
+ * `settings` answers the engine's settings in force at the moment of asking,
+ * and `engineNow` the engine itself, whose accept is what a switch presses.
+ * `routeTo` says whether an address is a tailnet one and whose, `wasUnpaired`
+ * whether somebody here unpaired a fingerprint, and `localAddresses` this
+ * machine's own addresses. `now` and `onChange` are the engine's own.
+ */
+export function createRequests({ now, settings, routeTo, wasUnpaired, engineNow, onChange, localAddresses }) {
+  /**
+   * Decks that finished a handshake and that nobody here has accepted yet, and
+   * decks merely heard shouting on the network. Two lists because they are two
+   * different claims: a pending deck proved it holds the key it announced, a
+   * heard one only said so. Both are rows with an accept on them; only the
+   * first is evidence.
+   *
+   * In memory rather than on disk. A request that is a day old is not a request
+   * any more, and a list of them that survives restarts is a list nobody reads.
+   */
+  const pending = new Map();
+  const strangers = new Map();
+  /**
+   * Decks somebody here said no to.
+   *
+   * WITHOUT THIS, DECLINING DID NOTHING THAT LASTED. A deck that asks is a deck
+   * that keeps asking — it dials on its own timer, and every dial that finds no
+   * pin here becomes a fresh request. So `dismiss` took a row off a list that
+   * the next minute put back, and on the other machine the refusal was
+   * indistinguishable from a deck that had not been answered yet: both are the
+   * same `pending` refusal on the wire, and both drew "waiting for the other
+   * deck to accept this one" forever.
+   *
+   * A name kept here is therefore two answers at once. This deck stops asking
+   * its owner, and the deck that asked is TOLD — see refuse("declined") in
+   * lan-socket.mjs, which is the only way the far end can ever learn that the
+   * answer was no rather than not yet.
+   *
+   * In memory, like the two lists above, and reversible: `allow` takes a name
+   * out and the requests come back. Nothing about it is written down, because a
+   * refusal that outlives the process is a decision nobody can find to undo.
+   */
+  const declined = new Map();
+
+  /**
+   * A real deck nobody here has accepted: draw it as a row with an accept on it.
+   *
+   * ONE HELPER FOR BOTH DIRECTIONS, because the evidence is the same either
+   * way. A deck that DIALLED this one finishes a handshake at the listener and
+   * arrives through `onPending`; a deck this one dialled finishes the same
+   * handshake in roundWith. Both have proved they hold the key they announced,
+   * and neither has been agreed to. Before #969 only the first raised a
+   * request and the second silently pinned itself.
+   *
+   * SAY YES FOR SOMEBODY WHO SAID TO. `autoAccept` is the accept button and
+   * nothing else: the same pin, from the same key the handshake just proved.
+   * Nothing about the wire changes — an inbound connection is still refused,
+   * because trust is read fresh per connection, and the caller comes back a few
+   * seconds later.
+   *
+   * A deck already told no does not become a row again. On the inbound path
+   * lan-socket refuses it before this is ever called; on the outbound one there
+   * is nothing before this, so the check lives here.
+   */
+  const askToAccept = entry => {
+    const cfg = settings();
+    if (cfg.pairingMode === "invite" || declined.has(entry.fp)) return;
+    const had = pending.get(entry.fp);
+    // WHICH SWITCH ANSWERS depends on where the deck is. A request from the
+    // tailnet is answered by the Tailscale pair, and only for a machine on this
+    // person's own Tailscale account; anything else on the tailnet waits for a
+    // press whatever either switch says. See routeOf.
+    const route = routeTo(entry.addr);
+    const via = route ? "tailscale" : "lan";
+    const own = !!route?.own;
+    pending.set(entry.fp, { ...entry, via, own, at: had?.at ?? now(), lastAt: now() });
+    if (!wasUnpaired(entry.fp) && saysYesOn(cfg, via) && (via === "lan" || own)) {
+      engineNow()?.accept(entry.fp, { byHand: false });
+      return;
+    }
+    if (!had) onChange?.();
+  };
+
+  /** A deck the beacon heard that nobody here has accepted: a row somebody
+   *  can accept, and — when the ask switch for its route is on — asked. */
+  const heardStranger = entry => {
+    const cfg = settings();
+    const had = strangers.get(entry.fp);
+    // KEYED BY MACHINE WHEN IT SAYS WHICH ONE IT IS. A computer that took
+    // a fresh key — a second deck sharing one config directory does, by
+    // design — used to leave its old key in this map for a day, and every
+    // one of them drew a row offering to pair with the same machine.
+    if (entry.host) for (const [fp, p] of strangers) if (p.host === entry.host && fp !== entry.fp) strangers.delete(fp);
+    const own = entry.via === "tailscale" && !!routeTo(entry.addr)?.own;
+    strangers.set(entry.fp, { ...entry, own });
+    // ASK IT, which is what the `ask` verb on its row does and nothing
+    // more: the address goes on the dial list and the next round sends a
+    // request that somebody over there still has to answer. A beacon
+    // carries a fingerprint and no key, so nothing is pinned here — see
+    // accept, which is deliberate about the difference.
+    //
+    // Only a deck that is NEW is asked, or a beacon every thirty seconds
+    // would be thirty seconds of asking; and never one this deck's owner
+    // already turned away.
+    // Never `byHand`: a beacon is a shout from an address nobody here
+    // named, and the row it leaves may ask rather than pin.
+    // Over the tailnet only a machine on this person's own account is
+    // asked unprompted; any other is a row for somebody to decide on.
+    const mayAsk = asksOn(cfg, entry.via) && (entry.via !== "tailscale" || own);
+    if (mayAsk && !had && !declined.has(entry.fp) && !wasUnpaired(entry.fp)) { engineNow().accept(entry.fp, { byHand: false }); return; }
+    // Only a deck that is new to us is news. A beacon every thirty
+    // seconds from one already on the list is not a reason to redraw.
+    if (!had) onChange?.();
+  };
+
+  /**
+   * What a settings write does to the decks already waiting, given the
+   * settings before it — the engine's apply calls this with them, after the
+   * write is in force.
+   */
+  const switched = was => {
+    // A request made before invite-only was enabled must not survive the
+    // switch and become an automatic approval when automatic mode returns.
+    // A fresh handshake after that switch may request pairing again.
+    if (was.pairingMode !== "invite" && settings().pairingMode === "invite" && pending.size) {
+      pending.clear();
+      onChange?.();
+    }
+    // TURNING IT ON ANSWERS WHAT IS ALREADY WAITING. A person who switches
+    // this on with two rows sitting in the panel means those two as much as
+    // the next one, and leaving them queued behind a setting called
+    // "automatic" is the switch not doing what it says.
+    //
+    // PER ROUTE, because each pair of switches answers for its own: turning
+    // the local one on does not answer a tailnet request, and turning the
+    // Tailscale one on answers only the owner's own machines.
+    const turnedOn = (f, via) => !f(was, via) && f(settings(), via);
+    const mayAnswer = p => (p.via === "tailscale" ? turnedOn(saysYesOn, "tailscale") && p.own : turnedOn(saysYesOn, "lan"));
+    for (const [fp, p] of [...pending]) if (!wasUnpaired(fp) && mayAnswer(p)) engineNow().accept(fp, { byHand: false });
+    // The same for the other direction: switching `ask` on with four machines
+    // already listed asks those four.
+    const mayAsk = p => (p.via === "tailscale" ? turnedOn(asksOn, "tailscale") && p.own : turnedOn(asksOn, "lan"));
+    for (const [fp, p] of [...strangers]) if (!declined.has(fp) && !wasUnpaired(fp) && !p.pub && mayAsk(p)) engineNow().accept(fp, { byHand: false });
+    // OFF MEANS THE TAILNET GOES QUIET HERE: nobody heard over it is offered,
+    // and the engine's tailnet poll stops the reads. Decks already paired stay
+    // paired.
+    if (was.tailscale && !settings().tailscale) {
+      for (const [fp, p] of [...strangers]) if (p.via === "tailscale") strangers.delete(fp);
+    }
+  };
+
+  /** The heard decks status() offers to pair with — see its `strangers`. */
+  const strangerRows = () => {
+    // A deck that was told no is not somebody to offer pairing with. It
+    // has its own row, with the one control that undoes the decision.
+    const heard = [...strangers.values()].filter(p => !declined.has(p.fp));
+    // pairable() collapses the rest by machine — see hostId. A computer
+    // that has run the deck a few times holds a key per run, and every
+    // one of them was a row of its own on everybody else's panel.
+    const { shown, more } = pairable(heard, now(), { mine: localAddresses() });
+    return shown.map(p => ({
+      fp: p.fp, name: p.name, addr: p.addr, port: p.port, at: p.at, more,
+      via: p.via ?? "lan", own: !!p.own,
+    }));
+  };
+
+  return {
+    askToAccept,
+    heardStranger,
+    switched,
+    /** Whether somebody here told this deck no — asked before a request is
+     *  drawn, on both paths. */
+    isDeclined: fp => declined.has(fp),
+    /** The row a deck is waiting on: its request when it asked, its beacon
+     *  when it was only heard, or null. */
+    seen: fp => (pending.get(fp) ?? null) ?? (strangers.get(fp) ?? null),
+    /** It was answered: off both lists. */
+    drop(fp) {
+      pending.delete(fp);
+      strangers.delete(fp);
+    },
+    /** A heard deck was asked: its address is on the dial list now, and its
+     *  row comes back as a request once the round reaches it. */
+    dropHeard(fp) {
+      strangers.delete(fp);
+    },
+    /** Say no, and stop being asked. The deck comes off the first list it is
+     *  on — its request if it asked, its heard row if it was only heard — and
+     *  onto the declined list, which is what stops the asking: a dial from it
+     *  is refused as "declined" (lan-socket.mjs), askToAccept draws no request
+     *  for it, and nothing here asks it. Not a block, though: `allow` undoes it.
+     *
+     *  A deck that asked AND was heard keeps its heard row. That is fine: the
+     *  next beacon would write that row back whatever this did, because
+     *  heardStranger records a declined deck like any other and only never
+     *  asks it, and what offers or asks from the heard list — strangerRows,
+     *  heardStranger and switched — checks the declined list first. */
+    dismiss(fp) {
+      // Whatever the row said, kept — the panel draws a declined deck by name
+      // and address, and after the delete below there is nowhere else to read
+      // them from.
+      const was = pending.get(fp) ?? strangers.get(fp) ?? null;
+      const had = pending.delete(fp) || strangers.delete(fp);
+      if (had) {
+        declined.set(fp, {
+          fp,
+          name: was?.name ?? fp,
+          addr: was?.addr ?? "",
+          port: was?.port ?? 0,
+          at: now(),
+        });
+        onChange?.();
+      }
+      return had;
+    },
+    /** Change your mind. The name comes off the declined list and the next time
+     *  that deck dials, it is a request again — which it will, on its own, so
+     *  there is nothing else to press. */
+    allow(fp) {
+      const had = declined.delete(fp);
+      if (had) onChange?.();
+      return had;
+    },
+    /** The rows status() draws for each list. */
+    pendingRows: () => [...pending.values()].map(p => ({ fp: p.fp, name: p.name, addr: p.addr, at: p.at, via: p.via ?? "lan", own: !!p.own })),
+    strangerRows,
+    declinedRows: () => [...declined.values()].map(p => ({ fp: p.fp, name: p.name, addr: p.addr, at: p.at })),
+  };
+}

package/src/server/lan-round-record.mjs

@@ -0,0 +1,45 @@
+// What the last round did with each deck, and when the whole round last
+// finished: lifted out of createEngine in lan-engine.mjs with the two
+// variables only these read and write, and the one rule read off them — is
+// anybody on the other end still deciding. The round in the engine writes a
+// record per deck it asked; the panel's rows, a deck's own `check now` and the
+// clock that picks the next round's gap (lan-round-timer.mjs) read them.
+
+/** `now` is the engine's clock. */
+export function createRoundRecord({ now }) {
+  /** What the last round did, for the panel. Not a log: one line per peer, most
+   *  recent only, because "what happened" is a question about now. */
+  const lastRound = new Map();
+  /** When the last round FINISHED, whatever it did or failed to do. The panel's
+   *  `↻` fires one on demand and the loop fires one on its own; a reader who
+   *  pressed it wants to know it happened, and a reader who did not wants to
+   *  know the list is not a photograph of an hour ago. */
+  let roundAt = null;
+
+  /**
+   * Is anybody on the other end still deciding?
+   *
+   * The exact sentence lan-call.mjs gives for "a real deck, not yet
+   * accepted", which is the one state where dialling again in a few seconds
+   * does something a minute later would not.
+   */
+  const waitingOnSomebody = () =>
+    [...lastRound.values()].some(r => r?.error === "waiting for the other deck to accept this one");
+
+  return {
+    /** What the last ask of a row did, or undefined. Keyed by the ROW the
+     *  round dialled, which for a typed address is the placeholder built from
+     *  it rather than the fingerprint that answered there. */
+    of: fp => lastRound.get(fp),
+    /** An ask of that row finished, well or not, and this is what it did. The
+     *  record is kept as it is handed over, so the same object before and
+     *  after a wait means nothing asked that row in between — see roundOne. */
+    keep(fp, record) { lastRound.set(fp, record); },
+    /** Nothing of that row is drawn any more: a dial-back taken away. */
+    drop(fp) { lastRound.delete(fp); },
+    /** A whole round finished — see roundAt. */
+    finished() { roundAt = now(); },
+    checkedAt: () => roundAt,
+    waitingOnSomebody,
+  };
+}

package/src/server/lan-round-timer.mjs

@@ -0,0 +1,62 @@
+// When the next sync round runs, lifted out of createEngine in lan-engine.mjs
+// with the one variable only it used — the timer — and the two gaps it picks
+// between. What a round does is the engine's, and the line every round waits
+// in is lan-turns.mjs's; this is only the clock that asks for the next one.
+
+/** How often a deck asks its peers what they have. A minute is far more often
+ *  than a login dies, and it is what makes the panel's list feel live rather
+ *  than something that updates when you press a button. */
+export const SYNC_MS = 60_000;
+
+/**
+ * How long to wait before dialling again while somebody is deciding.
+ *
+ * A minute is right for the steady state — two decks whose logins all work have
+ * nothing to say to each other — and it is far too long for the one moment
+ * anybody is watching: the seconds after somebody presses accept on the other
+ * machine. Reported as "it should work by itself", from a panel that had been
+ * correct for up to fifty-nine more seconds than the person in front of it.
+ *
+ * So the loop tightens while a request is outstanding and relaxes the moment it
+ * is answered — either way. A refusal is an answer, and a deck that said no is
+ * not asked every eight seconds.
+ */
+export const ASKING_MS = 8_000;
+
+/**
+ * `round` runs one whole round, the engine's own, which waits its turn in the
+ * line. `waiting` says whether a deck this one dialled is still deciding
+ * whether to accept it — the one state where asking again in a few seconds
+ * does something a minute later would not.
+ */
+export function createRoundTimer({ round, waiting }) {
+  /** The next round, while one is scheduled. */
+  let timer = null;
+
+  /**
+   * Run a round a whole SYNC_MS after the listener comes up, and another each
+   * time the last one finishes, until `ended` says the start that began the
+   * loop is over — stopped, restarted or switched off.
+   */
+  const start = ended => {
+    // A self-scheduling loop rather than one interval, because the gap
+    // between rounds is not one number: see ASKING_MS.
+    const tick = async () => {
+      try { await round(); } catch { /* a round reports itself, per peer */ }
+      if (ended()) return;
+      timer = setTimeout(() => { void tick(); }, waiting() ? ASKING_MS : SYNC_MS);
+      timer.unref?.();
+    };
+    timer = setTimeout(() => { void tick(); }, SYNC_MS);
+    timer.unref?.();
+  };
+
+  /** Call off the round scheduled next. One already running finishes, and
+   *  schedules nothing after it once its start has ended. */
+  const stop = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+
+  return { start, stop };
+}