`nx_lan_scan.nx` source

↩ module page · 284 lines · 10531 B
1// nx_lan_scan.nx -- shared sovereign LAN sweep primitive (no main).
2//
3// WHY THIS EXISTS (rule 15, DRY through shared libraries): two organs now ask
4// the SAME question -- "is host H open on port P?" -- nx_printer_ctl (printer
5// discovery/survey) and nx_iot_ctl (home-electronics inventory). If each keeps
6// its own copy of the sweep, one gets fixed and the other silently does not,
7// and the two tools then DISAGREE about the same LAN while both look healthy.
8// The attribution rule they must agree on is the reason to share, not the
9// line count.
10//
11// The implementation is lifted VERBATIM from the proven, gate-green
12// pctl_discover_scan / pctl_probe_host (nx_printer_ctl_lib), so behaviour is
13// identical BY CONSTRUCTION rather than by re-derivation.
14//
15// SCALE LAW (learned the hard way, banked in the iot-printer-fabric memory):
16// any organ that fans out network I/O over MCP must bound total latency to the
17// tools-daemon fork-capture window, or the call returns status=0 with no output
18// while working fine on the CLI. Three rules, all encoded below:
19//   1. BATCHED   -- fire all 254 non-blocking connects first, then poll.
20//   2. POLL-UNTIL-RESOLVED -- a single poll() returns as soon as ANY fd is
21//      ready (the ~250 instantly-refused hosts) BEFORE a real host finishes its
22//      handshake, so it finds NOTHING. Mark each fd done as its revents fire
23//      (write 0xff over the pollfd fd bytes so poll ignores it next round) and
24//      keep polling the still-connecting ones.
25//   3. TIGHT BUDGET -- responsive devices answer in <50ms; unreachable hosts
26//      must not be waited on.
27//
28// Open iff POLLOUT && !POLLERR && !POLLHUP.
29//
30// license_tier: ORIGINAL   No hw writes (Rule 26).
31import "nx_syscalls.nx"
32import "nx_connect.nx"   // bounded connect: a raw sys_connect hangs ~127s on a black-holed host
33const LSCAN_MAGIC_65535: i64 = 65535
34
35const LSCAN_SOCK_NONBLOCK: i64 = 2048   // SOCK_NONBLOCK
36const LSCAN_POLLOUT:       i64 = 4
37const LSCAN_POLLERR:       i64 = 8
38const LSCAN_POLLHUP:       i64 = 16
39const LSCAN_HOSTS:         i64 = 254    // .1 .. .254 of a /24
40const LSCAN_ROUNDS:        i64 = 12     // poll-until-resolved rounds
41const LSCAN_MIN_PER_MS:    i64 = 5      // floor on the per-round poll slice
42
43// THE SHARED SWEEP BUDGET (rule 11: this is exactly the kind of number that
44// must not be re-invented per call site).
45//
46// Sharing lscan_sweep alone did NOT make the organs agree -- MEASURED 2026-07-25:
47// nx_printer_ctl swept at 80ms/port and reported 6 hosts on 192.168.8, while
48// nx_iot_ctl swept at 60ms/port and reported 4 of the same 6. Hosts near the
49// budget (192.168.8.158, .205) flip in and out. The duplicated CODE was only
50// half the problem; the duplicated NUMBER is the other half, because a device's
51// visibility is a function of it. One constant, both organs, same answer.
52//
53// Bounded by the scale law: total = budget x TCP-port-count must stay inside
54// the tools-daemon fork-capture window (12 rows x 120ms ~= 1.4s worst case).
55const LSCAN_BUDGET_MS:     i64 = 120
56
57// ---- dotted /24 prefix parse: "192.168.8" -> (192<<16)|(168<<8)|8 ----
58// Returns -1 on anything that is not exactly three 0..255 octets.
59func lscan_parse_prefix(s: *u8) -> i64 {
  var val: i64 = 0
  var ndig: i64 = 0
  var oct: i64 = 0
  var base: i64 = 0
  var i: i64 = 0
  var done: i64 = 0
  while done == 0 {
      let c: i64 = s[i] & 0xff
      if c == 0 {
          done = 1
      } else {
          if c == 46 {
              if ndig == 0 { return 0 - 1 }
              if val > 255 { return 0 - 1 }
              base = (base << 8) | val
              oct = oct + 1
              val = 0
              ndig = 0
              i = i + 1
          } else {
              if c < 48 { return 0 - 1 }
              if c > 57 { return 0 - 1 }
              val = val * 10 + (c - 48)
              ndig = ndig + 1
              i = i + 1
          }
      }
  }
  if ndig == 0 { return 0 - 1 }
  if val > 255 { return 0 - 1 }
  base = (base << 8) | val
  oct = oct + 1
  if oct != 3 { return 0 - 1 }
  return base
94}
95
96// ---- dotted IPv4 parse: "192.168.1.42" -> packed ---------------------
97// Returns -1 on anything that is not exactly four 0..255 octets.
98func lscan_parse_ip(s: *u8) -> i64 {
  var val: i64 = 0
  var ndig: i64 = 0
  var oct: i64 = 0
  var packed: i64 = 0
  var i: i64 = 0
  var done: i64 = 0
  while done == 0 {
      let c: i64 = s[i] & 0xff
      if c == 0 {
          done = 1
      } else {
          if c == 46 {
              if ndig == 0 { return 0 - 1 }
              if val > 255 { return 0 - 1 }
              packed = (packed << 8) | val
              oct = oct + 1
              val = 0
              ndig = 0
              i = i + 1
          } else {
              if c < 48 { return 0 - 1 }
              if c > 57 { return 0 - 1 }
              val = val * 10 + (c - 48)
              ndig = ndig + 1
              i = i + 1
          }
      }
  }
  if ndig == 0 { return 0 - 1 }
  if val > 255 { return 0 - 1 }
  packed = (packed << 8) | val
  oct = oct + 1
  if oct != 4 { return 0 - 1 }
  return packed
133}
134
135// ---- port parse: decimal 1..65535, else -1 ---------------------------
136func lscan_parse_port(s: *u8) -> i64 {
  var v: i64 = 0
  var nd: i64 = 0
  var i: i64 = 0
  var done: i64 = 0
  while done == 0 {
      let c: i64 = s[i] & 0xff
      if c == 0 { done = 1 }
      else {
          if c < 48 { return 0 - 1 }
          if c > 57 { return 0 - 1 }
          v = v * 10 + (c - 48)
          nd = nd + 1
          if v > LSCAN_MAGIC_65535 { return 0 - 1 }
          i = i + 1
      }
  }
  if nd == 0 { return 0 - 1 }
  if v < 1 { return 0 - 1 }
  return v
156}
157
158// ---- fill a sockaddr_in (16 bytes) ----------------------------------
159func lscan_fill_sockaddr(addr: *u8, ipv4: i64, port: i64) -> i64 {
  addr[0] = 2 as u8
  addr[1] = 0 as u8
  addr[2] = ((port >> 8) & 0xff) as u8
  addr[3] = (port & 0xff) as u8
  addr[4] = ((ipv4 >> 24) & 0xff) as u8
  addr[5] = ((ipv4 >> 16) & 0xff) as u8
  addr[6] = ((ipv4 >> 8) & 0xff) as u8
  addr[7] = (ipv4 & 0xff) as u8
  var z: i64 = 8
  while z < 16 { addr[z] = 0 as u8; z = z + 1 }
  return 16
171}
172
173// ---- single-host non-blocking TCP connect probe ---------------------
174// 1 if <ipv4>:<port> accepts within timeout_ms, else 0. Never blocks longer
175// than timeout_ms; closes the fd on every path.
176func lscan_probe_host(ipv4: i64, port: i64, timeout_ms: i64) -> i64 {
  let fd: i64 = sys_socket(2, 1 | LSCAN_SOCK_NONBLOCK, 0)
  if fd < 0 { return 0 }
  let addr: *u8 = sys_mmap(16)
  lscan_fill_sockaddr(addr, ipv4, port)
  let rc: i64 = nx_connect_bounded(fd, addr, 16, NX_CONN_DEFAULT_MS)
  var open: i64 = 0
  if rc == 0 {
      open = 1
  } else {
      let pf: *u8 = sys_mmap(8)
      pf[0] = (fd & 0xff) as u8
      pf[1] = ((fd >> 8) & 0xff) as u8
      pf[2] = ((fd >> 16) & 0xff) as u8
      pf[3] = ((fd >> 24) & 0xff) as u8
      pf[4] = LSCAN_POLLOUT as u8
      pf[5] = 0 as u8
      pf[6] = 0 as u8
      pf[7] = 0 as u8
      let pr: i64 = sys_poll(pf, 1, timeout_ms)
      if pr > 0 {
          let rev: i64 = (pf[6] as i64) & 0xff
          if (rev & LSCAN_POLLOUT) != 0 {
              if (rev & LSCAN_POLLERR) == 0 {
                  if (rev & LSCAN_POLLHUP) == 0 { open = 1 }
              }
          }
      }
  }
  sys_close(fd)
  return open
207}
208
209// ---- /24 sweep -------------------------------------------------------
210// Scan base24.1 .. base24.254 on <port>; fill out_ips with packed IPv4 of every
211// host that accepted; return the count (capped at max).
212func lscan_sweep(base24: i64, port: i64, timeout_ms: i64, out_ips: *i64, max: i64) -> i64 {
  let pfds: *u8  = sys_mmap(LSCAN_HOSTS * 8)
  let hmap: *i64 = sys_mmap(LSCAN_HOSTS * 8) as *i64
  let fds:  *i64 = sys_mmap(LSCAN_HOSTS * 8) as *i64
  let addr: *u8  = sys_mmap(16)
  var nact: i64 = 0
  var h: i64 = 1
  while h <= LSCAN_HOSTS {
      let fd: i64 = sys_socket(2, 1 | LSCAN_SOCK_NONBLOCK, 0)
      if fd >= 0 {
          let ipv4: i64 = (base24 << 8) | h
          lscan_fill_sockaddr(addr, ipv4, port)
          nx_connect_bounded(fd, addr, 16, NX_CONN_DEFAULT_MS)
          let po: i64 = nact * 8
          pfds[po + 0] = (fd & 0xff) as u8
          pfds[po + 1] = ((fd >> 8) & 0xff) as u8
          pfds[po + 2] = ((fd >> 16) & 0xff) as u8
          pfds[po + 3] = ((fd >> 24) & 0xff) as u8
          pfds[po + 4] = LSCAN_POLLOUT as u8
          pfds[po + 5] = 0 as u8
          pfds[po + 6] = 0 as u8
          pfds[po + 7] = 0 as u8
          hmap[nact] = h
          fds[nact] = fd
          nact = nact + 1
      }
      h = h + 1
  }
  let done: *i64 = sys_mmap(LSCAN_HOSTS * 8) as *i64
  var d0: i64 = 0
  while d0 < nact { done[d0] = 0; d0 = d0 + 1 }
  var cnt: i64 = 0
  var remaining: i64 = nact
  var per: i64 = timeout_ms / LSCAN_ROUNDS
  if per < LSCAN_MIN_PER_MS { per = LSCAN_MIN_PER_MS }
  var round: i64 = 0
  while round < LSCAN_ROUNDS {
      if remaining <= 0 {
          round = LSCAN_ROUNDS
      } else {
          sys_poll(pfds, nact, per)
          var i: i64 = 0
          while i < nact {
              if done[i] == 0 {
                  let rev: i64 = (pfds[i * 8 + 6] as i64) & 0xff
                  if rev != 0 {
                      done[i] = 1
                      remaining = remaining - 1
                      pfds[i * 8 + 0] = 0xff as u8
                      pfds[i * 8 + 1] = 0xff as u8
                      pfds[i * 8 + 2] = 0xff as u8
                      pfds[i * 8 + 3] = 0xff as u8
                      if (rev & LSCAN_POLLOUT) != 0 {
                          if (rev & LSCAN_POLLERR) == 0 {
                              if (rev & LSCAN_POLLHUP) == 0 {
                                  if cnt < max {
                                      out_ips[cnt] = (base24 << 8) | hmap[i]
                                      cnt = cnt + 1
                                  }
                              }
                          }
                      }
                  }
              }
              i = i + 1
          }
          round = round + 1
      }
  }
  var c: i64 = 0
  while c < nact { sys_close(fds[c]); c = c + 1 }
  return cnt
284}
nx_lan_scan.nx source

`nx_lan_scan.nx` source
