code wiki / _hdl_build / nx_printer_ctl_lib.nx
`nx_printer_ctl_lib.nx` source

↩ module page · 836 lines · 36013 B
1// nx_printer_ctl_lib.nx -- sovereign 3D-printer / home-IoT control LIB (no main).
2//
3// The reusable core behind nx_printer_ctl (CLI organ) + nx_printer_ctl_gate.
4// Composes the shipped Moonraker primitives (nx_moonraker_client request
5// builders + nx_moonraker_io arbitrary-IPv4 roundtrip) into a cap-gated,
6// JSON-emitting device-control surface that the sovereign edge reaches over
7// the LAN.
8//
9// ARCHITECTURE (the operator's browser->edge->mTLS-home->printer design,
10// realized sovereignly): the sovereign edge (sites.elf :8443) already does
11// OPAQUE cap-token auth + reverse-proxy. This organ is the "home gateway"
12// leg -- BUT the NAS that runs the edge is ITSELF on the home LAN, so the
13// organ reaches the printer at <lan-ip>:7125 directly. The printer never
14// sees the WAN; only the cap-gated organ ever touches it => "zero external
15// exposure" holds BY CONSTRUCTION, no Node/nginx/WAN-mTLS-tunnel required.
16//
17// NEVER-BRICK (CLAUDE rule 26, ABSOLUTE): every control verb maps to a FIXED
18// allowlisted Moonraker endpoint (info / emergency_stop / print pause|resume
19// |cancel). There is NO raw-G-code passthrough, so no path can ever carry a
20// firmware-flash / EEPROM-write G-code (M500/M502/etc.). emergency_stop is a
21// Klipper RUNTIME MCU halt (recovered by a soft FIRMWARE_RESTART, RAM-only) --
22// it writes NO persistent hardware state. The safe-endpoint allowlist is
23// proven mechanically by nx_printer_ctl_gate (a control path outside the
24// allowlist => gate RED).
25//
26// license_tier: ORIGINAL   No hw writes (Rule 26).
27import "nx_syscalls.nx"
28import "nx_moonraker_client.nx"
29import "nx_moonraker_io.nx"
30import "nx_lan_scan.nx"
31
32const PCTL_SCRATCH:  i64 = 8192
33const PCTL_RESP:     i64 = 16384
34const PCTL_OUT:      i64 = 32768
35
36// verb ids
37const PCTL_V_INFO:   i64 = 1
38const PCTL_V_ESTOP:  i64 = 2
39const PCTL_V_PAUSE:  i64 = 3
40const PCTL_V_RESUME: i64 = 4
41const PCTL_V_CANCEL: i64 = 5
42const PCTL_V_CONTRACT: i64 = 6
43const PCTL_V_STATUS: i64 = 7
44const PCTL_V_READY:  i64 = 8
45const PCTL_V_DISCOVER: i64 = 9
46const PCTL_V_SURVEY: i64 = 10
47const PCTL_V_MONITOR: i64 = 11
48const PCTL_V_FILES: i64 = 12
49const PCTL_V_PROGRESS: i64 = 13
50const PCTL_V_PRINTSTART: i64 = 14
51const PCTL_V_UPLOAD: i64 = 15
52const PCTL_V_BAD:    i64 = 0
53const PCTL_TEMP_NONE: i64 = 0 - 32768
54const PCTL_SOCK_NONBLOCK: i64 = 2048   // SOCK_NONBLOCK
55const PCTL_POLLOUT: i64 = 4
56const PCTL_POLLERR: i64 = 8
57const PCTL_POLLHUP: i64 = 16
58// home-device survey port profile (curated; each port scanned across the /24).
59// Port index -> bit in the per-host mask; classification derives from the mask.
60const PCTL_SURVEY_NPORTS: i64 = 4
61
62// ===== small utils =================================================
63func pctl_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
64func pctl_streq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 }
  if b[i] != (0 as u8) { return 0 }
  return 1
