S1 kept call paced: carry the ask id, pace at the settings' defaults with jitter, stop at the caller's bound
The kept call is made again on a transport fault after kept-call-pace-first (1 s) doubling to kept-call-pace-max (30 s), each wait within 20 %, until the caller's bound; past it the answer names every call's time and words. One journal line per seat at the first fault, then at most once a minute. The ask id travels in the header x-ask; a holder reads it with process.AskOf, a bundle with stdio.AskIDOf (TypeScript askIdOf) from the call's _meta mesh/ask. Builds: design 47 H2 §775; H-A-351
This commit is contained in:
+197
-1
@@ -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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
+32
-3
@@ -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)
|
||||
}
|
||||
|
||||
+23
-8
@@ -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")
|
||||
}
|
||||
|
||||
+66
-26
@@ -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)
|
||||
|
||||
+23
-1
@@ -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
|
||||
|
||||
+25
-1
@@ -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()
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
+19
-1
@@ -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: `<node>.<module>`, `person.<name>`, `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<string, unknown>)[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<T>(meta: unknown, args: object, run: () => Promise<T>): Promise<T> {
|
||||
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
|
||||
* `<machine>.<module>`, or exactly `person.<name>`. A wildcard is no entry and an unproven caller never matches.
|
||||
|
||||
+7
-1
@@ -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<void> {
|
||||
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);
|
||||
|
||||
Reference in New Issue
Block a user