Files
mesh-delivery/modules/mesh-delivery-teller/cmd/mesh-delivery-teller-tools/main.go
T
jschoubben 3d058af14c D1 (teller): the teller names its own module from its credential's
Its conditions' keys, its asks' subjects, its reader and emitter, its ends bucket and its tools' first views take the module its credential names (the tools: the module the runtime serves them as) instead of constants of its name; a guard test finds none in its code.

Builds: design 47 G A-296, §428

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:47:50 +01:00

228 lines
9.6 KiB
Go

// Command mesh-delivery-teller-tools serves the teller's recovery tool (issue 774): the runtime launches it for a call.
// teller_end_ask writes one value of the teller's state ends and waits for the teller's answer there. The teller is the
// other program: it serves no request subject (ADR 0437 §4).
package main
import (
"context"
"encoding/json"
"fmt"
"os"
"sort"
"strings"
"sync"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-teller/internal/ends"
)
// widensSaidState is the teller's state widens-said (the program's own constant of it is in cmd/mesh-delivery-teller).
const widensSaidState = "widens-said"
// asker writes an ends value and waits for the teller's answer to it.
type asker func(key string, value []byte) (ends.End, error)
// Tools are the teller's tools.
func Tools(ask asker, now func() time.Time) []stdio.Tool {
str := func(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
return []stdio.Tool{
{Name: ends.Tool,
Description: "End one open ask the delivery teller holds at the operator channel, by hand, saying why: the teller " +
"cancels it at the router, which frees one of the three places the router gives the teller, or drops it from the " +
"teller's wait for room. For an ask whose question is gone but whose key was never taken away (a merge ask of a pull " +
"request merged by another path, a backup ask about a backup no longer failing), which otherwise holds its place " +
"until it lapses, so a newer ask is refused for want of room. Name the ask by its router id (as " +
"operator-channel's asks show it) or by the key of the gate's or the assigner's asks. Answers which ask it found, " +
"whether it ended it, and what it did; an ask answered, lapsed or ended already is left and said so.",
Input: map[string]any{"type": "object", "required": []string{"ask", "why"}, "properties": map[string]any{
"ask": map[string]any{"type": "string", "description": "the ask's router id, or the key of the gate's or the assigner's asks it was asked for"},
"why": map[string]any{"type": "string", "description": "why it is ended by hand, in plain words"}}},
Run: func(args map[string]any) (any, error) {
key, value, err := ends.New(str(args, "ask"), str(args, "why"), stdio.CallerOf(args), now())
if err != nil {
return nil, err
}
e, err := ask(key, value)
if err != nil {
return nil, err
}
return e.Result, nil
}},
}
}
// AnswersTool is the tool that reads the teller's state answers (ADR 0596 §3: the owner's state is read through its owner's
// tool): one answer by the key of the ask it answers, or every answer when none is named. It reads and writes nothing else.
const AnswersTool = "teller_answers"
// answers is the teller's state answers as the tool reads it.
type answers interface {
Get(key string) (*stdio.StateEntry, error)
Keys() ([]string, error)
}
// AnswerTools is the tool teller_answers over the state answers.
func AnswerTools(s answers) []stdio.Tool {
return []stdio.Tool{{Name: AnswersTool,
Description: "Read the answers the delivery teller kept to the gate's asks, as it wrote them: the answer under one ask's " +
"key (found false when the ask has none), or every answer when no key is named. An answer is the operator's chosen " +
"option, the warrant it came by and the words of it. What the gate reads to merge on the Approve.",
Input: map[string]any{"type": "object", "properties": map[string]any{
"key": map[string]any{"type": "string", "description": "the key of the gate's ask the answer is under; none for every answer"}}},
Run: func(args map[string]any) (any, error) {
key, _ := args["key"].(string)
if key = strings.TrimSpace(key); key != "" {
e, err := s.Get(key)
if err != nil {
return nil, fmt.Errorf("the answer under %s cannot be read: %w", key, err)
}
if e == nil {
return map[string]any{"key": key, "found": false}, nil
}
return map[string]any{"key": key, "found": true, "answer": json.RawMessage(e.Value)}, nil
}
keys, err := s.Keys()
if err != nil {
return nil, fmt.Errorf("the answers cannot be listed: %w", err)
}
sort.Strings(keys)
out := make([]map[string]any, 0, len(keys))
for _, k := range keys {
e, err := s.Get(k)
if err != nil {
return nil, fmt.Errorf("the answer under %s cannot be read: %w", k, err)
}
if e != nil {
out = append(out, map[string]any{"key": k, "answer": json.RawMessage(e.Value)})
}
}
return map[string]any{"answers": out}, nil
}}}
}
// ReadAnswersTool is the teller's ordinary read tool of its state answers (design 47 G A-175, A-178; mesh-sdk views.ReadTool):
// what the view follows, first by it and then by the teller's views family views.answers. Its marks are the state teller-marks.
const ReadAnswersTool = "teller_read_answers"
// marksState is the teller's state of what its views family said each state up to (A-178).
const marksState = "teller-marks"
// ReadAnswersTools is the tool teller_read_answers over the state answers and its marks.
func ReadAnswersTools(module string, values, marks views.Source, now func() time.Time) []stdio.Tool {
return []stdio.Tool{views.ReadTool(module, ReadAnswersTool, "answers",
"the operator's answers to the assigner's asks, by the ask's key.", values, marks, now)}
}
// WidensSaidTool reads the teller's state widens-said (design 47 G §335).
const WidensSaidTool = "teller_widens_said"
// WidensSaidTools is the tool teller_widens_said over the state widens-said: the last commit the teller said a widening of
// for one module on one watched branch, or every one when none is named.
func WidensSaidTools(s answers) []stdio.Tool {
return []stdio.Tool{{Name: WidensSaidTool,
Description: "Read what the delivery teller has said of widenings: for each module and watched branch, the last commit it told the " +
"operator a widening of on every channel. Keys are the module and the branch, each escaped as a key's name is, joined by a dot. " +
"Name a key for one, or none for every one.",
Input: map[string]any{"type": "object", "properties": map[string]any{
"key": map[string]any{"type": "string", "description": "<module>.<branch> as the state keys it; none for every one"}}},
Run: func(args map[string]any) (any, error) {
key, _ := args["key"].(string)
if key = strings.TrimSpace(key); key != "" {
e, err := s.Get(key)
if err != nil {
return nil, fmt.Errorf("%s cannot be read: %w", key, err)
}
if e == nil {
return map[string]any{"key": key, "found": false}, nil
}
return map[string]any{"key": key, "found": true, "commit": json.RawMessage(e.Value)}, nil
}
keys, err := s.Keys()
if err != nil {
return nil, fmt.Errorf("the keys cannot be listed: %w", err)
}
sort.Strings(keys)
out := make([]map[string]any, 0, len(keys))
for _, k := range keys {
e, err := s.Get(k)
if err != nil {
return nil, fmt.Errorf("%s cannot be read: %w", k, err)
}
if e != nil {
out = append(out, map[string]any{"key": k, "commit": json.RawMessage(e.Value)})
}
}
return map[string]any{"said": out}, nil
}}}
}
// askEnd writes the ends value at key and waits, on a watch of the key, at most bound for the teller's answer.
func askEnd(s stdio.KeptState, bound time.Duration) asker {
return func(key string, value []byte) (ends.End, error) {
answered := make(chan ends.End, 1)
var rev uint64
var mu sync.Mutex
take := func(revision uint64, v []byte) {
mu.Lock()
mine := rev
mu.Unlock()
if mine == 0 || revision <= mine {
return
}
e, err := ends.Decode(v)
if err != nil || !e.Done() {
return
}
select {
case answered <- e:
default:
}
}
if err := s.Watch(key, func(c stdio.StateChange) error {
if c.Op == "put" {
take(c.Revision, c.Value)
}
return nil
}); err != nil {
return ends.End{}, fmt.Errorf("watching %s.%s: %w", ends.State, key, err)
}
r, err := s.Put(key, json.RawMessage(value))
if err != nil {
return ends.End{}, fmt.Errorf("the end could not be written to %s: %w", ends.Bucket(os.Getenv(stdio.ServedAs)), err)
}
mu.Lock()
rev = r
mu.Unlock()
// The watch may have heard the answer before the revision was known: read it once too.
if e, err := s.Get(key); err == nil && e != nil {
take(e.Revision, e.Value)
}
wait, cancel := context.WithTimeout(context.Background(), bound) // a context's bound, no timer (ADR 0437 §8)
defer cancel()
select {
case e := <-answered:
return e, nil
case <-wait.Done():
return ends.End{}, fmt.Errorf("the teller did not answer within %s: is it running? its answer will be in %s.%s", bound, ends.Bucket(os.Getenv(stdio.ServedAs)), key)
}
}
}
func main() {
// teller_first_views and teller_first_view_again: where the teller's first view of the assigner's asks stands, and
// asking it again by hand (ADR 0615, design 25 § 12.2).
tools := append(Tools(askEnd(stdio.State(ends.State), 25*time.Second), time.Now),
views.StatusTools(os.Getenv(stdio.ServedAs), "teller_first_views", "teller_first_view_again", stdio.State(views.StatusState), meshhandactsclient.Recorder{Ask: stdio.Ask}, time.Now)...)
tools = append(tools, AnswerTools(stdio.State("answers"))...)
tools = append(tools, ReadAnswersTools(os.Getenv(stdio.ServedAs), views.KeptSource{State: stdio.State("answers")}, views.KeptSource{State: stdio.State(marksState)}, time.Now)...)
tools = append(tools, WidensSaidTools(stdio.State(widensSaidState))...)
if err := stdio.Serve("", tools); err != nil {
fmt.Fprintf(os.Stderr, "[mesh-delivery-teller-tools] %v\n", err)
os.Exit(1)
}
}