From 8d54028c7fc08ba7c06e20493ca7053661278ec7 Mon Sep 17 00:00:00 2001 From: giles Date: Tue, 30 Jun 2026 15:30:47 +0000 Subject: [PATCH] fed-sx-types Phase 2: peer_types.erl receiver-side cache MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit next/kernel/peer_types.erl — a mirror of peer_actors keyed by type CID (plans/fed-sx-host-types.md step 2). State [{TypeCidBytes, TypeRecord}], where TypeRecord is the parsed DefineType :object payload. Refinement schemas are immutable per CID, so cache entries never go stale. Pure API: new/0, lookup/2, store/3, evict/2, types/1, lookup_or_fetch/3. gen_server API (registered `peer_types`): put/2, lookup/1, state_for/1, known_types/0, lookup_or_fetch/2, start_link/0,1. lookup_or_fetch pulls a Cfg-supplied type_fetch_fn :: fun ((TypeCid, Cfg) -> {ok, Bytes} | {error, _}) on a miss, decodes the wire bytes via term_codec into the TypeRecord, and caches it. No fn -> {error, no_fetch_fn}; fetch error / bad bytes don't poison the cache (caller can retry). Keeping transport in the closure (Phase 3 discovery_type_fetch) keeps the cache testable. Test: next/tests/peer_types.sh (18) — pure + gen_server surface, fetch miss/hit, no-fn, error-no-poison, undecodable-bytes, prepopulate. Conformance 771/771. Co-Authored-By: Claude Opus 4.8 (1M context) --- next/kernel/peer_types.erl | 180 +++++++++++++++++++++++++++++++++++++ next/tests/peer_types.sh | 155 ++++++++++++++++++++++++++++++++ 2 files changed, 335 insertions(+) create mode 100644 next/kernel/peer_types.erl create mode 100755 next/tests/peer_types.sh diff --git a/next/kernel/peer_types.erl b/next/kernel/peer_types.erl new file mode 100644 index 00000000..d585c4a3 --- /dev/null +++ b/next/kernel/peer_types.erl @@ -0,0 +1,180 @@ +-module(peer_types). +-export([new/0, lookup/2, store/3, evict/2, types/1, + lookup_or_fetch/3, decode_type_doc/1, + start_link/0, start_link/1, stop/0, + put/2, lookup/1, state_for/1, known_types/0, + lookup_or_fetch/2, evict/1]). +-export([init/1, handle_call/3, handle_cast/2, handle_info/2]). +-behaviour(gen_server). + +%% Peer-types cache — receiver-side mirror of peer_actors.erl, for +%% host-type federation (plans/fed-sx-host-types.md, Phase 2). When an +%% inbound activity references a refinement type the local node hasn't +%% seen, the object-schema validation stage (Phase 4) needs that +%% type's record — its :refinement-schema and field shape — to vet the +%% inner object. Re-fetching the type doc on every inbound would be +%% wasteful, so we cache the TypeRecord keyed by its content-address. +%% +%% State shape (pure-functional): +%% [{TypeCidBytes, TypeRecord}, ...] +%% +%% TypeCidBytes is the type's CID (a binary). TypeRecord is the parsed +%% DefineType envelope's :object payload — a proplist carrying :name, +%% :fields, :refinement-schema, :instance-type. Refinement schemas are +%% immutable per CID (an updated type is a new CID), so cache entries +%% never go stale — TTL-free, like peer_actors' v2 entries. +%% +%% lookup_or_fetch is the load-bearing entry point: a miss invokes a +%% Cfg-supplied closure to fetch the type doc over the wire. Per the +%% design the closure has shape +%% type_fetch_fn :: fun ((TypeCid, Cfg) -> {ok, Bytes} | {error, _}) +%% returning the term_codec-encoded type-doc bytes; lookup_or_fetch +%% decodes them into the TypeRecord and caches it. Keeping the +%% transport in the closure (Phase 3's discovery_type_fetch) keeps +%% peer_types testable with a mocked fetch — same split as +%% peer_actors / discovery_fetch. +%% +%% gen_server wrapper registers under the atom `peer_types` so the +%% pipeline + http_server handlers can reach it without threading a +%% Pid through Cfg. + +%% ── Pure-functional API ───────────────────────────────────────── + +new() -> []. + +lookup(TypeCid, State) -> + case find_keyed(TypeCid, State) of + {ok, TR} -> {ok, TR}; + {error, _} -> not_found + end. + +store(TypeCid, TR, State) -> + set_keyed(TypeCid, TR, State). + +evict(TypeCid, State) -> + delete_keyed(TypeCid, State). + +types(State) -> [Cid || {Cid, _TR} <- State]. + +%% lookup_or_fetch/3 — cache hit returns {ok, TR, State} unchanged. +%% Cache miss pulls the type_fetch_fn out of Cfg and calls it with +%% (TypeCid, Cfg); a {ok, Bytes} reply is decoded via term_codec into +%% the TypeRecord, which is then stored. Failures (no fn, fetch error, +%% bad bytes) do NOT poison the cache so the caller can retry. +%% +%% no type_fetch_fn in Cfg -> {error, no_fetch_fn, State} +%% fn -> {ok, Bytes}, decodable -> {ok, TR, store(...)} +%% fn -> {ok, Bytes}, bad bytes -> {error, bad_type_doc, State} +%% fn -> {error, Reason} -> {error, Reason, State} +%% fn -> Other -> {error, {bad_fetch_return, Other}, State} + +lookup_or_fetch(TypeCid, Cfg, State) -> + case find_keyed(TypeCid, State) of + {ok, TR} -> {ok, TR, State}; + {error, _} -> fetch_and_store(TypeCid, Cfg, State) + end. + +fetch_and_store(TypeCid, Cfg, State) -> + case field(type_fetch_fn, Cfg) of + nil -> {error, no_fetch_fn, State}; + Fn when is_function(Fn, 2) -> + case Fn(TypeCid, Cfg) of + {ok, Bytes} -> + case decode_type_doc(Bytes) of + {ok, TR} -> {ok, TR, store(TypeCid, TR, State)}; + {error, R} -> {error, R, State} + end; + {error, Reason} -> {error, Reason, State}; + Other -> {error, {bad_fetch_return, Other}, State} + end; + _ -> {error, bad_fetch_fn_cfg, State} + end. + +%% decode_type_doc/1 — round the wire body back through term_codec. +%% The on-wire form is term_codec:encode(TypeRecord) (Phase 3's +%% /types/ route), so a clean decode yields the proplist TR. +decode_type_doc(Bytes) -> + case term_codec:decode(Bytes) of + {ok, TR, _} when is_list(TR) -> {ok, TR}; + _ -> {error, bad_type_doc} + end. + +%% ── gen_server wrapper ────────────────────────────────────────── + +start_link() -> + start_link([]). + +start_link(InitialState) -> + Pid = gen_server:start_link(peer_types, [InitialState]), + erlang:register(peer_types, Pid), + Pid. + +stop() -> + R = gen_server:call(peer_types, '$gen_stop'), + erlang:unregister(peer_types), + R. + +%% put/2 — store a TypeRecord under its CID. Mirrors store_srv. +put(TypeCid, TR) -> + gen_server:call(peer_types, {put, TypeCid, TR}). + +%% lookup/1 — cache read. {ok, TR} | not_found. +lookup(TypeCid) -> + gen_server:call(peer_types, {lookup, TypeCid}). + +%% state_for/1 — alias of lookup/1, named to match peer_actors' +%% state_for accessor used by http_server's kernel bridge. +state_for(TypeCid) -> + gen_server:call(peer_types, {lookup, TypeCid}). + +known_types() -> + gen_server:call(peer_types, get_types). + +evict(TypeCid) -> + gen_server:call(peer_types, {evict, TypeCid}). + +%% lookup_or_fetch/2 — gen_server form. Cfg carries the type_fetch_fn. +%% Reply is {ok, TR} on hit-or-fetched, {error, Reason} otherwise. +lookup_or_fetch(TypeCid, Cfg) -> + gen_server:call(peer_types, {lookup_or_fetch, TypeCid, Cfg}). + +%% gen_server callbacks + +init([InitialState]) -> + {ok, InitialState}. + +handle_call({put, TypeCid, TR}, _From, State) -> + {reply, ok, store(TypeCid, TR, State)}; +handle_call({lookup, TypeCid}, _From, State) -> + {reply, lookup(TypeCid, State), State}; +handle_call({lookup_or_fetch, TypeCid, Cfg}, _From, State) -> + case lookup_or_fetch(TypeCid, Cfg, State) of + {ok, TR, NewState} -> {reply, {ok, TR}, NewState}; + {error, Reason, Same} -> {reply, {error, Reason}, Same} + end; +handle_call(get_types, _From, State) -> + {reply, types(State), State}; +handle_call({evict, TypeCid}, _From, State) -> + {reply, ok, evict(TypeCid, State)}. + +handle_cast(_, S) -> {noreply, S}. + +handle_info(_, S) -> {noreply, S}. + +%% ── Internal helpers ──────────────────────────────────────────── + +field(K, [{K, V} | _]) -> V; +field(K, [_ | Rest]) -> field(K, Rest); +field(_, []) -> nil. + +find_keyed(_, []) -> {error, not_found}; +find_keyed(K, [{K, V} | _]) -> {ok, V}; +find_keyed(K, [_ | Rest]) -> find_keyed(K, Rest). + +set_keyed(K, V, []) -> [{K, V}]; +set_keyed(K, V, [{K, _} | Rest]) -> [{K, V} | Rest]; +set_keyed(K, V, [P | Rest]) -> [P | set_keyed(K, V, Rest)]. + +delete_keyed(_, []) -> []; +delete_keyed(K, [{K, _} | Rest]) -> Rest; +delete_keyed(K, [P | Rest]) -> [P | delete_keyed(K, Rest)]. diff --git a/next/tests/peer_types.sh b/next/tests/peer_types.sh new file mode 100755 index 00000000..c976c35f --- /dev/null +++ b/next/tests/peer_types.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# next/tests/peer_types.sh — host-type federation Phase 2 acceptance. +# +# Receiver-side peer-types cache (next/kernel/peer_types.erl), a mirror +# of peer_actors keyed by type CID. Tracks {TypeCidBytes, TypeRecord} +# pairs so the object-schema validation stage can vet inbound objects +# against a fetched-once refinement type. lookup_or_fetch pulls a +# Cfg-supplied type_fetch_fn on a miss, decodes the returned wire bytes +# via term_codec, and caches the TypeRecord. + +set -uo pipefail +cd "$(git rev-parse --show-toplevel)" + +SX_SERVER="${SX_SERVER:-hosts/ocaml/_build/default/bin/sx_server.exe}" +if [ ! -x "$SX_SERVER" ]; then + SX_SERVER="/root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe" +fi +if [ ! -x "$SX_SERVER" ]; then + echo "ERROR: sx_server.exe not found." >&2 + exit 1 +fi + +VERBOSE="${1:-}" +PASS=0; FAIL=0; ERRORS="" +TMPFILE=$(mktemp); trap "rm -f $TMPFILE" EXIT + +# TR1/TR2 are TypeRecords (the DefineType :object payloads). Doc1 is +# TR1's on-wire form (term_codec). FetchOk serves Doc1 for Cid1; +# FetchBad returns undecodable bytes. CfgOk/CfgBad/CfgNone vary the +# type_fetch_fn slot. +SETUP='Cid1 = <<98,97,102,121,49>>, Cid2 = <<98,97,102,121,50>>, TR1 = [{name, <<80,111,115,116>>}, {instance_type, <<78,111,116,101>>}], TR2 = [{name, <<82,101,112,108,121>>}], Doc1 = term_codec:encode(TR1), FetchOk = fun(C, _) -> case C =:= Cid1 of true -> {ok, Doc1}; false -> {error, not_found} end end, FetchBad = fun(_, _) -> {ok, <<255>>} end, CfgOk = [{type_fetch_fn, FetchOk}], CfgBad = [{type_fetch_fn, FetchBad}], CfgNone = [],' + +cat > "$TMPFILE" < [] +(epoch 10) +(eval "(get (erlang-eval-ast \"peer_types:new() =:= []\") :name)") +;; lookup miss -> not_found +(epoch 11) +(eval "(get (erlang-eval-ast \"peer_types:lookup(<<1>>, peer_types:new()) =:= not_found\") :name)") +;; store + lookup round-trip +(epoch 12) +(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid1, TR1, peer_types:new()), peer_types:lookup(Cid1, S) =:= {ok, TR1}\") :name)") +;; types/1 lists CIDs in insertion order +(epoch 13) +(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid2, TR2, peer_types:store(Cid1, TR1, peer_types:new())), peer_types:types(S) =:= [Cid1, Cid2]\") :name)") +;; evict removes the entry +(epoch 14) +(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:evict(Cid1, peer_types:store(Cid1, TR1, peer_types:new())), peer_types:lookup(Cid1, S) =:= not_found\") :name)") + +;; ── lookup_or_fetch (pure) ───────────────────────────────── +;; miss -> fetch via Cfg.fn, decode bytes, cache TR +(epoch 20) +(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgOk, peer_types:new()) of {ok, TR1, [{Cid1, TR1}]} -> ok; _ -> bad end\") :name)") +;; hit -> returns cached without calling fetch +(epoch 21) +(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid1, TR1, peer_types:new()), case peer_types:lookup_or_fetch(Cid1, CfgBad, S) of {ok, TR1, S} -> ok; _ -> bad end\") :name)") +;; no type_fetch_fn -> {error, no_fetch_fn}, cache untouched +(epoch 22) +(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgNone, peer_types:new()) of {error, no_fetch_fn, []} -> ok; _ -> bad end\") :name)") +;; fetch error does NOT poison the cache +(epoch 23) +(eval "(get (erlang-eval-ast \"${SETUP} BadCfg = [{type_fetch_fn, fun(_, _) -> {error, http_404} end}], case peer_types:lookup_or_fetch(Cid1, BadCfg, peer_types:new()) of {error, http_404, []} -> ok; _ -> bad end\") :name)") +;; undecodable bytes -> {error, bad_type_doc} +(epoch 24) +(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgBad, peer_types:new()) of {error, bad_type_doc, []} -> ok; _ -> bad end\") :name)") + +;; ── gen_server API ───────────────────────────────────────── +;; start_link + put + lookup round-trip +(epoch 30) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:lookup(Cid1) =:= {ok, TR1}\") :name)") +;; lookup miss -> not_found +(epoch 31) +(eval "(get (erlang-eval-ast \"peer_types:start_link(), peer_types:lookup(<<9>>) =:= not_found\") :name)") +;; state_for is an alias of lookup +(epoch 32) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:state_for(Cid1) =:= {ok, TR1}\") :name)") +;; known_types lists stored CIDs +(epoch 33) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:put(Cid2, TR2), peer_types:known_types() =:= [Cid1, Cid2]\") :name)") +;; lookup_or_fetch miss fetches + caches +(epoch 34) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), R = peer_types:lookup_or_fetch(Cid1, CfgOk), R =:= {ok, TR1} andalso peer_types:known_types() =:= [Cid1]\") :name)") +;; lookup_or_fetch with no fn -> {error, no_fetch_fn}, pristine +(epoch 35) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), R = peer_types:lookup_or_fetch(Cid1, CfgNone), R =:= {error, no_fetch_fn} andalso peer_types:known_types() =:= []\") :name)") +;; start_link/1 pre-populates the cache +(epoch 36) +(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link([{Cid1, TR1}]), peer_types:lookup(Cid1) =:= {ok, TR1}\") :name)") +EPOCHS + +OUTPUT=$(timeout 300 "$SX_SERVER" < "$TMPFILE" 2>/dev/null) + +check() { + local epoch="$1" desc="$2" expected="$3" + local actual + actual=$(echo "$OUTPUT" | awk -v e="$epoch" ' + $0 ~ "^\\(ok-len " e " " { getline; print; exit } + $0 ~ "^\\(ok " e " " { print; exit } + $0 ~ "^\\(error " e " " { print; exit } + ') + [ -z "$actual" ] && actual="" + if echo "$actual" | grep -qF -- "$expected"; then + PASS=$((PASS+1)) + [ "$VERBOSE" = "-v" ] && echo " ok $desc" + else + FAIL=$((FAIL+1)) + ERRORS+=" FAIL [$desc] (epoch $epoch) expected: $expected | actual: $actual +" + fi +} + +check 4 "peer_types module loaded" "peer_types" +check 10 "new/0 -> []" "true" +check 11 "lookup miss -> not_found" "true" +check 12 "store + lookup round-trip" "true" +check 13 "types/1 lists in insertion order" "true" +check 14 "evict removes entry" "true" +check 20 "lookup_or_fetch miss fetches" "ok" +check 21 "lookup_or_fetch hit skips fetch" "ok" +check 22 "no fetch_fn -> no_fetch_fn" "ok" +check 23 "fetch error doesn't poison" "ok" +check 24 "undecodable bytes -> bad_type_doc" "ok" +check 30 "gen_server put + lookup" "true" +check 31 "gen_server lookup miss" "true" +check 32 "gen_server state_for alias" "true" +check 33 "gen_server known_types lists" "true" +check 34 "gen_server fetch + cache" "true" +check 35 "gen_server no fn -> pristine" "true" +check 36 "start_link/1 pre-populates" "true" + +TOTAL=$((PASS+FAIL)) +if [ $FAIL -eq 0 ]; then + echo "ok $PASS/$TOTAL next/tests/peer_types.sh passed" +else + echo "FAIL $PASS/$TOTAL passed, $FAIL failed:" + echo "$ERRORS" +fi +[ $FAIL -eq 0 ]