69}
70func pctl_cat(d: *u8, o: i64, s: *u8) -> i64 { var i: i64 = 0; while s[i] != (0 as u8) { d[o] = s[i]; o = o + 1; i = i + 1 } return o }
71func pctl_catn(d: *u8, o: i64, v: i64) -> i64 {
  let t: *u8 = sys_mmap(28)
  var m: i64 = v
  if m < 0 { d[o] = 45 as u8; o = o + 1; m = 0 - m }
  var k: i64 = 0
  if m == 0 { t[0] = 48 as u8; k = 1 }
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  var i: i64 = 0
  while i < k { d[o] = t[k-1-i]; o = o + 1; i = i + 1 }
  return o
81}
82// escape body bytes [s,e) into a JSON string value: " -> ', \ -> /, ctrl -> space
83func pctl_cat_esc(d: *u8, o: i64, q: *u8, s: i64, e: i64) -> i64 {
  var i: i64 = s
  while i < e {
      var c: i64 = q[i] as i64
      c = c & 0xff
      if c == 34 { c = 39 }
      if c == 92 { c = 47 }
      if c < 32 { c = 32 }
      d[o] = c as u8
      o = o + 1
      i = i + 1
  }
  return o
96}
97
98// ===== dotted-IPv4 parse -> packed i64 (matches nx_mr_pack_ipv4) ====
99// "192.168.1.42" -> (192<<24)|(168<<16)|(1<<8)|42 ; returns -1 on malformed.
100func pctl_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
135}
136
137// parse a positive decimal string -> value, or -1 on any non-digit / empty
138func pctl_parse_port(s: *u8) -> i64 {
  var v: i64 = 0
  var i: i64 = 0
  if s[0] == (0 as u8) { return 0 - 1 }
  while s[i] != (0 as u8) {
      let c: i64 = s[i] & 0xff
      if c < 48 { return 0 - 1 }
      if c > 57 { return 0 - 1 }
      v = v * 10 + (c - 48)
      i = i + 1
  }
  if v < 1 { return 0 - 1 }
  if v > 65535 { return 0 - 1 }
  return v
152}
153
154// build the "a.b.c.d:port" Host header value into host buf; returns length
155func pctl_build_host(ip: *u8, port: i64, host: *u8) -> i64 {
  var o: i64 = 0
  o = pctl_cat(host, o, ip)
  host[o] = 58 as u8
  o = o + 1
  o = pctl_catn(host, o, port)
  host[o] = 0 as u8
  return o
163}
164
165// ===== verb name -> id + safe-endpoint allowlist (NEVER-BRICK) =====
166// Returns the FIXED Moonraker path for a control verb. Any verb not in this
167// map returns NULL -- there is no way to reach an arbitrary path, so no
168// firmware-write G-code can ever be routed. This IS the never-brick guarantee.
169func pctl_verb_id(v: *u8) -> i64 {
  if pctl_streq(v, "info" as *u8) == 1 { return PCTL_V_INFO }
  if pctl_streq(v, "estop" as *u8) == 1 { return PCTL_V_ESTOP }
  if pctl_streq(v, "pause" as *u8) == 1 { return PCTL_V_PAUSE }
  if pctl_streq(v, "resume" as *u8) == 1 { return PCTL_V_RESUME }
  if pctl_streq(v, "cancel" as *u8) == 1 { return PCTL_V_CANCEL }
  if pctl_streq(v, "contract" as *u8) == 1 { return PCTL_V_CONTRACT }
  if pctl_streq(v, "status" as *u8) == 1 { return PCTL_V_STATUS }
  if pctl_streq(v, "ready" as *u8) == 1 { return PCTL_V_READY }
  if pctl_streq(v, "discover" as *u8) == 1 { return PCTL_V_DISCOVER }
  if pctl_streq(v, "survey" as *u8) == 1 { return PCTL_V_SURVEY }
  if pctl_streq(v, "monitor" as *u8) == 1 { return PCTL_V_MONITOR }
  if pctl_streq(v, "files" as *u8) == 1 { return PCTL_V_FILES }
  if pctl_streq(v, "progress" as *u8) == 1 { return PCTL_V_PROGRESS }
  if pctl_streq(v, "printstart" as *u8) == 1 { return PCTL_V_PRINTSTART }
  if pctl_streq(v, "upload" as *u8) == 1 { return PCTL_V_UPLOAD }
  return PCTL_V_BAD
186}
187func pctl_verb_is_get(id: i64) -> i64 {
  if id == PCTL_V_INFO { return 1 }
  if id == PCTL_V_STATUS { return 1 }
  if id == PCTL_V_READY { return 1 }
  if id == PCTL_V_FILES { return 1 }
  if id == PCTL_V_PROGRESS { return 1 }
  return 0
194}
195// the ONLY paths this organ can ever emit (safe control surface allowlist)
196func pctl_verb_path(id: i64) -> *u8 {
  if id == PCTL_V_INFO   { return "/printer/info" as *u8 }
  if id == PCTL_V_ESTOP  { return "/printer/emergency_stop" as *u8 }
  if id == PCTL_V_PAUSE  { return "/printer/print/pause" as *u8 }
  if id == PCTL_V_RESUME { return "/printer/print/resume" as *u8 }
  if id == PCTL_V_CANCEL { return "/printer/print/cancel" as *u8 }
  if id == PCTL_V_STATUS { return "/printer/objects/query?extruder=temperature,target&heater_bed=temperature,target" as *u8 }
  if id == PCTL_V_READY  { return "/printer/info" as *u8 }
  if id == PCTL_V_FILES  { return "/server/files/list" as *u8 }
  if id == PCTL_V_PROGRESS { return "/printer/objects/query?print_stats&virtual_sdcard&display_status" as *u8 }
  if id == PCTL_V_PRINTSTART { return "/printer/print/start" as *u8 }
  return "\x00" as *u8
208}
209func pctl_verb_name(id: i64) -> *u8 {
  if id == PCTL_V_INFO   { return "info" as *u8 }
  if id == PCTL_V_ESTOP  { return "estop" as *u8 }
  if id == PCTL_V_PAUSE  { return "pause" as *u8 }
  if id == PCTL_V_RESUME { return "resume" as *u8 }
  if id == PCTL_V_CANCEL { return "cancel" as *u8 }
  if id == PCTL_V_CONTRACT { return "contract" as *u8 }
  if id == PCTL_V_STATUS { return "status" as *u8 }
  if id == PCTL_V_READY  { return "ready" as *u8 }
  if id == PCTL_V_DISCOVER { return "discover" as *u8 }
  if id == PCTL_V_SURVEY { return "survey" as *u8 }
  if id == PCTL_V_MONITOR { return "monitor" as *u8 }
  if id == PCTL_V_FILES { return "files" as *u8 }
  if id == PCTL_V_PROGRESS { return "progress" as *u8 }
  if id == PCTL_V_PRINTSTART { return "printstart" as *u8 }
  if id == PCTL_V_UPLOAD { return "upload" as *u8 }
  return "bad" as *u8
226}
227
228// ===== response body-start (after "\r\n\r\n") ======================
229func pctl_body_start(resp: *u8, n: i64) -> i64 {
  var i: i64 = 0
  while i + 3 < n {
      if resp[i] == (13 as u8) { if resp[i+1] == (10 as u8) { if resp[i+2] == (13 as u8) { if resp[i+3] == (10 as u8) { return i + 4 } } } }
      i = i + 1
  }
  return n
236}
237
238// ===== the composed network call (SAME path CLI + gate both use) ===
239// Performs the verb's Moonraker roundtrip against ip:port. Returns the HTTP
240// status code (>=100), or a negative nx_moonraker_io verdict on transport
241// failure. Fills resp[0..out] with the raw response; caller reads n via *rn.
242func pctl_call(id: i64, ipv4: i64, port: i64,
             host: *u8, host_len: i64,
             api_key: *u8, api_key_len: i64,
             scratch: *u8, resp: *u8, rn: *i64) -> i64 {
  let path: *u8 = pctl_verb_path(id)
  let plen: i64 = pctl_slen(path)
  var n: i64 = 0
  if pctl_verb_is_get(id) == 1 {
      n = nx_mr_get_ipv4(ipv4, port, host, host_len, path, plen, api_key, api_key_len, scratch, PCTL_SCRATCH, resp, PCTL_RESP)
  } else {
      let empty: *u8 = "\x00" as *u8
      n = nx_mr_post_ipv4(ipv4, port, host, host_len, path, plen, empty, 0, api_key, api_key_len, scratch, PCTL_SCRATCH, resp, PCTL_RESP)
  }
  rn[0] = n
  if n <= 0 { return n }
  let st: i64 = nx_mr_parse_status(resp, n)
  return st
259}
260
261// ===== JSON result emit for a network verb =========================
262// {"verb":"..","target":"ip:port","http_status":N,"result":"..","body_excerpt":".."}
263func pctl_emit_result(out: *u8, id: i64, host: *u8, status: i64, resp: *u8, n: i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"" as *u8)
  o = pctl_cat(out, o, pctl_verb_name(id))
  o = pctl_cat(out, o, "\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  o = pctl_cat(out, o, ",\"result\":\"" as *u8)
  if status >= 200 { if status < 300 { o = pctl_cat(out, o, "OK" as *u8) } }
  if status >= 300 { o = pctl_cat(out, o, "HTTP_ERROR" as *u8) }
  if status < 200 { if status >= 100 { o = pctl_cat(out, o, "HTTP_INFO" as *u8) } }
  if status <= 0 { o = pctl_cat(out, o, "NETWORK_ERR" as *u8) }
  if status > 0 { if status < 100 { o = pctl_cat(out, o, "BAD_RESPONSE" as *u8) } }
  o = pctl_cat(out, o, "\",\"body_excerpt\":\"" as *u8)
  if n > 0 {
      let bs: i64 = pctl_body_start(resp, n)
      var be: i64 = bs + 240
      if be > n { be = n }
      o = pctl_cat_esc(out, o, resp, bs, be)
  }
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
286}
287
288// ===== lean telemetry parse (mirrors nx_moonraker_telemetry_parse; self-contained =====
289// so the build closure stays minimal for a robust NAS build) ========================
290func pctl_find(body: *u8, n: i64, start: i64, needle: *u8) -> i64 {
  var nl: i64 = 0
  while needle[nl] != (0 as u8) { nl = nl + 1 }
  if nl == 0 { return start }
  if start < 0 { return 0 - 1 }
  var i: i64 = start
  let stop: i64 = n - nl
  while i <= stop {
      var j: i64 = 0
      var m: i64 = 1
      while j < nl {
          if body[i + j] != needle[j] { m = 0; j = nl } else { j = j + 1 }
      }
      if m == 1 { return i }
      i = i + 1
  }
  return 0 - 1
307}
308// skip ws, optional '-', digits; truncate at first non-digit; PCTL_TEMP_NONE if none
309func pctl_parse_int_deg(body: *u8, off: i64, n: i64) -> i64 {
  var q: i64 = off
  var sk: i64 = 1
  while sk == 1 {
      if q >= n { sk = 0 } else {
          let c: i64 = body[q] & 0xff
          if c == 32 { q = q + 1 } else {
              if c == 9 { q = q + 1 } else {
                  if c == 10 { q = q + 1 } else {
                      if c == 13 { q = q + 1 } else { sk = 0 }
                  }
              }
          }
      }
  }
  if q >= n { return PCTL_TEMP_NONE }
  var neg: i64 = 0
  if body[q] == (45 as u8) { neg = 1; q = q + 1 }
  var have: i64 = 0
  var v: i64 = 0
  var rd: i64 = 1
  while rd == 1 {
      if q >= n { rd = 0 } else {
          let d: i64 = body[q] & 0xff
          if d < 48 { rd = 0 } else {
              if d > 57 { rd = 0 } else {
                  v = v * 10 + (d - 48)
                  have = 1
                  q = q + 1
              }
          }
      }
  }
  if have == 0 { return PCTL_TEMP_NONE }
  if neg == 1 { return 0 - v }
  return v
345}
346// find object key (e.g. "\"extruder\":") then field (e.g. "\"temperature\":") after it -> int
347func pctl_temp_in(body: *u8, n: i64, objkey: *u8, field: *u8) -> i64 {
  let os: i64 = pctl_find(body, n, 0, objkey)
  if os < 0 { return PCTL_TEMP_NONE }
  let fs: i64 = pctl_find(body, n, os, field)
  if fs < 0 { return PCTL_TEMP_NONE }
  let fl: i64 = pctl_slen(field)
  return pctl_parse_int_deg(body, fs + fl, n)
354}
355func pctl_cat_num_or_null(d: *u8, o: i64, v: i64) -> i64 {
  if v == PCTL_TEMP_NONE { return pctl_cat(d, o, "null" as *u8) }
  return pctl_catn(d, o, v)
358}
359func pctl_ready_flag(body: *u8, n: i64) -> i64 {
  if pctl_find(body, n, 0, "\"state\":\"ready\"" as *u8) >= 0 { return 1 }
  if pctl_find(body, n, 0, "\"state\": \"ready\"" as *u8) >= 0 { return 1 }
  return 0
363}
364func pctl_state_of(body: *u8, n: i64, rdy: i64) -> *u8 {
  if rdy == 1 { return "ready" as *u8 }
  if pctl_find(body, n, 0, "shutdown" as *u8) >= 0 { return "shutdown" as *u8 }
  if pctl_find(body, n, 0, "error" as *u8) >= 0 { return "error" as *u8 }
  if pctl_find(body, n, 0, "startup" as *u8) >= 0 { return "startup" as *u8 }
  return "unknown" as *u8
370}
371func pctl_cat_netresult(d: *u8, o: i64, status: i64) -> i64 {
  if status <= 0 { return pctl_cat(d, o, "NETWORK_ERR" as *u8) }
  if status >= 200 { if status < 300 { return pctl_cat(d, o, "OK" as *u8) } }
  return pctl_cat(d, o, "HTTP_ERROR" as *u8)
375}
376// ===== status verb: parsed hotend/bed temps + targets ==============
377func pctl_emit_status(out: *u8, host: *u8, status: i64, resp: *u8, n: i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"status\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  var ha: i64 = PCTL_TEMP_NONE
  var ht: i64 = PCTL_TEMP_NONE
  var ba: i64 = PCTL_TEMP_NONE
  var bt: i64 = PCTL_TEMP_NONE
  if n > 0 { if status >= 200 { if status < 300 {
      let bs: i64 = pctl_body_start(resp, n)
      let bp: *u8 = ((resp as i64) + bs) as *u8
      let bn: i64 = n - bs
      ha = pctl_temp_in(bp, bn, "\"extruder\":" as *u8, "\"temperature\":" as *u8)
      ht = pctl_temp_in(bp, bn, "\"extruder\":" as *u8, "\"target\":" as *u8)
      ba = pctl_temp_in(bp, bn, "\"heater_bed\":" as *u8, "\"temperature\":" as *u8)
      bt = pctl_temp_in(bp, bn, "\"heater_bed\":" as *u8, "\"target\":" as *u8)
  } } }
  o = pctl_cat(out, o, ",\"hotend\":{\"actual_c\":" as *u8)
  o = pctl_cat_num_or_null(out, o, ha)
  o = pctl_cat(out, o, ",\"target_c\":" as *u8)
  o = pctl_cat_num_or_null(out, o, ht)
  o = pctl_cat(out, o, "},\"bed\":{\"actual_c\":" as *u8)
  o = pctl_cat_num_or_null(out, o, ba)
  o = pctl_cat(out, o, ",\"target_c\":" as *u8)
  o = pctl_cat_num_or_null(out, o, bt)
  o = pctl_cat(out, o, "},\"result\":\"" as *u8)
  o = pctl_cat_netresult(out, o, status)
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
408}
409// ===== ready verb: preflight klippy state ==========================
410func pctl_emit_ready(out: *u8, host: *u8, status: i64, resp: *u8, n: i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"ready\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  var rdy: i64 = 0
  var state: *u8 = "unknown" as *u8
  if n > 0 { if status >= 200 { if status < 300 {
      let bs: i64 = pctl_body_start(resp, n)
      let bp: *u8 = ((resp as i64) + bs) as *u8
      let bn: i64 = n - bs
      rdy = pctl_ready_flag(bp, bn)
      state = pctl_state_of(bp, bn, rdy)
  } } }
  o = pctl_cat(out, o, ",\"ready\":" as *u8)
  o = pctl_catn(out, o, rdy)
  o = pctl_cat(out, o, ",\"klippy_state\":\"" as *u8)
  o = pctl_cat(out, o, state)
  o = pctl_cat(out, o, "\",\"result\":\"" as *u8)
  o = pctl_cat_netresult(out, o, status)
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
433}
434
435// ===== discover: sovereign LAN sweep for Moonraker printers ========
436//
437// DRY (rule 15): the sweep itself now lives in nx_lan_scan and is SHARED with
438// nx_iot_ctl. It moved because the two organs must AGREE about the same LAN --
439// with two copies, one gets a fix and the other silently does not, and they
440// then answer "is host H open on port P" differently while both look healthy.
441// That is not hypothetical: on 2026-07-25 the printer survey reported 5 hosts
442// on 192.168.8 while the new IoT scan reported 6, minutes apart.
443//
444// These remain as thin wrappers so every existing caller and the 14-tooth
445// nx_printer_ctl_gate keep working unchanged (rule 19: never break a contract).
446func pctl_parse_prefix(s: *u8) -> i64 { return lscan_parse_prefix(s) }
447// non-blocking TCP connect probe: 1 if <ipv4>:<port> accepts, else 0
448func pctl_probe_host(ipv4: i64, port: i64, timeout_ms: i64) -> i64 {
  return lscan_probe_host(ipv4, port, timeout_ms)
450}
451// scan base24.1 .. base24.254 on <port>; fill out_ips with packed found; return count.
452// BATCHED (scale-law): fire all 254 non-blocking connects, then ONE poll over the whole
453// set -> O(one timeout) not O(N x timeout), so a full /24 sweep fits an MCP call window.
454func pctl_discover_scan(base24: i64, port: i64, timeout_ms: i64, out_ips: *i64, max: i64) -> i64 {
  return lscan_sweep(base24, port, timeout_ms, out_ips, max)
456}
457func pctl_cat_ip(d: *u8, o: i64, ipv4: i64) -> i64 {
  o = pctl_catn(d, o, (ipv4 >> 24) & 0xff)
  d[o] = 46 as u8
  o = o + 1
  o = pctl_catn(d, o, (ipv4 >> 16) & 0xff)
  d[o] = 46 as u8
  o = o + 1
  o = pctl_catn(d, o, (ipv4 >> 8) & 0xff)
  d[o] = 46 as u8
  o = o + 1
  o = pctl_catn(d, o, ipv4 & 0xff)
  return o
469}
470func pctl_emit_discover(out: *u8, prefix: *u8, port: i64, ips: *i64, count: i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"discover\",\"subnet\":\"" as *u8)
  o = pctl_cat(out, o, prefix)
  o = pctl_cat(out, o, "\",\"port\":" as *u8)
  o = pctl_catn(out, o, port)
  o = pctl_cat(out, o, ",\"found\":[" as *u8)
  var i: i64 = 0
  while i < count {
      if i > 0 { o = pctl_cat(out, o, "," as *u8) }
      o = pctl_cat(out, o, "\"" as *u8)
      o = pctl_cat_ip(out, o, ips[i])
      o = pctl_cat(out, o, "\"" as *u8)
      i = i + 1
  }
  o = pctl_cat(out, o, "],\"count\":" as *u8)
  o = pctl_catn(out, o, count)
  o = pctl_cat(out, o, "}\n" as *u8)
  return o
