Compare commits

...
12 Commits
Author SHA1 Message Date
mesh-admin 9747f3e1b1 Merge pull request 'go: a module reads the values its bucket still keeps for a key (ADR 0307, issue 502)' (#22) from adr-0307-state-history into main 2026-10-12 08:21:13 +00:00
jochen d41d255f28 go: a module reads the values its bucket still keeps for a key, so the tracker can carry them into its log (hq ADR 0307)
mesh/delivery delivered
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery-group group adr-0307-state-history merged: every member is merged
2026-10-12 10:17:56 +02:00
mesh-admin 5794ccd569 Merge pull request 'go: a module appends to and reads its log through the runtime (ADR 0297, issues 501, 502)' (#21) from adr-0297-log into main 2026-10-11 18:08:52 +00:00
jochen eaed934629 go: a module appends to and reads its log through the runtime, so its record outlives a bucket's history (hq ADR 0297)
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery delivered
2026-10-11 19:16:09 +02:00
mesh-admin 4cf45b5ca0 Merge pull request 'go: a tool reads its caller from the runtime (hq issue 365)' (#20) from fix/365-a-tool-call-names-its-caller into main 2026-10-11 09:19:42 +00:00
jschoubben d9e24e95a2 go: a tool reads its caller from the runtime, so a record can say who acted (hq issue 365)
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery delivered
mesh/delivery-group group fix/365-a-tool-call-names-its-caller merged: every member is merged
The runtime names the caller it took from the subject a call arrived on in the
call's _meta; stdio.CallerOf(args) hands it to the tool. Never read from the
arguments, and Unproven when the runtime named none, so a bundle on an older
runtime still says, explicitly, that its caller was not proven.
2026-10-11 05:11:08 +02:00
mesh-admin ee1e1a8303 Merge pull request 'cli: a client reads the answer its failed write left waiting, so a refusal is heard (issue 444)' (#19) from fix/444-a-client-reads-the-answer-its-write-could-not-finish into main 2026-10-11 00:56:01 +00:00
jschoubben 24f5ee81bd cli: after a failed write take only a refusal, since nothing can have run, and pin that the read keeps the ask's deadline (hq issue 444)
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery delivered
2026-10-11 02:49:17 +02:00
jschoubben b4900f52b8 cli: read the engine's answer after a failed request write, so a refusal is not lost as a broken pipe (hq issue 444)
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery superseded: a newer head of the same pull request
2026-10-11 02:43:54 +02:00
mesh-admin 19cfe0ef03 Merge pull request 'go/health: a health tool answers healthy, unhealthy or waits (issue 386, ADR 0283)' (#18) from feat/386-a-wait-for-the-operator into main 2026-10-10 19:13:46 +00:00
jochen 33917f91ac Refuse every form of path or address in a wait's words, a contradicting healthy answer, and a malformed wait at Waiting
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery delivered
mesh/delivery-group group feat/386-a-wait-for-the-operator merged: every member is merged
From the review of mesh-sdk#18: quoted and bracketed paths, home and relative
paths, IPv6, host and port, UNC and drive paths passed the check.
2026-10-10 21:10:01 +02:00
jochen 622b6b4f55 Add go/health: a health tool answers healthy, unhealthy or waits (hq ADR 0283, issue 386)
mesh/delivery-group group feat/386-a-wait-for-the-operator checking: 1 of 2 member(s) ready
mesh/merge-gate pass: builds mesh-sdk, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (typescript), go/merge-check.sh (go)
mesh/delivery superseded: a newer head of the same pull request
A module waiting for the operator's secret had only 'not healthy' to say,
so its first-node gate failed and the operator was told nothing to do.
The answer gains a state and named waits, and Read refuses any wait it
cannot check, so a malformed wait never excuses a fault.
2026-10-10 21:06:44 +02:00
12 changed files with 1296 additions and 7 deletions
+2 -2
View File
@@ -2,8 +2,8 @@
`stdio.Serve("", tools)` speaks MCP over stdio to the node's tool runtime, as the module the runtime
names (novox/hq ADR 0188, ADR 0193). A `Tool` is a name, a description, an argument schema and a
function; calls run concurrently. A tool named `<seat>.<verb>` is the seat's implementation.
`stdio.Emit(type, body)` publishes an event as the module, `stdio.Subscribe(pattern, handler)` receives the module's events (taken when the handler returns nil, offered again when it returns an error — the one rule is in the repository README, "Taking an event") and `stdio.Ask(key, body)` calls a tool, and `stdio.State(name)` gets, puts, deletes, lists and watches the module's declared state — all through the runtime (novox/hq ADR 0193, 0198, 0201). Standard library only.
function; calls run concurrently. `stdio.CallerOf(args)` inside a tool is who called it: the bus user the runtime took from the subject the call arrived on, named in the call's `_meta`, never read from the arguments — or `stdio.Unproven` when the runtime named none (novox/hq issue 365). A tool named `<seat>.<verb>` is the seat's implementation.
`stdio.Emit(type, body)` publishes an event as the module, `stdio.Subscribe(pattern, handler)` receives the module's events (taken when the handler returns nil, offered again when it returns an error — the one rule is in the repository README, "Taking an event") and `stdio.Ask(key, body)` calls a tool, and `stdio.State(name)` gets, puts, deletes, lists, watches and reads the kept history of the module's declared state, and `stdio.Log(name)` appends to, reads, and measures a log of operations the module declared — all through the runtime (novox/hq ADR 0193, 0198, 0201, 0297, 0307). Standard library only.
## Installing
+59
View File
@@ -0,0 +1,59 @@
package stdio
import (
"reflect"
"regexp"
"sync"
"unsafe"
)
// Unproven is the caller of a call the runtime named no caller for: one that arrived on the subject that names
// none, or from a runtime that names none (novox/hq issue 365). Said as a word, never left empty, so a record
// shows it was not proven.
const Unproven = "unproven"
// MetaCaller is where in a `tools/call`'s `_meta` the runtime names the caller: the bus user that published the
// call, which the runtime takes from the subject the call arrived on — that subject's last token, which the
// bus lets each user publish with its own name alone (novox/hq issue 365, by ADR 0259 §3's precedent). The
// runtime writes `_meta`; a caller writes only `arguments`, so no caller can name another.
const MetaCaller = "mesh/caller"
// busUser is the shape of a bus user's name: `<node>.<module>`, `person.<name>`, `controller` — names whose
// parts are safe in a subject. Anything else the runtime named is not a caller and reads as Unproven.
var busUser = regexp.MustCompile(`^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$`)
// calls holds the caller of every call while its tool runs, by the arguments map that call was handed.
var calls sync.Map // unsafe.Pointer → string
func argsKey(args map[string]any) unsafe.Pointer {
return reflect.ValueOf(args).UnsafePointer()
}
// CallerOf is who called the tool that was handed args, as the runtime proved it: the bus user that
// published the call, or Unproven. Read from the runtime, never from the arguments' contents — a `caller`
// argument names nobody. Valid while the tool runs; arguments no call was handed have no caller.
func CallerOf(args map[string]any) string {
if args == nil {
return Unproven
}
if c, ok := calls.Load(argsKey(args)); ok {
return c.(string)
}
return Unproven
}
// callerIn is the caller a `tools/call`'s `_meta` names, or Unproven.
func callerIn(meta map[string]any) string {
if s, ok := meta[MetaCaller].(string); ok && busUser.MatchString(s) {
return s
}
return Unproven
}
// runAs runs a tool with the caller held for its arguments for as long as it runs.
func runAs(t Tool, caller string, args map[string]any) (any, error) {
key := argsKey(args)
calls.Store(key, caller)
defer calls.Delete(key)
return t.Run(args)
}
+105
View File
@@ -0,0 +1,105 @@
package stdio
import (
"bufio"
"encoding/json"
"io"
"testing"
"time"
)
// callWith serves one tool that answers the caller CallerOf reads from its arguments, sends it one tools/call
// with the params given, and returns the caller it answered.
func callWith(t *testing.T, params map[string]any) string {
t.Helper()
inR, inW := io.Pipe()
outR, outW := io.Pipe()
go func() {
_ = ServeOn("tracker", []Tool{{Name: "who", Run: func(args map[string]any) (any, error) {
return map[string]any{"caller": CallerOf(args)}, nil
}}}, inR, outW)
}()
defer inW.Close()
b, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": params})
_, _ = inW.Write(append(b, '\n'))
lines := bufio.NewScanner(outR)
done := make(chan string, 1)
go func() {
if lines.Scan() {
var m struct {
Result struct {
Content []struct {
Text string `json:"text"`
} `json:"content"`
} `json:"result"`
}
_ = json.Unmarshal(lines.Bytes(), &m)
var answer struct {
Caller string `json:"caller"`
}
if len(m.Result.Content) > 0 {
_ = json.Unmarshal([]byte(m.Result.Content[0].Text), &answer)
}
done <- answer.Caller
}
}()
select {
case got := <-done:
return got
case <-time.After(3 * time.Second):
t.Fatal("the bundle did not answer the call")
return ""
}
}
// **A tool reads its caller from the runtime, never from the call's arguments** (novox/hq issue 365): the
// runtime names the caller it took from the subject the call arrived on in the call's `_meta`, and CallerOf
// hands it to the tool by the arguments the tool was given.
func TestAToolReadsTheCallerTheRuntimeNamed(t *testing.T) {
got := callWith(t, map[string]any{"name": "who", "arguments": map[string]any{"title": "x"},
"_meta": map[string]any{MetaCaller: "shanks.node-tools"}})
if got != "shanks.node-tools" {
t.Fatalf("the tool read caller %q, want the one the runtime named", got)
}
}
// A caller named in the arguments is not the caller: an argument is the caller's to write.
func TestACallerInTheArgumentsIsNeverTheCaller(t *testing.T) {
got := callWith(t, map[string]any{"name": "who", "arguments": map[string]any{"caller": "novox.node-tools",
"_meta": map[string]any{MetaCaller: "novox.node-tools"}, MetaCaller: "novox.node-tools"}})
if got != Unproven {
t.Fatalf("a caller the arguments claimed was read as %q, want %q", got, Unproven)
}
got = callWith(t, map[string]any{"name": "who", "arguments": map[string]any{"caller": "novox.node-tools"},
"_meta": map[string]any{MetaCaller: "shanks.node-tools"}})
if got != "shanks.node-tools" {
t.Fatalf("with a caller in the arguments the tool read %q, want the runtime's", got)
}
}
// A runtime that names no caller — one from before issue 365, or a call on the subject that names none — is
// said as Unproven, explicitly; a caller that is not a bus user's name is Unproven too.
func TestACallTheRuntimeNamedNoCallerForIsUnproven(t *testing.T) {
for _, params := range []map[string]any{
{"name": "who", "arguments": map[string]any{}},
{"name": "who"},
{"name": "who", "arguments": map[string]any{}, "_meta": map[string]any{}},
{"name": "who", "arguments": map[string]any{}, "_meta": map[string]any{MetaCaller: ""}},
{"name": "who", "arguments": map[string]any{}, "_meta": map[string]any{MetaCaller: "a b"}},
{"name": "who", "arguments": map[string]any{}, "_meta": map[string]any{MetaCaller: 7}},
} {
if got := callWith(t, params); got != Unproven {
t.Errorf("%v: the tool read caller %q, want %q", params, got, Unproven)
}
}
}
// Arguments the runtime never handed a tool have no caller.
func TestArgumentsOfNoCallHaveNoCaller(t *testing.T) {
if got := CallerOf(map[string]any{"x": 1}); got != Unproven {
t.Fatalf("CallerOf of a map no call was given answered %q", got)
}
if got := CallerOf(nil); got != Unproven {
t.Fatalf("CallerOf(nil) answered %q", got)
}
}
+15 -1
View File
@@ -140,7 +140,21 @@ func AskWith(ctx context.Context, socket string, req Request) (Answer, error) {
_ = conn.SetDeadline(deadline)
}
if err := WriteRequest(conn, req); err != nil {
return Answer{}, fmt.Errorf("asking the node-engine: %w", err)
// The engine may have answered before it read the request — a refusal (busy, an unknown account) written
// and the connection closed — and the write then fails on the close. That answer is already waiting, and
// it says why where the write error says only that the pipe broke (novox/hq issue 444, found under issue
// 434). So read it, within the deadline the connection already has, and only when none came say the write.
// Only a refusal is taken: the request was never wholly written, so nothing can have run, and any other
// answer here is not one a correct engine gives — passing it on as success would hide the failure.
a, rerr := ReadAnswer(conn)
if rerr != nil {
return Answer{}, fmt.Errorf("asking the node-engine: %w; and no answer came (%v)", err, rerr)
}
if a.Refused == "" {
return Answer{}, fmt.Errorf("asking the node-engine: %w; and the answer that came is not a refusal, "+
"though the request was never wholly written", err)
}
return a, nil
}
a, err := ReadAnswer(conn)
if err != nil {
+123
View File
@@ -0,0 +1,123 @@
package cli
import (
"context"
"errors"
"net"
"os"
"path/filepath"
"strings"
"testing"
"time"
)
// anEngineThatClosesFirst listens like the node-engine before mesh-host#80: it writes its answer, if any, and
// closes without reading the request (novox/hq issue 434). It answers one connection.
func anEngineThatClosesFirst(t *testing.T, answer *Answer) string {
t.Helper()
socket := filepath.Join(t.TempDir(), "cli.sock")
l, err := net.Listen("unix", socket)
if err != nil {
t.Skipf("no unix socket here: %v", err)
}
t.Cleanup(func() { l.Close() })
go func() {
conn, err := l.Accept()
if err != nil {
return
}
if answer != nil {
_ = WriteAnswer(conn, *answer)
}
conn.Close()
}()
return socket
}
// aLineTheSocketCannotHold is a request larger than a unix socket buffers, so its write cannot finish before
// the engine reads it — and an engine that closes first makes it fail every time, not only when it loses a race.
func aLineTheSocketCannotHold() []string { return []string{"status", strings.Repeat("x", 4<<20)} }
// An engine that refuses and closes before reading the request is heard: its refusal reaches the caller, not
// the broken pipe its close left the client's write (novox/hq issue 444).
func TestARefusalWrittenBeforeTheRequestIsReadReachesTheCaller(t *testing.T) {
busy := Refusal("the node-engine is busy: too many lines at once")
socket := anEngineThatClosesFirst(t, &busy)
a, err := Ask(context.Background(), socket, aLineTheSocketCannotHold())
if err != nil {
t.Fatalf("the engine said %q and the caller heard: %v", busy.Refused, err)
}
if a.Refused != busy.Refused || a.Exit != 1 {
t.Fatalf("the engine said %q and the caller heard %+v", busy.Refused, a)
}
}
// When the write fails and no answer is waiting, the error says both: what failed, and that no answer came.
func TestAFailedWriteWithNoAnswerSaysBoth(t *testing.T) {
socket := anEngineThatClosesFirst(t, nil)
start := time.Now()
_, err := Ask(context.Background(), socket, aLineTheSocketCannotHold())
if err == nil {
t.Fatal("a request the engine never read, and never answered, came back without an error")
}
if !strings.Contains(err.Error(), "asking the node-engine") || !strings.Contains(err.Error(), "no answer came") {
t.Fatalf("the error does not say what failed and that no answer came: %v", err)
}
if waited := time.Since(start); waited > 30*time.Second {
t.Fatalf("waited %s on a connection the engine had closed", waited)
}
}
// After a failed write only a refusal is taken: nothing can have run, so an answer saying it ran and exited 0
// is an error, never a success (novox/hq issue 444).
func TestAnAnswerOtherThanARefusalAfterAFailedWriteIsAnError(t *testing.T) {
ran := Answer{Exit: 0, Stdout: []byte("ok")}
socket := anEngineThatClosesFirst(t, &ran)
a, err := Ask(context.Background(), socket, aLineTheSocketCannotHold())
if err == nil {
t.Fatalf("a request never wholly written came back as success: %+v", a)
}
if !strings.Contains(err.Error(), "not a refusal") {
t.Fatalf("the error does not say the answer was not a refusal: %v", err)
}
}
// Reading after a failed write never waits longer than the ask already allowed: a peer that never reads and
// never answers is given up on at the context's deadline, not later (novox/hq issue 444).
func TestAFailedWriteWaitsNoLongerThanTheDeadline(t *testing.T) {
socket := filepath.Join(t.TempDir(), "cli.sock")
l, err := net.Listen("unix", socket)
if err != nil {
t.Skipf("no unix socket here: %v", err)
}
t.Cleanup(func() { l.Close() })
held := make(chan net.Conn, 1)
go func() {
conn, err := l.Accept()
if err != nil {
return
}
held <- conn // neither read nor answered, nor closed, until the test ends
}()
t.Cleanup(func() {
select {
case c := <-held:
c.Close()
default:
}
})
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
start := time.Now()
_, err = Ask(ctx, socket, aLineTheSocketCannotHold())
waited := time.Since(start)
if err == nil {
t.Fatal("a peer that never read nor answered gave no error")
}
if !errors.Is(err, os.ErrDeadlineExceeded) {
t.Fatalf("the error is not the deadline: %v", err)
}
if waited > 3*time.Second {
t.Fatalf("waited %s with a deadline of 1s", waited)
}
}
+191
View File
@@ -0,0 +1,191 @@
// Package health is the answer a module's health tool gives, and how the node-engine reads it (novox/hq ADR 0240
// rule 2, ADR 0283).
//
// A health tool answers one of three:
//
// - healthy: everything the module runs works;
// - unhealthy: something is wrong, said in Why;
// - waits: nothing is wrong but a part that cannot work until the operator gives something — one of the module's
// own secrets, or one of its settings. Each Wait names exactly one of them, the part, and what the operator
// gives, in words with no path, address or value.
//
// The answer keeps `healthy` beside `state`, so a node-engine older than ADR 0283 reads a wait as not healthy, as
// it did before. An answer without `state` is read from `healthy`.
//
// The module writes its answer with Healthy, Unhealthy or Waiting, and the node-engine reads it with Read. Read
// never trusts a shape it cannot check: a wait it cannot read makes the answer unhealthy, saying why.
package health
import (
"encoding/json"
"fmt"
"regexp"
"strings"
)
// The three states an answer says.
const (
StateHealthy = "healthy"
StateUnhealthy = "unhealthy"
StateWaits = "waits"
)
// Answer is a health tool's answer.
type Answer struct {
// State is healthy, unhealthy or waits.
State string `json:"state"`
// Healthy is State == healthy, kept for a reader older than State.
Healthy bool `json:"healthy"`
// Why is the answer in one or more plain sentences.
Why string `json:"why"`
// Waits is what the module waits for, when State is waits; and, beside a fault, what it also waits for.
Waits []Wait `json:"waits,omitempty"`
}
// Wait is one thing a module waits for the operator to give: exactly one of Secret and Setting.
type Wait struct {
// Part is what waits, in words: "the source games".
Part string `json:"part"`
// Secret is one of the module's own secrets, by name (a member of a secret family by its full name).
Secret string `json:"secret,omitempty"`
// Setting is one of the module's settings, by name.
Setting string `json:"setting,omitempty"`
// What is what the operator gives, in words: "the password of the source games".
What string `json:"what"`
}
// Healthy is a healthy answer.
func Healthy(why string) Answer {
return Answer{State: StateHealthy, Healthy: true, Why: why}
}
// Unhealthy is an unhealthy answer. Waits may be given beside the fault: they are said, and excuse nothing.
func Unhealthy(why string, waits ...Wait) Answer {
return Answer{State: StateUnhealthy, Why: why, Waits: waits}
}
// Waiting is an answer that says nothing is wrong but what the operator has yet to give. With no wait it is
// unhealthy: a module that waits names what for.
func Waiting(why string, waits ...Wait) Answer {
if len(waits) == 0 {
return Unhealthy(orSaid(why, "it says it waits") + " (and names nothing it waits for)")
}
for _, w := range waits {
if err := w.Check(); err != nil {
return Unhealthy(orSaid(why, "it says it waits") + " (" + err.Error() + ")")
}
}
return Answer{State: StateWaits, Why: why, Waits: waits}
}
// name is a secret's or a setting's name: what a manifest may declare.
var name = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
// looksLikeAddress finds what the operator's words never carry: a URL, an IPv4 or IPv6 address, a host and port, a
// path (absolute, from a home or relative, on its own or after a bracket or a quote), a UNC path or a drive path.
// It cannot find a value typed in plain words ("the password hunter2"): a module never puts one there, and the
// words are its own, not the operator's.
var looksLikeAddress = regexp.MustCompile(strings.Join([]string{
`://`,
`\b[0-9]{1,3}(\.[0-9]{1,3}){3}\b`,
`[0-9A-Fa-f]{0,4}::[0-9A-Fa-f]{0,4}`,
`\b[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){3,}\b`,
`\b[A-Za-z0-9.-]+:[0-9]{1,5}\b`,
`(^|[\s(\[{"'\x60])[~.]{0,2}/`,
`\\\\`,
`\b[A-Za-z]:\\`,
}, "|"))
// Check says why a wait cannot be read, or nil.
func (w Wait) Check() error {
switch {
case w.Secret != "" && w.Setting != "":
return fmt.Errorf("a wait names both the secret %q and the setting %q; it names one", w.Secret, w.Setting)
case w.Secret == "" && w.Setting == "":
return fmt.Errorf("a wait names neither a secret nor a setting")
case w.Secret != "" && !name.MatchString(w.Secret):
return fmt.Errorf("a wait names the secret %q, which is not a name", w.Secret)
case w.Setting != "" && !name.MatchString(w.Setting):
return fmt.Errorf("a wait names the setting %q, which is not a name", w.Setting)
case strings.TrimSpace(w.What) == "":
return fmt.Errorf("a wait for %s does not say what the operator gives", w.Names())
case strings.TrimSpace(w.Part) == "":
return fmt.Errorf("a wait for %s does not say which part waits", w.Names())
}
for _, words := range []string{w.What, w.Part} {
if strings.ContainsAny(words, "\n\r") {
return fmt.Errorf("a wait for %s says more than one line", w.Names())
}
if looksLikeAddress.MatchString(words) {
return fmt.Errorf("a wait for %s says a path or an address, which the operator's words never carry", w.Names())
}
}
return nil
}
// Names is what the wait names, as "the secret x" or "the setting y".
func (w Wait) Names() string {
if w.Secret != "" {
return "the secret " + w.Secret
}
if w.Setting != "" {
return "the setting " + w.Setting
}
return "nothing"
}
// Read reads a health tool's result. An answer it cannot read at all is an error; an answer whose wait it cannot
// read is unhealthy, saying why, so a malformed wait never excuses anything.
func Read(result []byte) (Answer, error) {
var a Answer
if err := json.Unmarshal(result, &a); err != nil {
return Answer{}, fmt.Errorf("it answered something other than healthy or not: %w", err)
}
switch a.State {
case "":
if a.Healthy {
a.State = StateHealthy
} else {
a.State = StateUnhealthy
}
case StateHealthy:
if !a.Healthy {
return Unhealthy(fmt.Sprintf("it answered the state healthy and healthy false, which contradict each other (%s)",
orSaid(a.Why, "and said nothing more"))), nil
}
// A healthy module waits for nothing: a wait beside healthy is a contradiction, and is dropped.
a.Waits = nil
case StateUnhealthy:
a.Healthy = false
case StateWaits:
a.Healthy = false
if len(a.Waits) == 0 {
return Unhealthy(orSaid(a.Why, "it says it waits") + " (and names nothing it waits for)"), nil
}
for _, w := range a.Waits {
if err := w.Check(); err != nil {
return Unhealthy(orSaid(a.Why, "it says it waits") + " (" + err.Error() + ")"), nil
}
}
default:
return Unhealthy(fmt.Sprintf("it answered the state %q, which is none of healthy, unhealthy or waits", a.State)), nil
}
if a.State != StateWaits {
// Waits beside a fault are said and excuse nothing; one that cannot be read is dropped, not believed.
var kept []Wait
for _, w := range a.Waits {
if w.Check() == nil {
kept = append(kept, w)
}
}
a.Waits = kept
}
return a, nil
}
func orSaid(s, otherwise string) string {
if strings.TrimSpace(s) == "" {
return otherwise
}
return s
}
+150
View File
@@ -0,0 +1,150 @@
package health
import (
"encoding/json"
"strings"
"testing"
)
func roundTrip(t *testing.T, a Answer) Answer {
t.Helper()
b, err := json.Marshal(a)
if err != nil {
t.Fatal(err)
}
got, err := Read(b)
if err != nil {
t.Fatal(err)
}
return got
}
var password = Wait{Part: "the source games", Secret: "smb-password-games", What: "the password of the source games"}
func TestEachConstructorSaysItsStateAndKeepsHealthyForAnOlderReader(t *testing.T) {
for _, c := range []struct {
a Answer
state string
healthy bool
}{
{Healthy("all armed"), StateHealthy, true},
{Unhealthy("the share is unreachable"), StateUnhealthy, false},
{Waiting("the source games waits for its password", password), StateWaits, false},
} {
b, _ := json.Marshal(c.a)
var old struct {
Healthy bool `json:"healthy"`
Why string `json:"why"`
}
if err := json.Unmarshal(b, &old); err != nil || old.Healthy != c.healthy || old.Why == "" {
t.Fatalf("an older reader of %s reads %+v (%v)", b, old, err)
}
if got := roundTrip(t, c.a); got.State != c.state || got.Healthy != c.healthy {
t.Fatalf("%s read as %+v", b, got)
}
}
}
func TestAWaitIsReadWithWhatItNames(t *testing.T) {
got := roundTrip(t, Waiting("waits", password, Wait{Part: "the source games", Setting: "smb-users", What: "the username of the source games"}))
if got.State != StateWaits || len(got.Waits) != 2 || got.Waits[0].Secret != "smb-password-games" || got.Waits[1].Setting != "smb-users" {
t.Fatalf("read as %+v", got)
}
}
func TestAnAnswerWithoutStateIsReadFromHealthy(t *testing.T) {
for raw, want := range map[string]string{`{"healthy":true,"why":"ok"}`: StateHealthy, `{"healthy":false,"why":"down"}`: StateUnhealthy} {
got, err := Read([]byte(raw))
if err != nil || got.State != want {
t.Fatalf("%s read as %+v, %v", raw, got, err)
}
}
}
func TestAWaitThatCannotBeReadIsUnhealthyAndSaysWhy(t *testing.T) {
for name, c := range map[string]struct {
w []Wait
says string
}{
"no wait": {nil, "names nothing"},
"neither": {[]Wait{{Part: "p", What: "w"}}, "neither a secret nor a setting"},
"both": {[]Wait{{Part: "p", Secret: "a", Setting: "b", What: "w"}}, "both"},
"not a name": {[]Wait{{Part: "p", Secret: "Smb Password", What: "w"}}, "not a name"},
"no what": {[]Wait{{Part: "p", Secret: "a"}}, "does not say what"},
"no part": {[]Wait{{Secret: "a", What: "w"}}, "which part"},
"two lines": {[]Wait{{Part: "p", Secret: "a", What: "the password\nhunter2"}}, "more than one line"},
"an address": {[]Wait{{Part: "p", Secret: "a", What: "the password of 192.0.2.76"}}, "path or an address"},
"a url": {[]Wait{{Part: "p", Secret: "a", What: "the password of smb://host/share"}}, "path or an address"},
"a path": {[]Wait{{Part: "the source at /mnt/games", Secret: "a", What: "the password"}}, "path or an address"},
} {
b, _ := json.Marshal(Answer{State: StateWaits, Why: "it waits", Waits: c.w})
got, err := Read(b)
if err != nil {
t.Fatalf("%s: %v", name, err)
}
if got.State != StateUnhealthy || got.Healthy || !strings.Contains(got.Why, c.says) {
t.Fatalf("%s: read as %+v, want unhealthy saying %q", name, got, c.says)
}
}
}
func TestAnUnknownStateIsUnhealthy(t *testing.T) {
got, err := Read([]byte(`{"state":"fine","healthy":true}`))
if err != nil || got.State != StateUnhealthy || got.Healthy {
t.Fatalf("read as %+v, %v", got, err)
}
}
func TestWaitsBesideAFaultAreSaidAndExcuseNothing(t *testing.T) {
got := roundTrip(t, Unhealthy("the share is unreachable", password, Wait{Part: "p", What: "w"}))
if got.State != StateUnhealthy || len(got.Waits) != 1 {
t.Fatalf("read as %+v: the readable wait is kept, the other dropped, the state stays unhealthy", got)
}
if h := roundTrip(t, Answer{State: StateHealthy, Healthy: true, Why: "ok", Waits: []Wait{password}}); len(h.Waits) != 0 {
t.Fatalf("a healthy answer kept its waits: %+v", h)
}
}
func TestWaitingWithNothingIsUnhealthy(t *testing.T) {
if a := Waiting("it waits"); a.State != StateUnhealthy {
t.Fatalf("Waiting with no wait is %+v", a)
}
}
func TestNotAnAnswerIsAnError(t *testing.T) {
if _, err := Read([]byte(`"yes"`)); err == nil {
t.Fatal("a string read as an answer")
}
}
func TestEveryFormOfPathOrAddressIsRefused(t *testing.T) {
for _, words := range []string{
"the source (/mnt/games)", `the source "/mnt/games"`, "the folder ~/games", "the folder ./games",
"2001:db8::1", "fe80::1%eth0", "2001:0db8:0000:0000:0000:0000:0000:0001", "nas.lan:445", "192.0.2.7:445",
`\\nas\games`, `C:\Users\x`, "smb://nas/games", "198.51.100.4",
} {
w := Wait{Part: "the source games", Secret: "smb-password-games", What: "the password of " + words}
if err := w.Check(); err == nil {
t.Errorf("%q passed as words for the operator", words)
}
}
for _, words := range []string{"the password of the source games", "the username of the source games-2", "the API key, issued by the vendor"} {
w := Wait{Part: "the source games", Secret: "smb-password-games", What: words}
if err := w.Check(); err != nil {
t.Errorf("%q refused: %v", words, err)
}
}
}
func TestHealthyStateWithHealthyFalseIsUnhealthy(t *testing.T) {
got, err := Read([]byte(`{"state":"healthy","healthy":false,"why":"x"}`))
if err != nil || got.State != StateUnhealthy || !strings.Contains(got.Why, "contradict") {
t.Fatalf("read as %+v, %v", got, err)
}
}
func TestWaitingChecksItsWaits(t *testing.T) {
if a := Waiting("it waits", Wait{Part: "p", What: "w"}); a.State != StateUnhealthy || !strings.Contains(a.Why, "neither") {
t.Fatalf("Waiting with a malformed wait is %+v", a)
}
}
+123
View File
@@ -0,0 +1,123 @@
package stdio
import (
"encoding/json"
"fmt"
"time"
)
// Log — a module's record of operations on the bus, kept as long as the log is (novox/hq ADR 0297). Not the
// current value: that is state, and a log's state is its fold. Each entry is one operation on one key, its
// sequence in the log is its identity, and the order of the log is the order of the operations. A module
// declares each log it owns in its manifest (`logs`) and names it here as it named it there; a log is its
// owner's alone, and the runtime refuses, with the reason, one it did not issue.
// LogEntry is one operation on one key, as the log holds it.
type LogEntry struct {
Sequence uint64 `json:"sequence"`
Key string `json:"key"`
Value json.RawMessage `json:"value"`
At time.Time `json:"at"`
}
// LogPage is one page of a read: its entries, in order, the sequence to read on from (0 when nothing
// follows) and the log's last sequence when it was read.
type LogPage struct {
Entries []LogEntry `json:"entries"`
Next uint64 `json:"next"`
Last uint64 `json:"last"`
}
// LogInfo is how much a log holds: its entries and bytes, its cap in bytes, and its first and last sequence.
type LogInfo struct {
Entries uint64 `json:"entries"`
Bytes uint64 `json:"bytes"`
MaxBytes uint64 `json:"max_bytes"`
First uint64 `json:"first"`
Last uint64 `json:"last"`
}
// KeptLog is one log this module owns.
type KeptLog struct{ name string }
// Log is a log this module owns, by its local name.
func Log(name string) KeptLog { return KeptLog{name: name} }
const logTimeout = 30 * time.Second
func (l KeptLog) ask(verb string, params map[string]any) (json.RawMessage, error) {
c, err := live()
if err != nil {
return nil, err
}
params["log"] = l.name
return c.ask("mesh/log."+verb, params, logTimeout)
}
func (l KeptLog) append(params map[string]any) (uint64, error) {
raw, err := l.ask("append", params)
if err != nil {
return 0, err
}
var appended struct {
Sequence uint64 `json:"sequence"`
}
return appended.Sequence, json.Unmarshal(raw, &appended)
}
// Append writes an entry for key, whatever came before it, and returns its sequence. A key is one or more
// names of letters, digits, `-` and `_`, joined by `.`; a value is JSON of at most 256 KiB. A full log
// refuses the entry: it never drops an older one to make room.
func (l KeptLog) Append(key string, value any) (uint64, error) {
return l.append(map[string]any{"key": key, "value": value})
}
// AppendAt writes an entry for key only if the key's last entry is still at expect — the sequence the caller
// read, 0 for a key with no entry yet — and returns its sequence. When another entry for the key came in
// between, nothing is written and the error is ErrChanged, as for a lost State update: read again and
// decide again.
func (l KeptLog) AppendAt(key string, value any, expect uint64) (uint64, error) {
return l.append(map[string]any{"key": key, "value": value, "expect": expect})
}
// Read is the entries from the sequence from on, oldest first, at most limit of them (0 is the runtime's
// page, 100; it gives at most 1000). keys narrows it: a key, with `*` for one name and `>` for the rest;
// empty is every key. Read on from the page's Next until it is 0.
func (l KeptLog) Read(from uint64, keys string, limit int) (*LogPage, error) {
if limit < 0 {
return nil, fmt.Errorf("a read of %s asks for at least no entries: limit %d", l.name, limit)
}
params := map[string]any{"from": from}
if keys != "" {
params["keys"] = keys
}
if limit > 0 {
params["limit"] = limit
}
raw, err := l.ask("read", params)
if err != nil {
return nil, err
}
var p LogPage
return &p, json.Unmarshal(raw, &p)
}
// Last is a key's last entry, or nil when the key has none.
func (l KeptLog) Last(key string) (*LogEntry, error) {
raw, err := l.ask("last", map[string]any{"key": key})
if err != nil || len(raw) == 0 || string(raw) == "null" {
return nil, err
}
var e LogEntry
return &e, json.Unmarshal(raw, &e)
}
// Info is how much the log holds and how much it may.
func (l KeptLog) Info() (*LogInfo, error) {
raw, err := l.ask("info", map[string]any{})
if err != nil {
return nil, err
}
var i LogInfo
return &i, json.Unmarshal(raw, &i)
}
+354
View File
@@ -0,0 +1,354 @@
package stdio
import (
"bufio"
"encoding/json"
"errors"
"fmt"
"io"
"strings"
"sync"
"testing"
"time"
)
// logRuntime is the runtime's side of mesh/log.append, read, last and info as the bus does them (novox/hq
// ADR 0297): one sequence per entry across the log, an append with expect refused unless the key's last
// entry is still at it (0 for a key with none), that refusal answered with CodeChanged as a lost state
// update is, and a read paged by its limit with the sequence to read on from. asked keeps every ask's
// method and params, as the bundle sent them.
type logRuntime struct {
mu sync.Mutex
entries []LogEntry
asked []message
}
func (r *logRuntime) last(key string) uint64 {
for i := len(r.entries) - 1; i >= 0; i-- {
if r.entries[i].Key == key {
return r.entries[i].Sequence
}
}
return 0
}
// matches is a key pattern as the runtime reads it: `*` one name, `>` the rest.
func matches(pattern, key string) bool {
if pattern == "" {
return true
}
p, k := strings.Split(pattern, "."), strings.Split(key, ".")
for i, t := range p {
if t == ">" {
return len(k) > i
}
if i >= len(k) || (t != "*" && t != k[i]) {
return false
}
}
return len(p) == len(k)
}
func (r *logRuntime) answer(m message) map[string]any {
var p struct {
Log string `json:"log"`
Key string `json:"key"`
Value json.RawMessage `json:"value"`
Expect *uint64 `json:"expect"`
From uint64 `json:"from"`
Keys string `json:"keys"`
Limit int `json:"limit"`
}
_ = json.Unmarshal(m.Params, &p)
r.mu.Lock()
defer r.mu.Unlock()
r.asked = append(r.asked, m)
if p.Log != "changes" {
return map[string]any{"error": map[string]any{"code": -32000, "message": "issues was issued no log " + p.Log}}
}
switch strings.TrimPrefix(m.Method, "mesh/log.") {
case "append":
if p.Expect != nil && r.last(p.Key) != *p.Expect {
return map[string]any{"error": map[string]any{"code": CodeChanged, "message": p.Key + ": the key was written by another writer first"}}
}
seq := uint64(len(r.entries)) + 1
r.entries = append(r.entries, LogEntry{Sequence: seq, Key: p.Key, Value: p.Value,
At: time.Date(2026, 10, 11, 18, 0, int(seq), 0, time.UTC)})
return map[string]any{"result": map[string]any{"sequence": seq}}
case "read":
limit := p.Limit
if limit == 0 {
limit = 100
}
page := map[string]any{"entries": []LogEntry{}, "next": 0, "last": len(r.entries)}
var got []LogEntry
for _, e := range r.entries {
if e.Sequence < p.From || !matches(p.Keys, e.Key) {
continue
}
if len(got) == limit {
page["next"] = e.Sequence
break
}
got = append(got, e)
}
if got != nil {
page["entries"] = got
}
return map[string]any{"result": page}
case "last":
seq := r.last(p.Key)
if seq == 0 {
return map[string]any{"result": nil}
}
return map[string]any{"result": r.entries[seq-1]}
case "info":
var bytes int
for _, e := range r.entries {
bytes += len(e.Value)
}
info := map[string]any{"entries": len(r.entries), "bytes": bytes, "max_bytes": 1 << 30, "first": 0, "last": len(r.entries)}
if len(r.entries) > 0 {
info["first"] = 1
}
return map[string]any{"result": info}
}
return map[string]any{"error": map[string]any{"code": -32601, "message": "no " + m.Method}}
}
// logging serves a bundle whose one tool, "log", runs run against r, answering each mesh/log ask beside
// the loop as the runtime does. It returns what the tool answered.
func logging(t *testing.T, r *logRuntime, run func() (any, error)) map[string]any {
t.Helper()
t.Setenv(ServedAs, "issues")
inR, inW := io.Pipe()
outR, outW := io.Pipe()
go func() {
_ = ServeOn("", []Tool{{Name: "log", Run: func(map[string]any) (any, error) { return run() }}}, inR, outW)
}()
var wmu sync.Mutex
send := func(m map[string]any) {
m["jsonrpc"] = "2.0"
b, _ := json.Marshal(m)
wmu.Lock()
defer wmu.Unlock()
_, _ = inW.Write(append(b, '\n'))
}
done := make(chan map[string]any, 1)
go func() {
lines := bufio.NewScanner(outR)
lines.Buffer(make([]byte, 1<<20), 1<<24)
for lines.Scan() {
var m message
if json.Unmarshal(lines.Bytes(), &m) != nil {
continue
}
if strings.HasPrefix(m.Method, "mesh/log.") {
go func(m message) {
a := r.answer(m)
a["id"] = m.ID
send(a)
}(m)
continue
}
var answer map[string]any
_ = json.Unmarshal(lines.Bytes(), &answer)
if answer["id"] == float64(1) {
done <- answer
return
}
}
}()
send(map[string]any{"id": 1, "method": "tools/call", "params": map[string]any{"name": "log"}})
t.Cleanup(func() { _ = inW.Close() })
select {
case a := <-done:
return a
case <-time.After(10 * time.Second):
t.Fatal("the bundle did not answer")
return nil
}
}
// params is what the bundle sent with its n-th ask, and the ask's method.
func (r *logRuntime) params(t *testing.T, n int) (string, map[string]any) {
t.Helper()
r.mu.Lock()
defer r.mu.Unlock()
if n >= len(r.asked) {
t.Fatalf("the bundle asked %d times, not %d", len(r.asked), n+1)
}
var p map[string]any
_ = json.Unmarshal(r.asked[n].Params, &p)
return r.asked[n].Method, p
}
// A bundle appends to, reads, and measures its log through the runtime (novox/hq ADR 0297): each verb is
// asked as mesh/log.<verb> naming the log, its answer is handed back whole, a key with no entry is nil,
// and a read pages on from Next until it is 0.
func TestABundleKeepsALogThroughTheRuntime(t *testing.T) {
r := &logRuntime{}
var (
first, second, third uint64
pages []*LogPage
last, none *LogEntry
info *LogInfo
narrowed *LogPage
)
got := logging(t, r, func() (any, error) {
changes := Log("changes")
var err error
if first, err = changes.Append("401", map[string]any{"op": "opened", "by": "fix@g14"}); err != nil {
return nil, err
}
if second, err = changes.Append("402", map[string]any{"op": "opened"}); err != nil {
return nil, err
}
if third, err = changes.AppendAt("401", map[string]any{"op": "moved", "to": "fixing"}, first); err != nil {
return nil, err
}
for _, k := range []string{"403", "404", "405"} {
if _, err = changes.Append(k, map[string]any{"op": "opened"}); err != nil {
return nil, err
}
}
for from := uint64(1); ; {
p, err := changes.Read(from, "", 2)
if err != nil {
return nil, err
}
pages = append(pages, p)
if p.Next == 0 {
break
}
from = p.Next
}
if narrowed, err = changes.Read(0, "401", 0); err != nil {
return nil, err
}
if last, err = changes.Last("401"); err != nil {
return nil, err
}
if none, err = changes.Last("999"); err != nil {
return nil, err
}
info, err = changes.Info()
return "done", err
})
if out, isError := text(t, got); isError || out != `"done"` {
t.Fatalf("the tool answered %s", out)
}
if first != 1 || second != 2 || third != 3 {
t.Fatalf("appended at %d, %d, %d", first, second, third)
}
// Asked as the contract names them: the verb, the log, and only what was given.
method, p := r.params(t, 0)
if method != "mesh/log.append" || p["log"] != "changes" || p["key"] != "401" || p["value"].(map[string]any)["by"] != "fix@g14" {
t.Fatalf("an append asked %s %v", method, p)
}
if _, has := p["expect"]; has {
t.Fatalf("an Append without expect named one: %v", p)
}
if method, p = r.params(t, 2); method != "mesh/log.append" || p["expect"] != float64(1) {
t.Fatalf("an AppendAt asked %s %v", method, p)
}
if method, p = r.params(t, 6); method != "mesh/log.read" || p["from"] != float64(1) || p["limit"] != float64(2) || p["keys"] != nil {
t.Fatalf("a read asked %s %v", method, p)
}
// Paged two at a time through six entries: three pages, every entry once, in order.
if len(pages) != 3 {
t.Fatalf("read %d pages, not 3", len(pages))
}
var seqs []uint64
for _, pg := range pages {
if pg.Last != 6 {
t.Fatalf("a page said the last sequence is %d", pg.Last)
}
for _, e := range pg.Entries {
seqs = append(seqs, e.Sequence)
}
}
if fmt.Sprint(seqs) != "[1 2 3 4 5 6]" || pages[0].Next != 3 || pages[2].Next != 0 {
t.Fatalf("paged %v, next %d then %d", seqs, pages[0].Next, pages[2].Next)
}
if e := pages[1].Entries[0]; e.Key != "401" || string(e.Value) != `{"op":"moved","to":"fixing"}` ||
!e.At.Equal(time.Date(2026, 10, 11, 18, 0, 3, 0, time.UTC)) {
t.Fatalf("an entry read as %+v", e)
}
// Narrowed to a key, with the runtime's page: no limit sent.
method, p = r.params(t, 9)
if method != "mesh/log.read" || p["keys"] != "401" || p["limit"] != nil {
t.Fatalf("a narrowed read asked %s %v", method, p)
}
if len(narrowed.Entries) != 2 || narrowed.Entries[0].Sequence != 1 || narrowed.Entries[1].Sequence != 3 || narrowed.Next != 0 {
t.Fatalf("narrowed to 401: %+v", narrowed)
}
if last == nil || last.Sequence != 3 || last.Key != "401" {
t.Fatalf("the last of 401 is %+v", last)
}
if method, p = r.params(t, 10); method != "mesh/log.last" || p["key"] != "401" {
t.Fatalf("a last asked %s %v", method, p)
}
if none != nil {
t.Fatalf("a key with no entry has a last: %+v", none)
}
if info == nil || info.Entries != 6 || info.MaxBytes != 1<<30 || info.First != 1 || info.Last != 6 || info.Bytes == 0 {
t.Fatalf("the log's info is %+v", info)
}
if method, p = r.params(t, 12); method != "mesh/log.info" || p["log"] != "changes" || len(p) != 1 {
t.Fatalf("an info asked %s %v", method, p)
}
}
// An AppendAt on a stale expect is ErrChanged and writes nothing: another entry for the key came in
// between. Expect 0 is a key with no entry yet, and is ErrChanged once the key has one. A log not issued
// is refused with the runtime's reason, and is not ErrChanged.
func TestAnAppendAtAStaleSequenceIsErrChangedAndWritesNothing(t *testing.T) {
r := &logRuntime{}
var errs []error
got := logging(t, r, func() (any, error) {
changes := Log("changes")
read, err := changes.AppendAt("401", map[string]any{"op": "opened"}, 0)
if err != nil {
return nil, err
}
// Another writer is first.
if _, err := changes.Append("401", map[string]any{"op": "noted"}); err != nil {
return nil, err
}
_, stale := changes.AppendAt("401", map[string]any{"op": "moved"}, read)
_, again := changes.AppendAt("401", map[string]any{"op": "opened"}, 0)
_, other := Log("elsewhere").Append("401", map[string]any{})
errs = []error{stale, again, other}
return "done", nil
})
if out, isError := text(t, got); isError || out != `"done"` {
t.Fatalf("the tool answered %s", out)
}
if !errors.Is(errs[0], ErrChanged) || !errors.Is(errs[1], ErrChanged) {
t.Fatalf("a stale expect answered %v and %v, not ErrChanged", errs[0], errs[1])
}
if errs[2] == nil || errors.Is(errs[2], ErrChanged) || !strings.Contains(errs[2].Error(), "no log elsewhere") {
t.Fatalf("a log not issued answered %v", errs[2])
}
if len(r.entries) != 2 {
t.Fatalf("the log holds %d entries, not 2: a refused append wrote", len(r.entries))
}
}
// A read asking for fewer than no entries is refused before the runtime is asked.
func TestAReadOfANegativeLimitIsRefused(t *testing.T) {
r := &logRuntime{}
var err error
logging(t, r, func() (any, error) {
_, err = Log("changes").Read(0, "", -1)
return "done", nil
})
if err == nil || len(r.asked) != 0 {
t.Fatalf("a negative limit answered %v after %d asks", err, len(r.asked))
}
}
+25
View File
@@ -31,6 +31,16 @@ type StateChange struct {
Current bool `json:"current"`
}
// StateRevision is one value a bucket still keeps for a key: what was written, at which revision, by which
// operation ("put" or "delete", whose value is null) and when (novox/hq ADR 0307).
type StateRevision struct {
Key string `json:"key"`
Value json.RawMessage `json:"value"`
Revision uint64 `json:"revision"`
Op string `json:"op"`
At time.Time `json:"at"`
}
// KeptState is one state this module keeps, or reads.
type KeptState struct{ name string }
@@ -58,6 +68,21 @@ func (s KeptState) Get(key string) (*StateEntry, error) {
return &e, json.Unmarshal(raw, &e)
}
// History is every value the bucket still keeps for key, oldest first — as many as the state declared it
// keeps, deletes included — and empty for a key it holds nothing for (novox/hq ADR 0307). A read, like Get:
// the owner's instances and its readers may ask it, and it writes nothing.
func (s KeptState) History(key string) ([]StateRevision, error) {
raw, err := s.ask("history", map[string]any{"key": key})
if err != nil {
return nil, err
}
revisions := []StateRevision{}
if len(raw) == 0 || string(raw) == "null" {
return revisions, nil
}
return revisions, json.Unmarshal(raw, &revisions)
}
// Put writes a key — the owner's instances only — and returns the revision written.
func (s KeptState) Put(key string, value any) (uint64, error) {
raw, err := s.ask("put", map[string]any{"key": key, "value": value})
+142
View File
@@ -0,0 +1,142 @@
package stdio
import (
"bufio"
"encoding/json"
"io"
"strings"
"sync"
"testing"
"time"
)
// historying serves a bundle whose one tool, "history", runs run, answering each mesh/state ask with
// answer beside the loop, as the runtime does; it returns what the bundle asked.
func historying(t *testing.T, answer func(message) map[string]any, run func()) []message {
t.Helper()
t.Setenv(ServedAs, "issues")
inR, inW := io.Pipe()
outR, outW := io.Pipe()
go func() {
_ = ServeOn("", []Tool{{Name: "history", Run: func(map[string]any) (any, error) { run(); return "done", nil }}}, inR, outW)
}()
var wmu, amu sync.Mutex
var asked []message
send := func(m map[string]any) {
m["jsonrpc"] = "2.0"
b, _ := json.Marshal(m)
wmu.Lock()
defer wmu.Unlock()
_, _ = inW.Write(append(b, '\n'))
}
done := make(chan struct{})
go func() {
lines := bufio.NewScanner(outR)
for lines.Scan() {
var m message
if json.Unmarshal(lines.Bytes(), &m) != nil {
continue
}
if strings.HasPrefix(m.Method, "mesh/state.") {
amu.Lock()
asked = append(asked, m)
amu.Unlock()
a := answer(m)
a["id"] = m.ID
send(a)
continue
}
if m.Method == "" {
close(done)
return
}
}
}()
send(map[string]any{"id": 1, "method": "tools/call", "params": map[string]any{"name": "history"}})
t.Cleanup(func() { _ = inW.Close() })
select {
case <-done:
case <-time.After(10 * time.Second):
t.Fatal("the bundle did not answer")
}
amu.Lock()
defer amu.Unlock()
return asked
}
// History asks mesh/state.history with the state and the key alone, and hands back every kept value oldest
// first, a delete with its null value; nothing kept is an empty history; a refusal is the runtime's error
// (novox/hq ADR 0307).
func TestHistoryIsEveryKeptValueOldestFirst(t *testing.T) {
kept := []map[string]any{
{"key": "401", "value": map[string]any{"status": "open"}, "revision": 4, "op": "put", "at": "2026-10-10T19:46:00Z"},
{"key": "401", "value": map[string]any{"status": "fixing"}, "revision": 9, "op": "put", "at": "2026-10-11T08:01:02Z"},
{"key": "401", "value": nil, "revision": 12, "op": "delete", "at": "2026-10-11T09:30:00+02:00"},
}
var got, none, null []StateRevision
var refused error
asked := historying(t, func(m message) map[string]any {
var p map[string]any
_ = json.Unmarshal(m.Params, &p)
switch {
case p["state"] != "issues":
return map[string]any{"error": map[string]any{"code": -32000, "message": "issues was issued no state " + p["state"].(string)}}
case p["key"] == "401":
return map[string]any{"result": kept}
case p["key"] == "402":
return map[string]any{"result": nil}
}
return map[string]any{"result": []any{}}
}, func() {
var err error
if got, err = State("issues").History("401"); err != nil {
t.Errorf("history of 401: %v", err)
}
if none, err = State("issues").History("999"); err != nil {
t.Errorf("history of 999: %v", err)
}
if null, err = State("issues").History("402"); err != nil {
t.Errorf("history of 402: %v", err)
}
var h []StateRevision
h, refused = State("elsewhere.issues").History("401")
if h != nil {
t.Errorf("a refused history handed back %v", h)
}
})
if len(asked) != 4 {
t.Fatalf("asked %d times, not 4", len(asked))
}
var p map[string]any
_ = json.Unmarshal(asked[0].Params, &p)
if asked[0].Method != "mesh/state.history" || p["state"] != "issues" || p["key"] != "401" || len(p) != 2 {
t.Fatalf("asked %s %v", asked[0].Method, p)
}
if len(got) != 3 {
t.Fatalf("history of 401 is %d values, not 3: %+v", len(got), got)
}
want := []struct {
rev uint64
op string
value string
at time.Time
}{
{4, "put", `{"status":"open"}`, time.Date(2026, 10, 10, 19, 46, 0, 0, time.UTC)},
{9, "put", `{"status":"fixing"}`, time.Date(2026, 10, 11, 8, 1, 2, 0, time.UTC)},
{12, "delete", `null`, time.Date(2026, 10, 11, 7, 30, 0, 0, time.UTC)},
}
for i, w := range want {
r := got[i]
if r.Key != "401" || r.Revision != w.rev || r.Op != w.op || string(r.Value) != w.value || !r.At.Equal(w.at) {
t.Fatalf("value %d is %+v, not %+v", i, r, w)
}
}
if none == nil || len(none) != 0 || null == nil || len(null) != 0 {
t.Fatalf("nothing kept read as %v and %v, not an empty history", none, null)
}
if refused == nil || !strings.Contains(refused.Error(), "issued no state elsewhere.issues") {
t.Fatalf("a state not issued answered %v", refused)
}
}
+7 -4
View File
@@ -39,7 +39,8 @@ type Tool struct {
Description string
// Input is the JSON schema of the arguments; nil is a tool that takes nothing.
Input map[string]any
Run func(args map[string]any) (any, error)
// Run answers one call. Who called is CallerOf(args): the bus user the runtime proved, or Unproven.
Run func(args map[string]any) (any, error)
}
type message struct {
@@ -223,6 +224,8 @@ func ServeOn(name string, tools []Tool, in io.Reader, out io.Writer) error {
var p struct {
Name string `json:"name"`
Arguments map[string]any `json:"arguments"`
// Meta is the runtime's, never the caller's: who called, taken from the subject (CallerOf).
Meta map[string]any `json:"_meta"`
}
_ = json.Unmarshal(m.Params, &p)
t, ok := byName[p.Name]
@@ -232,18 +235,18 @@ func ServeOn(name string, tools []Tool, in io.Reader, out io.Writer) error {
}
// Beside the loop, never in it: a tool that emits waits for the runtime's answer, which
// arrives on the line this loop reads next — and calls do not queue behind a slow one.
go func(id any, t Tool, args map[string]any) {
go func(id any, t Tool, args map[string]any, caller string) {
if args == nil {
args = map[string]any{}
}
result, err := t.Run(args)
result, err := runAs(t, caller, args)
if err != nil {
c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": err.Error()}}, "isError": true}})
return
}
text, _ := json.Marshal(result)
c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": string(text)}}}})
}(id, t, p.Arguments)
}(id, t, p.Arguments, callerIn(p.Meta))
case "mesh/event":
// One event the runtime read from this module's consumer (ADR 0198), answered once every
// handler it is for has taken it; an error is answered as one, so the runtime does not