Compare commits
8
Commits
go/v0.1.13
...
4cf45b5ca0
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4cf45b5ca0 | ||
|
|
d9e24e95a2 | ||
|
|
ee1e1a8303 | ||
|
|
24f5ee81bd | ||
|
|
b4900f52b8 | ||
|
|
19cfe0ef03 | ||
|
|
33917f91ac | ||
|
|
622b6b4f55 |
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
`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.
|
||||
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 and watches the module's declared state — all through the runtime (novox/hq ADR 0193, 0198, 0201). Standard library only.
|
||||
|
||||
## Installing
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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
@@ -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 {
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
+7
-4
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user