diff --git a/go/busretry/busretry.go b/go/busretry/busretry.go index e4814ab2..dd39dd4c 100644 --- a/go/busretry/busretry.go +++ b/go/busretry/busretry.go @@ -17,8 +17,11 @@ import ( "context" "errors" "fmt" + "math/rand/v2" "os" + "sort" "strings" + "sync" "time" "github.com/nats-io/nats.go" @@ -36,10 +39,203 @@ var ( // in a process shares, so a test sets them only through it, as t.Cleanup(busretry.Waits(...)): a test that set them // and left them set shortened the next test's bound to milliseconds, and a loaded check machine overran it (the check // of release sdk1, 2026-11-02). A bound a test waits on to succeed is seconds: no slow machine reaches it. +// It sets the kept-call pace (KeptPace) to first and most too, so a test of a kept call waits milliseconds. func Waits(bound, first, most time.Duration) (restore func()) { was := [3]time.Duration{Bound, FirstWait, MostWait} + wasPace := KeptPace Bound, FirstWait, MostWait = bound, first, most - return func() { Bound, FirstWait, MostWait = was[0], was[1], was[2] } + KeptPace = Pace{First: first, Max: most} + return func() { Bound, FirstWait, MostWait, KeptPace = was[0], was[1], was[2], wasPace } +} + +// Pace is the kept-call form's pace (design 47 H2 §775): on a transport fault the call is made again after First, +// the wait doubling to at most Max, each wait drawn within 20 % of its value so many callers do not call in step. +type Pace struct{ First, Max time.Duration } + +// The settings every module using the kept-call form declares, with DefaultPace's values as their defaults (§775). +const ( + PaceFirstSetting = "kept-call-pace-first" + PaceMaxSetting = "kept-call-pace-max" +) + +// DefaultPace is the pace a module's settings name when they name none (§775): 1 s doubling to 30 s, so a holder +// between two lives (a restart takes 20 to 50 s) is met within one minute without a call a second. +var DefaultPace = Pace{First: time.Second, Max: 30 * time.Second} + +// KeptPace is the pace of every kept call this process makes: DefaultPace until the process reads its settings. +var KeptPace = DefaultPace + +// The clock and the sleep the paced form waits on; a test of this package replaces both, so nothing sleeps. +var ( + now = time.Now + sleep = time.Sleep +) + +// jittered is w drawn within 20 % of its value. +func jittered(w time.Duration) time.Duration { + return time.Duration(float64(w) * (0.8 + 0.4*rand.Float64())) +} + +// Kept names one kept call of the paced form (design 47 H2 §775): the seat and the verb it asks (named in the journal +// line), the ask's id (named among the asks waiting), the caller's bound (zero is Bound) and the pace (zero is +// KeptPace). Open, when given, makes it asked again only while its key is open (DoKept). Logf is the journal; nil +// writes to standard error. +type Kept struct { + Seat, Verb, Ask string + Bound time.Duration + Pace Pace + Open *Open + Logf func(format string, args ...any) +} + +// Try is one call of a kept call that met a transport fault: when it was made and the words it met. +type Try struct { + At time.Time + Words string +} + +// Unanswered is a kept call's end past its caller's bound (§775): every call's time and words, so the caller's +// could-not-run or could-not-be-performed names them. It wraps the last fault, so Undelivered and TimedOut read it. +type Unanswered struct { + Seat, Verb, Ask string + Bound time.Duration + Tries []Try + Last error +} + +func (u *Unanswered) Error() string { + var b strings.Builder + fmt.Fprintf(&b, "%s.%s", u.Seat, u.Verb) + if u.Ask != "" { + fmt.Fprintf(&b, " (ask %s)", u.Ask) + } + fmt.Fprintf(&b, " unanswered within its bound of %s, called %d times:", u.Bound, len(u.Tries)) + for i, t := range u.Tries { + if i > 0 { + b.WriteString(";") + } + fmt.Fprintf(&b, " %s %s", t.At.UTC().Format("15:04:05.000"), t.Words) + } + return b.String() +} + +func (u *Unanswered) Unwrap() error { return u.Last } + +// Fault says err is a transport fault of a kept call (§775): a request that reached no one, a call's own deadline +// passing; a callee's refusal never is. +func Fault(err error) bool { return TimedOut(err) || Undelivered(err) } + +// DoPaced makes a kept call through try (design 47 H2 §775): on a transport fault (Fault) it calls again at k's pace, +// each wait jittered, until the caller's bound, writing one journal line per seat at the first fault and then at most +// once a minute (the seat, the verb, the asks waiting and the count of calls). Past the bound it returns the last +// answer with an *Unanswered naming every call; a refusal of what was asked returns at once. +func DoPaced[T any](k Kept, try func() (T, error)) (T, error) { + bound, pace := k.Bound, k.Pace + if bound <= 0 { + bound = Bound + } + if pace.First <= 0 { + pace.First = KeptPace.First + } + if pace.Max <= 0 { + pace.Max = KeptPace.Max + } + logf := k.Logf + if logf == nil { + logf = func(f string, a ...any) { fmt.Fprintf(os.Stderr, "[mesh-sdk] "+f+"\n", a...) } + } + start, wait := now(), pace.First + var tries []Try + waiting := false + defer func() { + if waiting { + journal.done(k.Seat, k.Ask) + } + }() + for { + at := now() + v, err := try() + if !Fault(err) || (k.Open != nil && !k.Open.stillOpen()) { + return v, err + } + tries = append(tries, Try{At: at, Words: err.Error()}) + if !waiting { + journal.wait(k.Seat, k.Ask) + waiting = true + } + journal.fault(k.Seat, k.Verb, logf) + left := bound - now().Sub(start) + if left <= 0 { + return v, &Unanswered{Seat: k.Seat, Verb: k.Verb, Ask: k.Ask, Bound: bound, Tries: tries, Last: err} + } + sleep(min(jittered(wait), left)) + wait = min(wait*2, pace.Max) + } +} + +// journal holds, per seat, the asks of this process waiting on it through a fault, the calls made since its last +// line and when that line was written: one line per seat at the first fault, then at most once a minute (§775). +var journal = &faults{seats: map[string]*seatFaults{}} + +type faults struct { + mu sync.Mutex + seats map[string]*seatFaults +} + +type seatFaults struct { + asks map[string]int + calls int + last time.Time +} + +func (f *faults) of(seat string) *seatFaults { + s := f.seats[seat] + if s == nil { + s = &seatFaults{asks: map[string]int{}} + f.seats[seat] = s + } + return s +} + +func (f *faults) wait(seat, ask string) { + f.mu.Lock() + defer f.mu.Unlock() + f.of(seat).asks[ask]++ +} + +func (f *faults) done(seat, ask string) { + f.mu.Lock() + defer f.mu.Unlock() + s := f.of(seat) + if s.asks[ask]--; s.asks[ask] <= 0 { + delete(s.asks, ask) + } +} + +func (f *faults) fault(seat, verb string, logf func(string, ...any)) { + f.mu.Lock() + s := f.of(seat) + s.calls++ + t := now() + if !s.last.IsZero() && t.Sub(s.last) < time.Minute { + f.mu.Unlock() + return + } + s.last = t + var asks []string + n := 0 + for a, c := range s.asks { + n += c + if a != "" { + asks = append(asks, a) + } + } + sort.Strings(asks) + calls := s.calls + s.calls = 0 + f.mu.Unlock() + logf("kept call: the seat %s does not answer (%s): %d asks waiting %v, %d calls since the last line; called "+ + "again at the kept-call pace until each caller's bound", seat, verb, n, asks, calls) } // Undelivered says err means the request reached no one: no responders, JetStream not enabled (for the account), or diff --git a/go/busretry/busretry_test.go b/go/busretry/busretry_test.go index 53883f6f..dd598c2e 100644 --- a/go/busretry/busretry_test.go +++ b/go/busretry/busretry_test.go @@ -110,8 +110,87 @@ func subAKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen(t *testing.T) { } } +// fakeClock replaces the paced form's clock and sleep for one test: a sleep moves the clock, nothing sleeps. +func fakeClock(t *testing.T) (slept *[]time.Duration) { + at := time.Date(2026, 11, 21, 22, 0, 0, 0, time.UTC) + waits := []time.Duration{} + wasNow, wasSleep, wasJournal := now, sleep, journal + now = func() time.Time { return at } + sleep = func(d time.Duration) { waits = append(waits, d); at = at.Add(d) } + journal = &faults{seats: map[string]*seatFaults{}} + t.Cleanup(func() { now, sleep, journal = wasNow, wasSleep, wasJournal }) + return &waits +} + +// Design 47 H2 §775: the kept call is paced from 1 s doubling to 30 s, each wait within 20 %; met by no responders twice +// and then answered it returns the answer and writes one journal line; past its caller's bound it returns every try; +// a refusal returns at once; the journal says a seat at most once a minute. +func subAKeptCallIsPaced(t *testing.T) { + t.Run("no responders twice, then answered: the answer and one line", func(t *testing.T) { + slept := fakeClock(t) + tries, logs := 0, []string{} + v, err := DoPaced(Kept{Seat: "mesh-builds", Verb: "build", Ask: "a1", Bound: time.Minute, + Logf: func(f string, a ...any) { logs = append(logs, fmt.Sprintf(f, a...)) }}, func() (int, error) { + if tries++; tries <= 2 { + return 0, nats.ErrNoResponders + } + return 7, nil + }) + if v != 7 || err != nil || tries != 3 || len(logs) != 1 || !strings.Contains(logs[0], "mesh-builds") || + !strings.Contains(logs[0], "build") || !strings.Contains(logs[0], "[a1]") { + t.Fatalf("%d, %v after %d tries, logs %q", v, err, tries, logs) + } + for i, base := range []time.Duration{time.Second, 2 * time.Second} { + if w := (*slept)[i]; w < base*8/10 || w > base*12/10 { + t.Errorf("wait %d is %s, not within 20 %% of %s", i, w, base) + } + } + }) + t.Run("past its bound: every try", func(t *testing.T) { + slept := fakeClock(t) + tries := 0 + _, err := DoPaced(Kept{Seat: "mesh-wants", Verb: "compose-candidate", Ask: "a2", Bound: 3 * time.Minute, + Logf: func(string, ...any) {}}, func() (int, error) { tries++; return 0, context.DeadlineExceeded }) + var u *Unanswered + if !errors.As(err, &u) || len(u.Tries) != tries || tries < 5 || !TimedOut(err) || + !strings.Contains(err.Error(), "context deadline exceeded") { + t.Fatalf("%d tries: %v", tries, err) + } + for _, w := range *slept { + if w > 30*time.Second*12/10 { + t.Errorf("a wait of %s passes the pace's most", w) + } + } + }) + t.Run("a refusal returns at once", func(t *testing.T) { + slept := fakeClock(t) + tries := 0 + _, err := DoPaced(Kept{Seat: "git", Verb: "merge"}, func() (int, error) { tries++; return 0, &Answered{Words: "refused"} }) + if tries != 1 || len(*slept) != 0 || err == nil { + t.Fatalf("%d tries, %v", tries, err) + } + }) + t.Run("one line per seat a minute", func(t *testing.T) { + fakeClock(t) + logs := 0 + k := Kept{Seat: "mesh-builds", Verb: "build", Bound: 10 * time.Second, Logf: func(string, ...any) { logs++ }} + fail := func() (int, error) { return 0, nats.ErrNoResponders } + _, _ = DoPaced(k, fail) + _, _ = DoPaced(k, fail) + if logs != 1 { + t.Fatalf("%d lines within a minute", logs) + } + k.Bound = 2 * time.Minute + _, _ = DoPaced(k, fail) + if logs < 2 { + t.Fatalf("%d lines past a minute", logs) + } + }) +} + // TestABusThatAnswersNothingIsWaitedOut runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest. func TestABusThatAnswersNothingIsWaitedOut(t *testing.T) { t.Run("ABusThatAnswersNothingIsWaitedOut", subABusThatAnswersNothingIsWaitedOut) t.Run("AKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen", subAKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen) + t.Run("AKeptCallIsPaced", subAKeptCallIsPaced) } diff --git a/go/caller.go b/go/caller.go index d503c586..94de4fa1 100644 --- a/go/caller.go +++ b/go/caller.go @@ -28,11 +28,19 @@ var busUser = regexp.MustCompile(`^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$`) // buscalls.MetaCall, written here too so this package imports nothing of buscalls. const MetaCall = "mesh/call" +// AskHeader is the bus header a kept call carries its ask's id in (design 47 H2 §775; H-A-351): a holder in a process +// reads it with process.AskOf, and the tool runner copies it into a `tools/call`'s `_meta` under MetaAsk, read with +// AskIDOf. +const AskHeader = "x-ask" + +// MetaAsk is where in a `tools/call`'s `_meta` the runtime names the ask id the call carried in AskHeader (H-A-351). +const MetaAsk = "mesh/ask" + // callID is the shape of a call's id: one subject-safe token, as the runtime makes it. Anything else reads as none. var callID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,128}$`) // inFlight is what the runtime said of one call while its tool runs. -type inFlight struct{ caller, call string } +type inFlight struct{ caller, call, ask string } // calls holds the caller and the id of every call while its tool runs, by the arguments map that call was handed. var calls sync.Map // unsafe.Pointer → inFlight @@ -75,6 +83,27 @@ func callIn(meta map[string]any) string { return "" } +// AskIDOf is the ask id the call that was handed args carried (design 47 H2 §775; H-A-351): what the kept call set in +// AskHeader and the runtime named under MetaAsk, by which a holder takes the ask once. Empty when the call +// carried none. Valid while the tool runs. +func AskIDOf(args map[string]any) string { + if args == nil { + return "" + } + if c, ok := calls.Load(argsKey(args)); ok { + return c.(inFlight).ask + } + return "" +} + +// askIn is the ask id a `tools/call`'s `_meta` names, or empty: one subject-safe token, as a call's id is. +func askIn(meta map[string]any) string { + if s, ok := meta[MetaAsk].(string); ok && callID.MatchString(s) { + return s + } + return "" +} + // 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) { @@ -84,9 +113,9 @@ func callerIn(meta map[string]any) string { } // runAs runs a tool with the caller and the call's id held for its arguments for as long as it runs. -func runAs(t Tool, caller, call string, args map[string]any) (any, error) { +func runAs(t Tool, f inFlight, args map[string]any) (any, error) { key := argsKey(args) - calls.Store(key, inFlight{caller, call}) + calls.Store(key, f) defer calls.Delete(key) return t.Run(args) } diff --git a/go/caller_test.go b/go/caller_test.go index c816933c..81c7a9f6 100644 --- a/go/caller_test.go +++ b/go/caller_test.go @@ -13,26 +13,26 @@ import ( // 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 { - caller, _ := callAnswering(t, params) + caller, _, _ := callAnswering(t, params) return caller } // callAnswering is callWith answering the call's id CallIDOf read too. -func callAnswering(t *testing.T, params map[string]any) (string, string) { +func callAnswering(t *testing.T, params map[string]any) (string, string, string) { servesAlone(t) 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), "call": CallIDOf(args)}, nil + return map[string]any{"caller": CallerOf(args), "call": CallIDOf(args), "ask": AskIDOf(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 [2]string, 1) + done := make(chan [3]string, 1) go func() { if lines.Scan() { var m struct { @@ -46,19 +46,20 @@ func callAnswering(t *testing.T, params map[string]any) (string, string) { var answer struct { Caller string `json:"caller"` Call string `json:"call"` + Ask string `json:"ask"` } if len(m.Result.Content) > 0 { _ = json.Unmarshal([]byte(m.Result.Content[0].Text), &answer) } - done <- [2]string{answer.Caller, answer.Call} + done <- [3]string{answer.Caller, answer.Call, answer.Ask} } }() select { case got := <-done: - return got[0], got[1] + return got[0], got[1], got[2] case <-time.After(3 * time.Second): t.Fatal("the bundle did not answer the call") - return "", "" + return "", "", "" } } @@ -83,10 +84,24 @@ func TestAToolReadsTheCallerTheRuntimeNamed(t *testing.T) { {map[string]any{}, map[string]any{MetaCall: "a b"}, ""}, {map[string]any{}, map[string]any{MetaCall: 7}, ""}, } { - if _, call := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); call != c.want { + if _, call, _ := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); call != c.want { t.Errorf("args %v, meta %v: the tool read call %q, want %q", c.args, c.meta, call, c.want) } } + // Design 47 H2 §775, H-A-351: the ask id a kept call carried is the runtime's to name under mesh/ask, never the + // arguments'. + for _, c := range []struct { + args, meta map[string]any + want string + }{ + {map[string]any{}, map[string]any{MetaAsk: "build-7Hq2"}, "build-7Hq2"}, + {map[string]any{MetaAsk: "forged"}, map[string]any{}, ""}, + {map[string]any{}, map[string]any{MetaAsk: "a.b"}, ""}, + } { + if _, _, ask := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); ask != c.want { + t.Errorf("args %v, meta %v: the tool read ask %q, want %q", c.args, c.meta, ask, c.want) + } + } if CallIDOf(map[string]any{"x": 1}) != "" || CallIDOf(nil) != "" { t.Error("arguments no call was handed have a call id") } diff --git a/go/process/call.go b/go/process/call.go index 407ebd59..26a00866 100644 --- a/go/process/call.go +++ b/go/process/call.go @@ -10,6 +10,7 @@ import ( "github.com/nats-io/nats.go" + stdio "git.novox.be/novox/mesh-sdk/go" "git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/busretry" "git.novox.be/novox/mesh-sdk/go/calladdress" @@ -52,34 +53,51 @@ func (c *Conn) CallOn(node, key string, body any) (json.RawMessage, error) { } // CallKept is Call for a call whose answer the caller keeps and which is safe to make again (a read, or a write the -// callee deduplicates): it is asked again through a transport fault, a timeout or no responders, whether or not the bus -// is blacked out, until it is answered or busretry.Bound has passed (novox/hq ADR 0668, extending ADR 0615 §6; issue -// 1966). A callee that restarts answers no one for seconds; Call fails that at once. The caller keeps a call still -// unanswered past the bound as a wait of its own, and makes it again on the callee's event or its consumer's bind. +// callee deduplicates): mesh-sdk's kept-call form (design 47 H2 §775), asked again through a transport fault, a timeout +// or no responders at the kept-call pace (busretry.KeptPace, jittered), whether or not the bus is blacked out, until it +// is answered or busretry.Bound has passed (novox/hq ADR 0668, extending ADR 0615 §6; issue 1966). A refusal returns at +// once. A caller with an ask id and a bound of its own uses CallKeptAsk. func (c *Conn) CallKept(key string, body any) (json.RawMessage, error) { - called, fallback, err := callSubjectsOn(key, "", c.callerToken()) - if err != nil { - return nil, err - } - return c.callKeptOn(called, fallback, body) + return c.CallKeptAsk(KeptAsk{}, key, body) } // CallKeptOn is CallKept to the tool or seat verb of one named machine, as CallOn is Call's. func (c *Conn) CallKeptOn(node, key string, body any) (json.RawMessage, error) { + return c.CallKeptAskOn(KeptAsk{}, node, key, body) +} + +// KeptAsk is what a caller names of its kept call (design 47 H2 §775): the ask's id, which the call carries in the +// header stdio.AskHeader for the holder to take it once by (H-A-351), and the caller's bound (zero is busretry.Bound). +type KeptAsk struct { + ID string + Bound time.Duration +} + +// CallKeptAsk is CallKept carrying ask's id and stopping at ask's bound: past it the error is a *busretry.Unanswered +// naming every call's time and words. +func (c *Conn) CallKeptAsk(ask KeptAsk, key string, body any) (json.RawMessage, error) { + return c.callKeptAskOn(ask, "", key, body, nil) +} + +// CallKeptAskOn is CallKeptAsk to the tool or seat verb of one named machine. +func (c *Conn) CallKeptAskOn(ask KeptAsk, node, key string, body any) (json.RawMessage, error) { if err := calladdress.CheckNode(node); err != nil { return nil, err } - called, fallback, err := callSubjectsOn(key, node, c.callerToken()) - if err != nil { - return nil, err - } - return c.callKeptOn(called, fallback, body) + return c.callKeptAskOn(ask, node, key, body, nil) } // CallKeptWhileOpen is CallKept for an ask the asker can close or replace: it is asked again only while open says its // key is still open (design 47 G §351, §460). func (c *Conn) CallKeptWhileOpen(open busretry.Open, key string, body any) (json.RawMessage, error) { - called, fallback, err := callSubjectsOn(key, "", c.callerToken()) + if open.Open == nil { + return nil, fmt.Errorf("the call on %s: a kept call names its key's open function", key) + } + return c.callKeptAskOn(KeptAsk{}, "", key, body, &open) +} + +func (c *Conn) callKeptAskOn(ask KeptAsk, node, key string, body any, open *busretry.Open) (json.RawMessage, error) { + called, fallback, err := callSubjectsOn(key, node, c.callerToken()) if err != nil { return nil, err } @@ -87,21 +105,25 @@ func (c *Conn) CallKeptWhileOpen(open busretry.Open, key string, body any) (json if err != nil { return nil, err } - return busretry.DoKept("the call on "+fallback, open, askBoth(c.request, called, fallback, data), nil) + return callKeptWith(keptOf(key, ask, open), c.requestAsking(ask.ID), called, fallback, data) } -func (c *Conn) callKeptOn(called, fallback string, body any) (json.RawMessage, error) { - data, err := json.Marshal(body) - if err != nil { - return nil, err +// keptOf is the paced form's naming of a call on key: its seat and verb, or its module and tool. +func keptOf(key string, ask KeptAsk, open *busretry.Open) busretry.Kept { + k := busretry.Kept{Ask: ask.ID, Bound: ask.Bound, Open: open} + if a, err := calladdress.Parse(key); err == nil { + k.Seat, k.Verb = a.Seat, a.Verb + if a.Seat == "" { + k.Seat, k.Verb = a.Module, a.Tool + } } - return callKeptWith(c.request, called, fallback, data) + return k } -// callKeptWith is callWith for a kept call: busretry.DoRepeatable with no blackout probe. -func callKeptWith(request func(string, []byte) (json.RawMessage, error), called, fallback string, +// callKeptWith is callWith for a kept call: busretry.DoPaced with no blackout probe. +func callKeptWith(k busretry.Kept, request func(string, []byte) (json.RawMessage, error), called, fallback string, data []byte) (json.RawMessage, error) { - return busretry.DoRepeatable("the call on "+fallback, askBoth(request, called, fallback, data), nil) + return busretry.DoPaced(k, askBoth(request, called, fallback, data)) } // askBoth asks called, then fallback when nothing answers it. @@ -209,10 +231,28 @@ func callSubjectsOn(key, node, token string) (called, fallback string, err error // request asks one subject once and reads its reply ({result, error, node}); a reply naming an error is // the call's failure, not a transport one. func (c *Conn) request(subject string, data []byte) (json.RawMessage, error) { - ctx, cancel := context.WithTimeout(context.Background(), CallTimeout) - defer cancel() + return c.requestAsk(subject, data, "") +} + +// requestAsking is request carrying an ask's id in the header stdio.AskHeader (H-A-351); empty carries none. +func (c *Conn) requestAsking(ask string) func(string, []byte) (json.RawMessage, error) { + return func(subject string, data []byte) (json.RawMessage, error) { return c.requestAsk(subject, data, ask) } +} + +// askMsg is the request a call publishes: its ask's id in stdio.AskHeader when it carries one (H-A-351). +func askMsg(subject string, data []byte, ask string) *nats.Msg { req := nats.NewMsg(subject) req.Data = data + if ask != "" { + req.Header.Set(stdio.AskHeader, ask) + } + return req +} + +func (c *Conn) requestAsk(subject string, data []byte, ask string) (json.RawMessage, error) { + ctx, cancel := context.WithTimeout(context.Background(), CallTimeout) + defer cancel() + req := askMsg(subject, data, ask) if strings.HasPrefix(subject, "mesh.seat.") { // Every seat call says it waits for a held call's end; a verb that is not marked ignores it (lead answer A-244). req.Header.Set(approval.WaitHeader, approval.WaitHeld) diff --git a/go/process/call_test.go b/go/process/call_test.go index dd1a1121..7d138e21 100644 --- a/go/process/call_test.go +++ b/go/process/call_test.go @@ -10,6 +10,8 @@ import ( "github.com/nats-io/nats.go" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/busretry" ) @@ -128,7 +130,7 @@ func TestACallIsAskedAgainOnlyWhenItReachedNoOne(t *testing.T) { } var err error if row.kept { - _, err = callKeptWith(request, "called", "fallback", nil) + _, err = callKeptWith(busretry.Kept{Seat: "s", Verb: "v"}, request, "called", "fallback", nil) } else { _, err = callWith(request, func() bool { return true }, "called", "fallback", nil) } @@ -136,6 +138,26 @@ func TestACallIsAskedAgainOnlyWhenItReachedNoOne(t *testing.T) { t.Errorf("%s: asked %d times (%v), want %d", row.name, asks, err, row.asks) } } + // Design 47 H2 §775, H-A-351: a kept call carries its ask's id in the header, and a holder in a process reads it with + // AskOf while its handler runs; a call carrying none reads empty. + if m := askMsg("mesh.seat.mesh-builds.call.build", []byte(`{}`), "ask-9"); m.Header.Get(stdio.AskHeader) != "ask-9" { + t.Errorf("the ask's id is not in the header: %v", m.Header) + } + if m := askMsg("s", nil, ""); m.Header.Get(stdio.AskHeader) != "" { + t.Errorf("a call with no ask carries one: %v", m.Header) + } + c := &Conn{} + for _, ask := range []string{"ask-9", ""} { + msg := askMsg("mesh.seat.mesh-builds.tool.build", []byte(`{"x":1}`), ask) + read := "unread" + c.answerCall(msg, "mesh.seat.mesh-builds.tool.build", func(_ string, body json.RawMessage, _ bool) (any, *approval.Held, error) { + read = AskOf(body) + return nil, nil, nil + }) + if read != ask || AskOf(json.RawMessage(msg.Data)) != "" { + t.Errorf("the holder read the ask %q, want %q, and none once its handler ended", read, ask) + } + } } // A-107: AnswerSeat reads the caller from a call's last token (dots written `~`), "" for anything that is not a diff --git a/go/process/serve.go b/go/process/serve.go index 6234ddf3..4e2eabf1 100644 --- a/go/process/serve.go +++ b/go/process/serve.go @@ -6,9 +6,12 @@ import ( "regexp" "sort" "strings" + "sync" + "unsafe" "github.com/nats-io/nats.go" + stdio "git.novox.be/novox/mesh-sdk/go" "git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/calladdress" "git.novox.be/novox/mesh-sdk/go/seatdef" @@ -157,6 +160,21 @@ func (c *Conn) admitted(seat, verb string, definition func() (seatdef.Definition } } +// asks holds the ask id each call in flight carried (stdio.AskHeader), by its body's bytes, while its handler runs. +var asks sync.Map // unsafe.Pointer → string + +// AskOf is the ask id the call whose body a SeatHandler was handed carried in stdio.AskHeader (design 47 H2 §775; +// H-A-351): what a holder in a process takes the ask once by. Empty when it carried none. Valid while the handler runs. +func AskOf(body json.RawMessage) string { + if len(body) == 0 { + return "" + } + if a, ok := asks.Load(unsafe.Pointer(unsafe.SliceData(body))); ok { + return a.(string) + } + return "" +} + // answerCall runs h for one call and replies {result, error, node}; a panic in h is the call's error, never silence. func (c *Conn) answerCall(msg *nats.Msg, pattern string, h heldHandler) { caller := "" @@ -177,7 +195,13 @@ func (c *Conn) answerCall(msg *nats.Msg, pattern string, h heldHandler) { reply.Error = fmt.Sprintf("%s failed: %v", msg.Subject, r) } }() - result, held, err := h(caller, json.RawMessage(msg.Data), wait) + body := json.RawMessage(msg.Data) + if ask := msg.Header.Get(stdio.AskHeader); ask != "" && len(body) > 0 { + key := unsafe.Pointer(unsafe.SliceData(body)) + asks.Store(key, ask) + defer asks.Delete(key) + } + result, held, err := h(caller, body, wait) switch { case err != nil: reply.Error = err.Error() diff --git a/go/stdio.go b/go/stdio.go index b6bf51ad..7e6e71a3 100644 --- a/go/stdio.go +++ b/go/stdio.go @@ -268,18 +268,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, caller, call string) { + go func(id any, t Tool, args map[string]any, caller, call, ask string) { if args == nil { args = map[string]any{} } - result, err := runAs(t, caller, call, args) + result, err := runAs(t, inFlight{caller, call, ask}, 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, callerIn(p.Meta), callIn(p.Meta)) + }(id, t, p.Arguments, callerIn(p.Meta), callIn(p.Meta), askIn(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 diff --git a/src/callers/index.ts b/src/callers/index.ts index 8a913775..8207f8c9 100644 --- a/src/callers/index.ts +++ b/src/callers/index.ts @@ -17,6 +17,12 @@ export const META_CALLER = "mesh/caller"; /** Where in a `tools/call`'s `_meta` the runtime names the id of the call in flight (`buscalls.MetaCall`). */ export const META_CALL = "mesh/call"; +/** + * Where in a `tools/call`'s `_meta` the runtime names the ask id a kept call carried (the Go side's `stdio.MetaAsk`; + * design 47 H2 §775, H-A-351): what a holder takes the ask once by. + */ +export const META_ASK = "mesh/ask"; + // A bus user's name: `.`, `person.`, `controller`; anything else is no caller. const busUser = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/; // A call's id: one subject-safe token. @@ -25,6 +31,7 @@ const callID = /^[A-Za-z0-9_-]{1,128}$/; interface InFlight { readonly caller: string; readonly call: string; + readonly ask: string; } // The caller and the call's id of every call while its tool runs, by the arguments object that call was handed. @@ -42,12 +49,18 @@ export function callIn(meta: unknown): string { return typeof s === "string" && callID.test(s) ? s : ""; } +/** The ask id a `tools/call`'s `_meta` names, or empty: one subject-safe token, as a call's id is. */ +export function askIn(meta: unknown): string { + const s = meta && typeof meta === "object" ? (meta as Record)[META_ASK] : undefined; + return typeof s === "string" && callID.test(s) ? s : ""; +} + /** * Run `run` with the caller and the call's id `meta` names held for `args` while it runs: the stdio session does this * for every `tools/call`. */ export async function runAs(meta: unknown, args: object, run: () => Promise): Promise { - calls.set(args, { caller: callerIn(meta), call: callIn(meta) }); + calls.set(args, { caller: callerIn(meta), call: callIn(meta), ask: askIn(meta) }); try { return await run(); } finally { @@ -65,6 +78,11 @@ export function callIdOf(args: object | undefined | null): string { return (args && calls.get(args)?.call) || ""; } +/** The ask id the call that was handed `args` carried (H-A-351), or empty. Valid while the tool runs. */ +export function askIdOf(args: object | undefined | null): string { + return (args && calls.get(args)?.ask) || ""; +} + /** * A module's trusted list of who may call it (ADR 0459 §2): an entry is a module (on any machine), exactly * `.`, or exactly `person.`. A wildcard is no entry and an unproven caller never matches. diff --git a/test/sdk.test.ts b/test/sdk.test.ts index 6127376e..0fb1f2f8 100644 --- a/test/sdk.test.ts +++ b/test/sdk.test.ts @@ -670,7 +670,7 @@ test("the provider loop is named for what it is, and its old name stays an alias await newTest6(); // a TypeScript bundle's value over one call's limit fails at once, namin }); -import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN } from "../dist/callers/index.js"; +import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN, runAs, askIdOf, META_ASK } from "../dist/callers/index.js"; import { Follower, statusTools, keepStatus, statusKey, viewWaitsFinding, type Answer, type Status } from "../dist/views/index.js"; // callers and verb callers judge a proved caller by the Go side's rules (ADR 0459 §2, ADR 0627 §2) @@ -698,6 +698,12 @@ async function newTest1(): Promise { for (const [cls, want] of byClass) assert.deepEqual(readDefinitionCallers("list", undefined, cls), want, String(cls)); assert.deepEqual(readDefinitionCallers("register", ["seat:mesh-broker"], "act"), ["seat:mesh-broker"]); assert.throws(() => parseCallers('{"callers":["a"],"more":1}'), /unknown field "more"/); + // design 47 H2 §775, H-A-351: the ask id a kept call carried is the runtime's to name under mesh/ask, never the arguments' + for (const [meta, args, want] of [[{ [META_ASK]: "build-7Hq2" }, {}, "build-7Hq2"], [{}, { [META_ASK]: "forged" }, ""], [{ [META_ASK]: "a.b" }, {}, ""]] as const) { + const a = { ...args }; + assert.equal(await runAs(meta, a, async () => askIdOf(a)), want, JSON.stringify(meta)); + assert.equal(askIdOf(a), "", "no ask once the call ended"); + } const verbs = parseVerbCallers('{"pull":["*"],"merge-pull":["mesh-delivery-forge-bridge"],"comment":["operator"]}', ["pull", "merge-pull", "comment"], {}); assert.equal(refusal(verbs, "pull", "ace.anyone"), undefined);