489}
490
491// ===== survey: home-device inventory (multi-port classify) =========
492// bit0=7125 Moonraker, bit1=10088 Fluidd, bit2=80 HTTP, bit3=443 HTTPS
493func pctl_survey_port(pi: i64) -> i64 {
  if pi == 0 { return 7125 }
  if pi == 1 { return 10088 }
  if pi == 2 { return 80 }
  if pi == 3 { return 443 }
  return 0
499}
500// scan each survey port across the /24, OR-ing a per-host port-mask.
501// Reuses the proven batched poll-until-resolved scan (each port = <=254 sockets, fd-safe).
502func pctl_survey_scan(base24: i64, budget_per_port: i64, mask: *i64) -> i64 {
  let ips: *i64 = sys_mmap(254 * 8) as *i64
  var pi: i64 = 0
  while pi < PCTL_SURVEY_NPORTS {
      let port: i64 = pctl_survey_port(pi)
      let cnt: i64 = pctl_discover_scan(base24, port, budget_per_port, ips, 254)
      var j: i64 = 0
      while j < cnt {
          let h: i64 = ips[j] & 0xff
          let m: i64 = mask[h]
          mask[h] = m | (1 << pi)
          j = j + 1
      }
      pi = pi + 1
  }
  return 0
518}
519func pctl_survey_kind(bits: i64) -> *u8 {
  if (bits & 1) != 0 { return "3d-printer" as *u8 }
  if (bits & 2) != 0 { return "3d-printer" as *u8 }
  if (bits & 4) != 0 { return "web-device" as *u8 }
  if (bits & 8) != 0 { return "web-device" as *u8 }
  return "device" as *u8
525}
526func pctl_emit_survey(out: *u8, prefix: *u8, base24: i64, mask: *i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"survey\",\"subnet\":\"" as *u8)
  o = pctl_cat(out, o, prefix)
  o = pctl_cat(out, o, "\",\"devices\":[" as *u8)
  var count: i64 = 0
  var h: i64 = 1
  while h <= 254 {
      let bits: i64 = mask[h]
      if bits != 0 {
          if count > 0 { o = pctl_cat(out, o, "," as *u8) }
          o = pctl_cat(out, o, "{\"ip\":\"" as *u8)
          o = pctl_cat_ip(out, o, (base24 << 8) | h)
          o = pctl_cat(out, o, "\",\"kind\":\"" as *u8)
          o = pctl_cat(out, o, pctl_survey_kind(bits))
          o = pctl_cat(out, o, "\",\"ports\":[" as *u8)
          var pi: i64 = 0
          var np: i64 = 0
          while pi < PCTL_SURVEY_NPORTS {
              if (bits & (1 << pi)) != 0 {
                  if np > 0 { o = pctl_cat(out, o, "," as *u8) }
                  o = pctl_catn(out, o, pctl_survey_port(pi))
                  np = np + 1
              }
              pi = pi + 1
          }
          o = pctl_cat(out, o, "]}" as *u8)
          count = count + 1
      }
      h = h + 1
  }
  o = pctl_cat(out, o, "],\"count\":" as *u8)
  o = pctl_catn(out, o, count)
  o = pctl_cat(out, o, "}\n" as *u8)
  return o
