T1a verb-timeout-ask: a bundle's ask waits the timeout its verb's definition names

The runner reads the `timeout` (whole seconds) of a seat's verb from the seat list's definitions beside `chunked` and hands it to
the bus connection's ask (AskWithin, AskAsWithin, AskAsChunkedWithin); a verb that names none, a seat the definitions do not hold
and a module's tool wait the runner's own bound, RequestTimeout.

Builds: design 47 H §760, H-A-43

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 02:35:28 +01:00
parent 76df3cb420
commit 5314231c0d
8 changed files with 144 additions and 15 deletions
+26 -6
View File
@@ -32,9 +32,18 @@ import (
"github.com/novox/mesh-tools/node-tools/internal/wire"
)
// RequestTimeout is how long a call waits for its answer — what modules already expect.
// RequestTimeout is how long a call waits for its answer when its verb's definition names no `timeout`: the tool runner's own
// bound, what modules already expect (design 47 H §760, H-A-43).
const RequestTimeout = 30 * time.Second
// waitOf is the bound a call waits: within where the verb's definition names one, else the tool runner's own.
func waitOf(within time.Duration) time.Duration {
if within > 0 {
return within
}
return RequestTimeout
}
// Credential is a broker credential as the mesh delivers it (novox/hq ADR 0120).
type Credential struct {
URL string `json:"url"`
@@ -793,6 +802,12 @@ func (c *Conn) reachedAt(key string) (string, error) {
// Ask calls a tool by key — or on a subject the mesh listed for it — and learns which machine
// answered. Core request/reply: a tool call is never persisted (design 25 §3).
func (c *Conn) Ask(key string, body any, on string) (Answered, error) {
return c.AskWithin(key, body, on, 0)
}
// AskWithin is Ask that waits within for its answer, the `timeout` its verb's definition names (design 47 H §760, H-A-43);
// zero waits the tool runner's own bound, RequestTimeout.
func (c *Conn) AskWithin(key string, body any, on string, within time.Duration) (Answered, error) {
subject := on
if subject == "" {
s, err := c.reachedAt(key)
@@ -809,12 +824,12 @@ func (c *Conn) Ask(key string, body any, on string) (Answered, error) {
// account publish with its own name alone; asked again on the subject that names no caller only when the
// first reached nobody — nothing serves it yet, or the bus does not grant it yet — so no call is done twice.
if called := CalledSubject(subject, c.cred.User); called != "" {
answered, fallBack, err := c.askCalled(called, data)
answered, fallBack, err := c.askCalled(called, data, within)
if !fallBack {
return answered, err
}
}
return c.askOnce(subject, data)
return c.askOnce(subject, data, within)
}
// ErrNoResponders is the bus's own refusal: nothing subscribes to the subject asked. It is told apart
@@ -822,8 +837,8 @@ func (c *Conn) Ask(key string, body any, on string) (Answered, error) {
var ErrNoResponders = errors.New("503 no responders")
// askOnce asks once.
func (c *Conn) askOnce(subject string, data []byte) (Answered, error) {
msg, err := c.nc.Request(subject, data, RequestTimeout)
func (c *Conn) askOnce(subject string, data []byte, within time.Duration) (Answered, error) {
msg, err := c.nc.Request(subject, data, waitOf(within))
if err != nil {
if errors.Is(err, nats.ErrNoResponders) {
return Answered{}, ErrNoResponders
@@ -1036,6 +1051,11 @@ func SeatToolSubject(seat, verb, scope, node string) string {
// `<module>.<tool>` another's, `seat:<seat>.<verb>[@<node>]` a role's — resolved through what the
// mesh issued that module to reach, as its own runtime resolved it, else the derived shape.
func (c *Conn) AskAs(module, key string, body any) (Answered, error) {
return c.AskAsWithin(module, key, body, 0)
}
// AskAsWithin is AskAs that waits within for its answer (design 47 H §760); zero waits RequestTimeout.
func (c *Conn) AskAsWithin(module, key string, body any, within time.Duration) (Answered, error) {
name, wanted, _ := strings.Cut(key, "@")
subject := ""
if m := c.Membership(module); m != nil {
@@ -1058,7 +1078,7 @@ func (c *Conn) AskAs(module, key string, body any) (Answered, error) {
}
subject = s
}
return c.Ask(key, body, subject)
return c.AskWithin(key, body, subject, within)
}
// EventsStream is where every module's events land, and ConsumerOf the durable consumer the
+10
View File
@@ -4,6 +4,7 @@ import (
"errors"
"fmt"
"testing"
"time"
)
func TestSubjectsAreTheOnesTheTypeScriptRuntimeUses(t *testing.T) {
@@ -60,3 +61,12 @@ func TestAnEventDeliveredAgainHasItsOwnKey(t *testing.T) {
}
}
}
// Design 47 H §760: a call waits the bound its verb's definition names, else the tool runner's own.
func TestWaitOfIsTheVerbsBoundElseTheRunnersOwn(t *testing.T) {
for within, want := range map[time.Duration]time.Duration{0: RequestTimeout, 40 * time.Second: 40 * time.Second, 600 * time.Second: 600 * time.Second} {
if got := waitOf(within); got != want {
t.Errorf("waitOf(%s) = %s, want %s", within, got, want)
}
}
}
+3 -2
View File
@@ -7,6 +7,7 @@ import (
"regexp"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go"
)
@@ -150,9 +151,9 @@ func (c *Conn) publishRefused(err error) bool {
// askCalled asks once on a caller-named subject. fallBack says the call reached nobody — nothing serves that
// subject yet, or the bus refused this user its publish — so it may be asked on the subject that names no
// caller without being done twice.
func (c *Conn) askCalled(subject string, data []byte) (answered Answered, fallBack bool, err error) {
func (c *Conn) askCalled(subject string, data []byte, within time.Duration) (answered Answered, fallBack bool, err error) {
ctx, cancel := context.WithCancelCause(context.Background())
ctx, stop := context.WithTimeout(ctx, RequestTimeout)
ctx, stop := context.WithTimeout(ctx, waitOf(within))
defer stop()
c.calls.mu.Lock()
if c.calls.pending == nil {
@@ -216,3 +216,30 @@ func TestAFallBackForWantOfAResponderIsSaidOncePerSubject(t *testing.T) {
t.Errorf("the fall-back was said %d times, want once: %v", n, said)
}
}
// Design 47 H §760: a call waits the bound its verb's definition names, and ends there with the timeout; the caller of a verb whose
// definition names none waits the tool runner's own bound, RequestTimeout.
func TestACallWaitsTheBoundItsVerbNamesAndTimesOutThere(t *testing.T) {
url := grantedBus(t, map[string][]string{"anchor.node-tools": {"_INBOX.>"}, "shanks.node-tools": {"mesh.mod.*.tool.>"}})
server := dial(t, url, "node-tools", "anchor", "anchor.node-tools")
release := make(chan struct{})
stop, err := server.HandleSubjectCalled("mesh.mod.ledger.tool.slow", func(string, json.RawMessage) (any, error) {
<-release
return map[string]any{}, nil
})
if err != nil {
t.Fatal(err)
}
defer stop()
defer close(release)
server.Flush()
asker := dial(t, url, "node-tools", "shanks", "shanks.node-tools")
began := time.Now()
_, err = asker.AskWithin("ledger.slow", map[string]any{}, "", 200*time.Millisecond)
if err == nil || err.Error() != "timeout" {
t.Fatalf("a call whose verb names a bound the holder outlasts: %v, want the timeout", err)
}
if took := time.Since(began); took > bus.RequestTimeout/2 {
t.Errorf("the call waited %s, want its own bound of 200ms, not the tool runner's %s", took, bus.RequestTimeout)
}
}
+6 -1
View File
@@ -25,6 +25,11 @@ const FileField = "file"
// counts with buscalls.SeatChunks, each acknowledged before the next, and answers the verb's own answer with the whole
// file added as FileField. The asking bundle receives no chunk itself.
func (c *Conn) AskAsChunked(module, key string, body any) (Answered, error) {
return c.AskAsChunkedWithin(module, key, body, 0)
}
// AskAsChunkedWithin is AskAsChunked that waits within for the verb's answer (design 47 H §760); zero waits RequestTimeout.
func (c *Conn) AskAsChunkedWithin(module, key string, body any, within time.Duration) (Answered, error) {
// The verb may be asked of the machine that ran the ask (`@<node>`, A-254): the chunk subjects name the seat, the verb and
// the call alone.
name, _, _ := strings.Cut(key, "@")
@@ -52,7 +57,7 @@ func (c *Conn) AskAsChunked(module, key string, body any) (Answered, error) {
return Answered{}, fmt.Errorf("the chunks of %s cannot be heard: %w", key, err)
}
defer func() { _ = sub.Unsubscribe() }()
answered, err := c.AskAs(module, key, args)
answered, err := c.AskAsWithin(module, key, args, within)
if err != nil {
return answered, err
}