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

↩ module page · 238 lines · 14152 B
1// nx_deadline_gate.nx -- the referee for request-deadline propagation (nx_deadline_lib).
2//
3// The property that matters is not "does it parse a number". It is that the clamp can only ever SHORTEN a
4// wait the caller already chose, because that is what makes this a COMPOSITION of the estate's existing
5// per-lane timeout rulers instead of a second, rival one. So the load-bearing tooth is exhaustive over a
6// grid: for every (deadline, now, want) tried, dl_wait_ms <= want AND >= 0. A primitive that could return
7// more than `want` would silently extend somebody's timeout the first time it was adopted.
8//
9// It also asserts the PRODUCER and CONSUMER agree on the header name by reading the producer's SOURCE --
10// nx_sites_daemon_v2 carries its own NX_SD2_DEADLINE_HDR copy today, and a comment asking people to keep
11// two literals in step is not a control. This tooth turns that into a RED.
12// license_tier: ORIGINAL   Read-only. No hw writes (Rule 26).   expect_exit: 0
13import "nx_syscalls.nx"
14import "nx_gate_verdict.nx"
15import "nx_deadline_lib.nx"
16
17const DG_SRC_A: *u8 = "buildroot/runtime/_hdl_build/nx_sites_daemon_v2.nx"
18const DG_SRC_B: *u8 = "runtime/_hdl_build/nx_sites_daemon_v2.nx"
19const DG_SRC_C: *u8 = "/mnt/c/Users/elder/nishi-core/nxc2/runtime/_hdl_build/nx_sites_daemon_v2.nx"
20const DG_PROD_CONST: *u8 = "const NX_SD2_DEADLINE_HDR: *u8 = \""
21// Fixture request buffer. One size for every fixture below, comfortably above the largest of them, so a
22// new fixture cannot silently outgrow a per-site number nobody re-checked.
23const DG_FX_BUF: i64 = 2048
24// The deadline the header-carrying fixture DECLARES. It is a MATCHED PAIR with the digits written inside
25// that fixture's header text, and the pairing is self-checking rather than trusted: if the two ever
26// disagree, the scan tooth that compares them fails. That is the only honest way to bind a const to a
27// string literal, since the literal cannot be derived from the const.
28const DG_FX_DEADLINE_MS: i64 = 1234567
29// Offset of the deadline header line inside that same fixture ("POST /api/x HTTP/1.1" 20 + CRLF 2 +
30// "Host: a" 7 + CRLF 2 = 31) and a window that ends MID-NAME. Asserted, not trusted: the companion tooth
31// proves the FULL name matches at this offset, so a 0 from the short window is a TRUNCATION refusal and
32// not a name mismatch. Getting this wrong is how a tooth ends up testing a different thing than it says.
33const DG_FX_HDR_OFF: i64 = 31
34const DG_FX_TRUNC_LEN: i64 = 6
35
36func dg_len(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
37
38func dg_find(hay: *u8, hn: i64, needle: *u8) -> i64 {
  let m: i64 = dg_len(needle)
  if m == 0 { return 0 - 1 }
  if m > hn { return 0 - 1 }
  var i: i64 = 0
  let last: i64 = hn - m
  while i <= last {
      var j: i64 = 0
      var ok: i64 = 1
      while j < m {
          if hay[i + j] != needle[j] { ok = 0; j = m } else { j = j + 1 }
      }
      if ok == 1 { return i }
      i = i + 1
  }
  return 0 - 1
54}
55
56// Fixture writer. Requests are assembled AT RUNTIME rather than stored as one blob so each tooth can
57// state its own shape inline and no fixture can silently drift out from under the tooth that names it.
58func dg_put(dst: *u8, off: i64, s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) { dst[off+i] = s[i]; i = i + 1 }
  return off + i
62}
63func dg_read_any(box: *i64) -> *u8 {
  var b: *u8 = sys_read_file(DG_SRC_A, box)
  if (b as i64) == 0 { b = sys_read_file(DG_SRC_B, box) }
  if (b as i64) == 0 { b = sys_read_file(DG_SRC_C, box) }
  return b
68}
69
70func main(argc: i64, argv: *i64) -> i64 {
  gv_head("nx_deadline_gate -- request deadline propagation: the clamp may only ever SHORTEN, and the producer and consumer must agree on the header name" as *u8)
  let ctr: *i64 = gv_ctr()
73
  // ---- parsing: ABSENT and ZERO are different answers ----
  gv_check_eq("parse: a plain decimal value parses to that deadline" as *u8,
      dl_parse_ms("1788469400123" as *u8, 13), 1788469400123, ctr)
  gv_check_eq("parse: one leading space (as a header value may carry) is tolerated" as *u8,
      dl_parse_ms(" 4242" as *u8, 5), 4242, ctr)
  gv_check_eq("parse: it stops at the first non-digit, so a trailing CR or parameter is harmless" as *u8,
      dl_parse_ms("500\r" as *u8, 4), 500, ctr)
  gv_check_eq("parse: a literal 0 is a REAL (long-expired) deadline, NOT absent" as *u8,
      dl_parse_ms("0" as *u8, 1), 0, ctr)
  gv_check_eq("neg-control-an-EMPTY-value-is-ABSENT-not-zero (a missing header must never impose a zero budget)" as *u8,
      dl_parse_ms("" as *u8, 0), DL_ABSENT, ctr)
  gv_check_eq("neg-control-a-NON-NUMERIC-value-is-ABSENT-not-a-partial-number" as *u8,
      dl_parse_ms("abc" as *u8, 3), DL_ABSENT, ctr)
  gv_check_eq("neg-control-an-OVERFLOWING-value-REFUSES-rather-than-wrapping (a wrapped deadline is a wrong answer with a plausible shape)" as *u8,
      dl_parse_ms("99999999999999999999" as *u8, 20), DL_ABSENT, ctr)
89
  // ---- the three named states ----
  gv_check_eq("state: no declared deadline is NO-DEADLINE-DECLARED, never EXPIRED" as *u8,
      dl_state(DL_ABSENT, 1000), DL_S_NONE, ctr)
  gv_check_eq("state: a deadline in the future is LIVE" as *u8,
      dl_state(2000, 1000), DL_S_LIVE, ctr)
  gv_check_eq("state: a deadline already reached is EXPIRED (<= now, so equality counts as gone)" as *u8,
      dl_state(1000, 1000), DL_S_EXPIRED, ctr)
  gv_check_eq("remaining: a live deadline reports the milliseconds left" as *u8,
      dl_remaining_ms(2500, 1000), 1500, ctr)
  gv_check_eq("remaining: absent stays ABSENT rather than becoming a number" as *u8,
      dl_remaining_ms(DL_ABSENT, 1000), DL_ABSENT, ctr)
101
  // ---- THE CLAMP: the property the whole lib exists for ----
  gv_check_eq("clamp: with NO deadline the caller's own wait is returned UNCHANGED (never invent a budget)" as *u8,
      dl_wait_ms(DL_ABSENT, 1000, 5000), 5000, ctr)
  gv_check_eq("clamp: an EXPIRED deadline yields 0 -- do not start work that cannot be delivered" as *u8,
      dl_wait_ms(900, 1000, 5000), 0, ctr)
  gv_check_eq("clamp: when less time remains than the caller wanted, the REMAINING time wins (honouring)" as *u8,
      dl_wait_ms(1200, 1000, 5000), 200, ctr)
  gv_check_eq("clamp: when MORE time remains than the caller wanted, the caller's want wins (composing, not extending)" as *u8,
      dl_wait_ms(9000, 1000, 5000), 5000, ctr)
  gv_check_eq("neg-control-a-negative-want-can-never-produce-a-negative-wait" as *u8,
      dl_wait_ms(9000, 1000, 0 - 7), 0, ctr)
113
  // EXHAUSTIVE over a grid: the two invariants that make this a composition rather than a rival ruler.
  // ★A PROPERTY CHECKED ON THREE HAND-PICKED CASES IS AN ANECDOTE; CHECKED OVER EVERY COMBINATION IT IS
  //  AN INVARIANT -- and this is the one that decides whether adopting the lib can hurt a caller.
  var never_longer: i64 = 1
  var never_negative: i64 = 1
  var tried: i64 = 0
  var saw_shorten: i64 = 0
  var d: i64 = 0
  while d < 12 {
      var w: i64 = 0
      while w < 12 {
          let now: i64 = 500
          let dl: i64 = 400 + d * 40
          let want: i64 = w * 40
          let got: i64 = dl_wait_ms(dl, now, want)
          if got > want { never_longer = 0 }
          if got < 0 { never_negative = 0 }
          if got < want { saw_shorten = 1 }
          tried = tried + 1
          w = w + 1
      }
      d = d + 1
  }
  gv_check("CLAMP INVARIANT (exhaustive, 144 combinations): dl_wait_ms NEVER returns more than the caller's own want -- it composes their timeout, it cannot extend it" as *u8,
      never_longer, ctr)
  gv_check("CLAMP INVARIANT (exhaustive): dl_wait_ms never returns a negative wait" as *u8,
      never_negative, ctr)
  gv_check("fixture-reached-condition: the grid actually exercised the SHORTENING branch (an all-pass-through grid would prove nothing)" as *u8,
      saw_shorten, ctr)
  gv_check_eq("fixture-reached-condition: the grid visited every combination it claims" as *u8,
      tried, 144, ctr)
145
  // ---- PRODUCER/CONSUMER AGREEMENT, read from the producer's own source ----
  let box: *i64 = sys_mmap(16) as *i64
  let src: *u8 = dg_read_any(box)
  var sn: i64 = 0
  if (src as i64) != 0 { sn = box[0] }
  gv_need("the front-door source is readable from one of the three known roots (else this axis abstains rather than acquitting)" as *u8,
      ((sn > 0) as i64), ctr)
  if sn > 0 {
      let at: i64 = dg_find(src, sn, DG_PROD_CONST)
      gv_check("producer: the front door declares NX_SD2_DEADLINE_HDR" as *u8,
          (at >= 0) as i64, ctr)
      if at >= 0 {
          let vp: *u8 = ((src as i64) + at + dg_len(DG_PROD_CONST)) as *u8
          let want: i64 = dg_len(DL_HDR)
          var same: i64 = 1
          var k: i64 = 0
          while k < want {
              if vp[k] != DL_HDR[k] { same = 0; k = want } else { k = k + 1 }
          }
          gv_check("SSOT: the producer's header literal is BYTE-EQUAL to this lib's DL_HDR -- two copies exist, so a divergence is a RED rather than a comment asking people to be careful" as *u8,
              same, ctr)
      }
  }
169
  // ---- FINDING THE DEADLINE (dl_keylen / dl_is_hdr_line / dl_scan_request).
  // These are in the LIB and therefore provable IN-PROCESS. Had they been written as sd2_-prefixed
  // copies inside the front door, they would have sat on the far side of a fork boundary from this gate
  // and could only ever have been tested end-to-end -- which in practice means not tested at all.
  let kl: i64 = dl_keylen()
  gv_check_eq("keylen: DERIVED from DL_HDR and lands exactly one past the colon, so it can never drift from the literal" as *u8,
      (DL_HDR[kl-1] as i64), 58, ctr)
  gv_check_eq("keylen: it stops AT the colon rather than running to the end of the literal (the trailing space is a value, not a name)" as *u8,
      kl, dg_len(DL_HDR) - 1, ctr)
179
  let fx: *u8 = sys_mmap(DG_FX_BUF)
  var fn: i64 = 0
  fn = dg_put(fx, 0, "POST /api/x HTTP/1.1\r\nHost: a\r\nX-Nishi-Deadline-Mono-Ms: 1234567\r\nContent-Length: 5\r\n\r\nhello" as *u8)
  gv_check_eq("scan: a deadline carried in the request headers is found and parsed" as *u8,
      dl_scan_request(fx, fn), DG_FX_DEADLINE_MS, ctr)
185
  let fx2: *u8 = sys_mmap(DG_FX_BUF)
  var fn2: i64 = 0
  fn2 = dg_put(fx2, 0, "GET /x HTTP/1.1\r\nHost: a\r\nAccept: */*\r\n\r\n" as *u8)
  gv_check_eq("neg-control-a-request-declaring-NO-deadline-scans-to-ABSENT-not-to-a-number" as *u8,
      dl_scan_request(fx2, fn2), DL_ABSENT, ctr)
191
  let fx3: *u8 = sys_mmap(DG_FX_BUF)
  var fn3: i64 = 0
  fn3 = dg_put(fx3, 0, "GET /x HTTP/1.1\r\nx-NISHI-deadline-MONO-ms: 777\r\n\r\n" as *u8)
  gv_check_eq("scan: the header is matched case-INSENSITIVELY (RFC 9110), so a hop that re-cased it is still honoured" as *u8,
      dl_scan_request(fx3, fn3), 777, ctr)
197
  // THE ONE THAT MATTERS ON A PUBLIC FRONT DOOR. The body is attacker-controlled. A request that could
  // SHORTEN its own deadline is merely odd; one that could LENGTHEN it walks straight past the budget
  // this whole file exists to enforce. The scan must stop at the blank line.
  let fx4: *u8 = sys_mmap(DG_FX_BUF)
  var fn4: i64 = 0
  fn4 = dg_put(fx4, 0, "POST /x HTTP/1.1\r\nHost: a\r\nContent-Length: 38\r\n\r\nX-Nishi-Deadline-Mono-Ms: 99999999999\r\n" as *u8)
  gv_check_eq("neg-control-a-deadline-shaped-string-in-the-POST-BODY-is-NOT-readable-as-a-header (a body that could lengthen its own deadline is a bypass)" as *u8,
      dl_scan_request(fx4, fn4), DL_ABSENT, ctr)
  gv_check("fixture-reached-condition: that body fixture really does contain the header text it must not honour, so the tooth above is not passing on an empty search" as *u8,
      dg_find(fx4, fn4, "X-Nishi-Deadline-Mono-Ms: 99999999999" as *u8) >= 0, ctr)
208
  let fx5: *u8 = sys_mmap(DG_FX_BUF)
  var fn5: i64 = 0
  fn5 = dg_put(fx5, 0, "GET /x HTTP/1.1\r\nX-Nishi-Deadline-Mono-Ms: 111\r\nX-Nishi-Deadline-Mono-Ms: 222\r\n\r\n" as *u8)
  gv_check_eq("scan: with the header DUPLICATED the FIRST wins -- the same rule every first-match reader downstream follows, so the edge and the backend resolve it identically" as *u8,
      dl_scan_request(fx5, fn5), 111, ctr)
214
  let fx6: *u8 = sys_mmap(DG_FX_BUF)
  var fn6: i64 = 0
  fn6 = dg_put(fx6, 0, "X-Nishi-Deadline-Mono-Zz: 5\r\n\r\n" as *u8)
  gv_check_eq("neg-control-a-DIFFERENT-header-sharing-a-long-prefix-does-not-match" as *u8,
      dl_is_hdr_line(fx6, 0, fn6), 0, ctr)
  // The PAIR is the point. Tooth one proves the full header name really is at DG_FX_HDR_OFF, so tooth
  // two's 0 can only come from the buffer ending mid-name. Without the first, the second would pass just
  // as happily against an offset holding some unrelated header -- a tooth testing something other than
  // the bound it is named for. A NEG-CONTROL THAT COULD RETURN 0 FOR A SECOND REASON PROVES NEITHER.
  gv_check_eq("fixture-reached-condition: the full deadline header name IS present at the offset the truncation tooth uses" as *u8,
      dl_is_hdr_line(fx, DG_FX_HDR_OFF, DG_FX_HDR_OFF + dl_keylen()), 1, ctr)
  gv_check_eq("neg-control-a-buffer-TRUNCATED-mid-name-returns-0-rather-than-reading-past-n" as *u8,
      dl_is_hdr_line(fx, DG_FX_HDR_OFF, DG_FX_HDR_OFF + DG_FX_TRUNC_LEN), 0, ctr)
228
  gv_kv("scan_headers_ms" as *u8, dl_scan_request(fx, fn))
  gv_kv("scan_body_absent" as *u8, dl_scan_request(fx4, fn4))
  gv_kv("dl_keylen" as *u8, kl)
  gv_kv("grid_combinations" as *u8, tried)
  gv_kv("producer_src_bytes" as *u8, sn)
  gv_kv("hdr_name_len" as *u8, dg_len(DL_HDR))
235
  return gv_verdict("deadline" as *u8, ctr,
      "the deadline clamp composes a caller's timeout and provably cannot extend it (exhaustive over 144 combinations), ABSENT is never confused with a zero budget, an overflowing value refuses rather than wraps, and the producer's header literal is asserted byte-equal to the consumer's" as *u8)
238}
nx_deadline_gate.nx source

`nx_deadline_gate.nx` source