561}
562
563// ===== monitor: ONE sovereign call = the whole dashboard JSON =======
564// Replaces the shell beat's grep/date logic (no coreutils). discover -> if online
565// status+ready -> survey -> epoch (sovereign clock syscall) -> aggregated JSON.
566func pctl_ip_to_str(pip: i64, buf: *u8) -> i64 {
  var o: i64 = 0
  o = pctl_catn(buf, o, (pip >> 24) & 0xff)
  buf[o] = 46 as u8
  o = o + 1
  o = pctl_catn(buf, o, (pip >> 16) & 0xff)
  buf[o] = 46 as u8
  o = o + 1
  o = pctl_catn(buf, o, (pip >> 8) & 0xff)
  buf[o] = 46 as u8
  o = o + 1
  o = pctl_catn(buf, o, pip & 0xff)
  buf[o] = 0 as u8
  return o
580}
581func pctl_build_monitor(out: *u8, subnet: *u8, base24: i64) -> i64 {
  let ts: *i64 = sys_mmap(16) as *i64
  sys_clock_gettime_real(ts)
  let epoch: i64 = ts[0]
  let ips: *i64 = sys_mmap(254 * 8) as *i64
  let dcount: i64 = pctl_discover_scan(base24, 7125, 250, ips, 254)
  var online: i64 = 0
  var pip: i64 = 0
  if dcount > 0 { online = 1; pip = ips[0] }
  let mask: *i64 = sys_mmap(256 * 8) as *i64
  pctl_survey_scan(base24, LSCAN_BUDGET_MS, mask)
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"updated_epoch\":" as *u8)
  o = pctl_catn(out, o, epoch)
  o = pctl_cat(out, o, ",\"subnet\":\"" as *u8)
  o = pctl_cat(out, o, subnet)
  o = pctl_cat(out, o, "\",\"printer_ip\":\"" as *u8)
  let ipstr: *u8 = sys_mmap(24)
  if online == 1 {
      pctl_ip_to_str(pip, ipstr)
      o = pctl_cat(out, o, ipstr)
  }
  o = pctl_cat(out, o, "\",\"printer_online\":" as *u8)
  if online == 1 { o = pctl_cat(out, o, "true" as *u8) } else { o = pctl_cat(out, o, "false" as *u8) }
  o = pctl_cat(out, o, ",\"status\":" as *u8)
  if online == 1 {
      let host: *u8 = sys_mmap(64)
      let hl: i64 = pctl_build_host(ipstr, 7125, host)
      let scratch: *u8 = sys_mmap(PCTL_SCRATCH)
      let resp: *u8 = sys_mmap(PCTL_RESP)
      let rn: *i64 = sys_mmap(8) as *i64
      let empty: *u8 = "\x00" as *u8
      let sc: i64 = pctl_call(PCTL_V_STATUS, pip, 7125, host, hl, empty, 0, scratch, resp, rn)
      let tmp: *u8 = sys_mmap(PCTL_OUT)
      let tl: i64 = pctl_emit_status(tmp, host, sc, resp, rn[0])
      if tl > 0 { if tmp[tl-1] == (10 as u8) { tmp[tl-1] = 0 as u8 } else { tmp[tl] = 0 as u8 } }
      o = pctl_cat(out, o, tmp)
      o = pctl_cat(out, o, ",\"ready\":" as *u8)
      let resp2: *u8 = sys_mmap(PCTL_RESP)
      let rn2: *i64 = sys_mmap(8) as *i64
      let rc: i64 = pctl_call(PCTL_V_READY, pip, 7125, host, hl, empty, 0, scratch, resp2, rn2)
      let tmp2: *u8 = sys_mmap(PCTL_OUT)
      let tl2: i64 = pctl_emit_ready(tmp2, host, rc, resp2, rn2[0])
      if tl2 > 0 { if tmp2[tl2-1] == (10 as u8) { tmp2[tl2-1] = 0 as u8 } else { tmp2[tl2] = 0 as u8 } }
      o = pctl_cat(out, o, tmp2)
  } else {
      o = pctl_cat(out, o, "null,\"ready\":null" as *u8)
  }
  o = pctl_cat(out, o, ",\"survey\":" as *u8)
  let sv: *u8 = sys_mmap(PCTL_OUT)
  let svl: i64 = pctl_emit_survey(sv, subnet, base24, mask)
  if svl > 0 { if sv[svl-1] == (10 as u8) { sv[svl-1] = 0 as u8 } else { sv[svl] = 0 as u8 } }
  o = pctl_cat(out, o, sv)
  o = pctl_cat(out, o, "}\n" as *u8)
  return o
