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

1// nx_apistack_idempotency.nx -- CAP-API-IDEMPOTENCY: exactly-once writes over /api. A control plane's write actions
2// (deploy/rollback/restart) MUST be safe to retry -- a dropped response must not double-execute. Answer: an
3// append-only Idempotency-Key ledger (key<TAB>result). On a keyed write: if the key is SEEN, return the CACHED
4// result and SKIP execution; else execute then record. Deterministic, first-write-wins, replay-safe by construction.
5// (IETF Idempotency-Key draft, done sovereign + append-only.) license_tier: ORIGINAL
6import "nx_syscalls.nx"
7import "nx_site_lock_lib.nx"
8const K_MAGIC_262144: i64 = 262144
9const K_MAGIC_4096: i64 = 4096
10
11func id_read_file(path: *u8, out: *u8, cap: i64) -> i64 {
12    let fd: i64 = sys_openat_rd(path)
13    if fd < 0 { return 0 }
14    var total: i64 = 0; var go: i64 = 1
15    while go == 1 {
16        let tail: *u8 = (out as i64 + total) as *u8
17        let nr: i64 = sys_read(fd, tail, cap - total)
18        if nr <= 0 { go = 0 }
19        if nr > 0 { total = total + nr }
20        if total >= cap { go = 0 }
21    }
22    sys_close(fd)
23    return total
24}
25
26// the cached result for `key`: returns result length (>=0) if SEEN, or -1 if NEW (must execute). FIRST match wins.
27func id_lookup(ledger_path: *u8, key: *u8, key_n: i64, out: *u8, cap: i64) -> i64 {
28    let buf: *u8 = sys_mmap(K_MAGIC_262144); let n: i64 = id_read_file(ledger_path, buf, K_MAGIC_262144)
29    let fs: *i64 = sys_mmap(8); let fe: *i64 = sys_mmap(8)
30    var ls: i64 = 0
31    while ls < n {
32        let le: i64 = slk_line_end(buf, n, ls)
33        if le > ls { if buf[ls] != (35 as u8) {
34            if slk_field(buf, ls, le, 0, fs, fe) == 1 {
35                if slk_eq(slk_at(buf, fs[0]), fe[0] - fs[0], key, key_n) == 1 {
36                    if slk_field(buf, ls, le, 1, fs, fe) == 1 {
37                        var o: i64 = 0; let rl: i64 = fe[0] - fs[0]
38                        while o < rl { if o < cap - 1 { out[o] = buf[fs[0] + o] } o = o + 1 }
39                        out[o] = 0 as u8
40                        return rl
41                    }
42                    out[0] = 0 as u8; return 0     // key present, empty result -> still SEEN
43                }
44            }
45        } }
46        ls = le + 1
47    }
48    out[0] = 0 as u8; return 0 - 1                  // -1 = NOT found = a new request
49}
50
51// 1 if the key was recorded (=> return cached, do NOT re-execute), 0 if new.
52func id_seen(ledger_path: *u8, key: *u8, key_n: i64) -> i64 {
53    let tmp: *u8 = sys_mmap(K_MAGIC_4096)
54    if id_lookup(ledger_path, key, key_n, tmp, K_MAGIC_4096) >= 0 { return 1 }
55    return 0
56}
57
58// record key->result (append-only; caller records ONCE after executing). First-write-wins -- a later record for the
59// same key is inert because id_lookup returns the first match.
60func id_record(ledger_path: *u8, key: *u8, key_n: i64, result: *u8, result_n: i64) -> i64 {
61    let fd: i64 = sys_openat_append(ledger_path, 0x1a4)
62    if fd < 0 { return 0 - 1 }
63    sys_write(fd, key, key_n); sys_write(fd, "\t" as *u8, 1)
64    sys_write(fd, result, result_n); sys_write(fd, "\n" as *u8, 1)
65    sys_close(fd)
66    return 1
67}
nx_apistack_idempotency.nx source

`nx_apistack_idempotency.nx` source