636}
637
638// ===== print job workflow: progress parse (print_stats + virtual_sdcard) ====
639// copy a JSON string value: find <anchor> then <keyq> (e.g. "\"state\":\"") after it,
640// copy chars until the closing quote (escaping \ and ctrl for our own JSON).
641func pctl_cat_jsonstr_after(out: *u8, o: i64, body: *u8, n: i64, anchor: *u8, keyq: *u8) -> i64 {
  let ao: i64 = pctl_find(body, n, 0, anchor)
  if ao < 0 { return o }
  let ko: i64 = pctl_find(body, n, ao, keyq)
  if ko < 0 { return o }
  var i: i64 = ko + pctl_slen(keyq)
  var go: i64 = 1
  while go == 1 {
      if i >= n { go = 0 } else {
          var c: i64 = body[i] & 0xff
          if c == 34 { go = 0 } else {
              if c == 92 { c = 47 }
              if c < 32 { c = 32 }
              out[o] = c as u8
              o = o + 1
              i = i + 1
          }
      }
  }
  return o
661}
662// parse a Moonraker 0.0-1.0 progress float after <anchor>/<keyq> -> integer percent 0-100
663func pctl_pct_after(body: *u8, n: i64, anchor: *u8, keyq: *u8) -> i64 {
  let ao: i64 = pctl_find(body, n, 0, anchor)
  if ao < 0 { return 0 }
  let ko: i64 = pctl_find(body, n, ao, keyq)
  if ko < 0 { return 0 }
  var i: i64 = ko + pctl_slen(keyq)
  var sk: i64 = 1
  while sk == 1 { if i >= n { sk = 0 } else { let c: i64 = body[i] & 0xff; if c == 32 { i = i + 1 } else { sk = 0 } } }
  var intp: i64 = 0
  var rd: i64 = 1
  while rd == 1 { if i >= n { rd = 0 } else { let d: i64 = body[i] & 0xff; if d < 48 { rd = 0 } else { if d > 57 { rd = 0 } else { intp = intp * 10 + (d - 48); i = i + 1 } } } }
  if intp >= 1 { return 100 }
  var f: i64 = 0
  if i < n {
      if body[i] == (46 as u8) {
          i = i + 1
          if i < n {
              let d1: i64 = body[i] & 0xff
              if d1 >= 48 { if d1 <= 57 {
                  f = (d1 - 48) * 10
                  i = i + 1
                  if i < n { let d2: i64 = body[i] & 0xff; if d2 >= 48 { if d2 <= 57 { f = f + (d2 - 48) } } }
              } }
          }
      }
  }
  return f
690}
691func pctl_emit_progress(out: *u8, host: *u8, status: i64, resp: *u8, n: i64) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"progress\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  var pct: i64 = 0
  o = pctl_cat(out, o, ",\"state\":\"" as *u8)
  if n > 0 { if status >= 200 { if status < 300 {
      let bs: i64 = pctl_body_start(resp, n)
      let bp: *u8 = ((resp as i64) + bs) as *u8
      let bn: i64 = n - bs
      o = pctl_cat_jsonstr_after(out, o, bp, bn, "\"print_stats\"" as *u8, "\"state\":\"" as *u8)
      pct = pctl_pct_after(bp, bn, "\"virtual_sdcard\"" as *u8, "\"progress\":" as *u8)
  } } }
  o = pctl_cat(out, o, "\",\"filename\":\"" as *u8)
  if n > 0 { if status >= 200 { if status < 300 {
      let bs2: i64 = pctl_body_start(resp, n)
      let bp2: *u8 = ((resp as i64) + bs2) as *u8
      let bn2: i64 = n - bs2
      o = pctl_cat_jsonstr_after(out, o, bp2, bn2, "\"print_stats\"" as *u8, "\"filename\":\"" as *u8)
  } } }
  o = pctl_cat(out, o, "\",\"progress_pct\":" as *u8)
  o = pctl_catn(out, o, pct)
  o = pctl_cat(out, o, ",\"result\":\"" as *u8)
  o = pctl_cat_netresult(out, o, status)
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
719}
720
721// ===== printstart: start a print of a NAMED, pre-sliced file =======
722// Validated filename (safe chars only, via nx_mr_build_print_start_body); we NEVER inject
723// raw G-code -> never-brick holds. Deeper hardening rung: fetch the file + nx_klipper_gcode
724// _validator before start (reject M500/M502/firmware writes).
725func pctl_printstart(out: *u8, ipv4: i64, port: i64, host: *u8, hl: i64, fn: *u8, fnlen: i64) -> i64 {
  let body: *u8 = sys_mmap(512)
  let blen: i64 = nx_mr_build_print_start_body(fn, fnlen, body, 512)
  var o: i64 = 0
  if blen <= 0 {
      o = pctl_cat(out, o, "{\"verb\":\"printstart\",\"result\":\"BAD_FILENAME\",\"note\":\"filename must be safe chars a-zA-Z0-9._-/\"}\n" as *u8)
      return o
  }
  let scratch: *u8 = sys_mmap(PCTL_SCRATCH)
  let resp: *u8 = sys_mmap(PCTL_RESP)
  let empty: *u8 = "\x00" as *u8
  let n: i64 = nx_mr_post_ipv4(ipv4, port, host, hl, "/printer/print/start" as *u8, 20, body, blen, empty, 0, scratch, PCTL_SCRATCH, resp, PCTL_RESP)
  var status: i64 = n
  if n > 0 { status = nx_mr_parse_status(resp, n) }
  o = pctl_cat(out, o, "{\"verb\":\"printstart\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"filename\":\"" as *u8)
  o = pctl_cat(out, o, fn)
  o = pctl_cat(out, o, "\",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  o = pctl_cat(out, o, ",\"result\":\"" as *u8)
  o = pctl_cat_netresult(out, o, status)
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
749}
750
751// ===== upload: sovereign multipart POST /server/files/upload =======
752// Uploads a local G-code file to the printer (stores it; does NOT run it -- printstart
753// runs a named file). Builds the multipart/form-data body ourselves (no 3rd-party HTTP lib).
754func pctl_build_upload_req(req: *u8, host: *u8, filename: *u8, gcode: *u8, gcode_len: i64) -> i64 {
  let bnd: *u8 = "----nxbprinterctlB0undary" as *u8
  // part1: --bnd\r\nContent-Disposition...filename\r\nContent-Type...\r\n\r\n
  let p1: *u8 = sys_mmap(1024)
  var a: i64 = 0
  a = pctl_cat(p1, a, "--" as *u8)
  a = pctl_cat(p1, a, bnd)
  a = pctl_cat(p1, a, "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"" as *u8)
  a = pctl_cat(p1, a, filename)
  a = pctl_cat(p1, a, "\"\r\nContent-Type: application/octet-stream\r\n\r\n" as *u8)
  // part3: \r\n--bnd--\r\n
  let p3: *u8 = sys_mmap(64)
  var b: i64 = 0
  b = pctl_cat(p3, b, "\r\n--" as *u8)
  b = pctl_cat(p3, b, bnd)
  b = pctl_cat(p3, b, "--\r\n" as *u8)
  let body_len: i64 = a + gcode_len + b
  // headers
  var o: i64 = 0
  o = pctl_cat(req, o, "POST /server/files/upload HTTP/1.1\r\nHost: " as *u8)
  o = pctl_cat(req, o, host)
  o = pctl_cat(req, o, "\r\nContent-Type: multipart/form-data; boundary=" as *u8)
  o = pctl_cat(req, o, bnd)
  o = pctl_cat(req, o, "\r\nContent-Length: " as *u8)
  o = pctl_catn(req, o, body_len)
  o = pctl_cat(req, o, "\r\nConnection: close\r\n\r\n" as *u8)
  // body: part1 + gcode + part3
  var i: i64 = 0
  while i < a { req[o] = p1[i]; o = o + 1; i = i + 1 }
  i = 0
  while i < gcode_len { req[o] = gcode[i]; o = o + 1; i = i + 1 }
  i = 0
  while i < b { req[o] = p3[i]; o = o + 1; i = i + 1 }
  return o
788}
789func pctl_upload_send(out: *u8, ipv4: i64, port: i64, host: *u8, filename: *u8, gcode: *u8, gcode_len: i64) -> i64 {
  let req: *u8 = sys_mmap(gcode_len + 16384)
  let rlen: i64 = pctl_build_upload_req(req, host, filename, gcode, gcode_len)
  let fd: i64 = nx_mr_tcp_connect_ipv4(ipv4, port)
  var status: i64 = 0 - 2
  var n: i64 = 0
  if fd >= 0 {
      var sent: i64 = 0
      while sent < rlen {
          let w: i64 = sys_write(fd, ((req as i64) + sent) as *u8, rlen - sent)
          if w <= 0 { sent = rlen } else { sent = sent + w }
      }
      let resp: *u8 = sys_mmap(PCTL_RESP)
      n = sys_read(fd, resp, PCTL_RESP)
      sys_close(fd)
      if n > 0 { status = nx_mr_parse_status(resp, n) } else { status = 0 - 4 }
  }
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"upload\",\"target\":\"" as *u8)
  o = pctl_cat(out, o, host)
  o = pctl_cat(out, o, "\",\"filename\":\"" as *u8)
  o = pctl_cat(out, o, filename)
  o = pctl_cat(out, o, "\",\"bytes\":" as *u8)
  o = pctl_catn(out, o, gcode_len)
  o = pctl_cat(out, o, ",\"http_status\":" as *u8)
  o = pctl_catn(out, o, status)
  o = pctl_cat(out, o, ",\"result\":\"" as *u8)
  o = pctl_cat_netresult(out, o, status)
  o = pctl_cat(out, o, "\"}\n" as *u8)
  return o
819}
820
821// ===== the sovereign architecture contract (no network; agent-facing) =====
822func pctl_emit_contract(out: *u8) -> i64 {
  var o: i64 = 0
  o = pctl_cat(out, o, "{\"verb\":\"contract\",\"capability\":\"nx_printer_ctl\",\"maps_operator_design\":\"browser->edge->home-gateway->printer\"," as *u8)
  o = pctl_cat(out, o, "\"flow\":[" as *u8)
  o = pctl_cat(out, o, "{\"hop\":1,\"node\":\"browser\",\"presents\":\"opaque X-Nishi-Cap token (cookie/bearer)\"}," as *u8)
  o = pctl_cat(out, o, "{\"hop\":2,\"node\":\"sovereign edge sites.elf :8443\",\"does\":\"validate opaque cap-token, reverse-proxy /printers route\",\"tls\":\"sovereign TLS-1.3 own trust store\"}," as *u8)
  o = pctl_cat(out, o, "{\"hop\":3,\"node\":\"nx_printer_ctl organ (on-NAS, on-LAN)\",\"does\":\"cap-gated fixed-endpoint control\",\"auth\":\"least-authority cap\"}," as *u8)
  o = pctl_cat(out, o, "{\"hop\":4,\"node\":\"QIDI/Moonraker :7125 (Fluidd :10088)\",\"reach\":\"LAN HTTP only\"}]," as *u8)
  o = pctl_cat(out, o, "\"zero_external_exposure\":\"BY_CONSTRUCTION: NAS edge is on the home LAN; printer never sees WAN; only the cap-gated organ reaches it\"," as *u8)
  o = pctl_cat(out, o, "\"never_brick\":\"fixed safe-endpoint allowlist (info/emergency_stop/pause/resume/cancel); NO raw-gcode passthrough => no firmware/EEPROM write path; estop = runtime MCU halt, RAM-only\"," as *u8)
  o = pctl_cat(out, o, "\"safe_endpoints\":[\"/printer/info\",\"/printer/objects/query\",\"/server/files/list\",\"/server/files/upload\",\"/printer/emergency_stop\",\"/printer/print/start\",\"/printer/print/pause\",\"/printer/print/resume\",\"/printer/print/cancel\"]," as *u8)
  o = pctl_cat(out, o, "\"print_workflow\":\"files->printstart(validated filename, never raw-gcode)->progress; slice via sovereign nx_print_session (mesh->gcode); G-code validated by nx_klipper_gcode_validator\"," as *u8)
  o = pctl_cat(out, o, "\"no_third_party\":\"sovereign organs only; no Node/Express/nginx/http-proxy-middleware\"}\n" as *u8)
  return o
836}
nx_printer_ctl_lib.nx source

`nx_printer_ctl_lib.nx` source
