Feature 57 (config and provisioning): release mesh-tools (the provider's StateBus, the SDK pin, templates), reviewed

node-tools/internal/provide/provide.go

@@ -0,0 +1,132 @@
+// Package provide is the runtime's half of node-tools being a provider of `mcp-endpoint`: it runs the mesh SDK's
+// provider helper, so a consumer handed to the provisioner (claude-code's `${bound:mcp-endpoint:port}`) is answered
+// from an entry node-tools writes in its own bucket, not from the controller's binding file (novox/hq ADR 0349
+// clause 12, issue 791).
+//
+// The offer carries no credential: the console's authority is the machine's login (ADR 0152, 0175), so the helper
+// reads nothing from the vault, needs no consumers' file and the entry names none. node-tools is not marked moved:
+// its manifest says `"answered-by": "helper"` for the provision, and the helper runs whenever the runtime does
+// (issue 791), as route-proxy's does (issue 792).
+package provide
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/provider"
+
+	"github.com/novox/mesh-tools/node-tools/internal/bus"
+)
+
+const (
+	// Module is the provider: the runtime's own module.
+	Module = "node-tools"
+	// Provision is what node-tools provides, as its manifest says.
+	Provision = "mcp-endpoint"
+	// ServedPort is the port its manifest serves (`serves.mcp-endpoint.port`): where the console listens.
+	ServedPort = 4270
+)
+
+// Offers is what node-tools serves, per provision.
+func Offers() map[string]provider.Offer {
+	return map[string]provider.Offer{Provision: {
+		Credential: provider.NoCredential,
+		Serves:     map[string]any{"port": ServedPort},
+	}}
+}
+
+// busOf is the helper's bus over the runtime's own state: the provider's bucket is its state `bound`, and the
+// controller's assignments are the state it reads, `mesh-controller.assignments` (both declared in the manifest).
+type busOf struct{ conn *bus.Conn }
+
+func (b busOf) state(bucket string) (string, error) {
+	switch bucket {
+	case provider.BucketOf(Module):
+		return "bound", nil
+	case provider.AssignmentsBucket:
+		return "mesh-controller.assignments", nil
+	}
+	return "", fmt.Errorf("%s is not a bucket this provider keeps or reads", bucket)
+}
+
+func (b busOf) Watch(ctx context.Context, bucket string, handle func(key string, value []byte)) error {
+	name, err := b.state(bucket)
+	if err != nil {
+		return err
+	}
+	stop, err := b.conn.StateWatch(Module, name, "", func(ch bus.StateChange) error {
+		if ch.Op == "delete" {
+			handle(ch.Key, nil)
+		} else {
+			handle(ch.Key, ch.Value)
+		}
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+	go func() { <-ctx.Done(); stop() }()
+	return nil
+}
+
+func (b busOf) Put(_ context.Context, bucket, key string, value []byte) error {
+	name, err := b.state(bucket)
+	if err != nil {
+		return err
+	}
+	_, err = b.conn.StatePut(Module, name, key, json.RawMessage(value))
+	return err
+}
+
+func (b busOf) Delete(_ context.Context, bucket, key string) error {
+	name, err := b.state(bucket)
+	if err != nil {
+		return err
+	}
+	return b.conn.StateDelete(Module, name, key)
+}
+
+// New is the helper answering node-tools's consumers on node.
+func New(conn *bus.Conn, node string, every time.Duration, logf func(string, ...any)) *provider.Provider {
+	return provider.New(provider.Options{
+		Node:   node,
+		Module: Module,
+		Offers: Offers(),
+		Bus:    busOf{conn: conn},
+		Every:  every,
+		Logf:   logf,
+	})
+}
+
+// Run answers the consumers until ctx ends. The state is not reachable until the mesh has issued the runtime its
+// membership and made the buckets, so a start that cannot watch is tried again, not given up.
+func Run(ctx context.Context, conn *bus.Conn, node string, every time.Duration, logf func(string, ...any)) {
+	for delay := 2 * time.Second; ctx.Err() == nil; delay = min(delay*2, time.Minute) {
+		attempt, cancel := context.WithCancel(ctx)
+		err := New(conn, node, every, logf).Run(attempt)
+		cancel()
+		if ctx.Err() != nil {
+			return
+		}
+		logf("[mesh-tools] the provider helper stopped: %v; trying again in %s", err, delay)
+		select {
+		case <-ctx.Done():
+		case <-time.After(delay):
+		}
+	}
+}
+
+// Start runs the helper when this process is the machine's runtime (the node-tools credential, on a machine's
+// name), with no condition on the environment, and returns what ends it. A runtime on another credential, a module's
+// own in a test, is not the provider and answers nobody.
+func Start(conn *bus.Conn, module, node string, every time.Duration, logf func(string, ...any)) (stop func()) {
+	if module != Module || node == "" {
+		return func() {}
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	logf("[mesh-tools] answering %s's consumers of %s through the provider helper", Module, Provision)
+	go Run(ctx, conn, node, every, logf)
+	return cancel
+}

node-tools/internal/provide/provide_test.go

@@ -0,0 +1,149 @@
+package provide
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-tools/node-tools/internal/bus"
+	mt "github.com/novox/mesh-tools/node-tools/internal/meshtest"
+)
+
+// claude-code's facts.json template, as the catalogue keeps it (modules/claude-code/files/facts.json).
+const factsTemplate = `{
+  "node": "${machine:name}",
+  "console": "http://127.0.0.1:${bound:mcp-endpoint:port}/mcp"
+}
+`
+
+// factsToday is that file as the controller composes it today, from the port node-tools serves.
+const factsToday = `{
+  "node": "anchor",
+  "console": "http://127.0.0.1:4270/mcp"
+}
+`
+
+// fill is what the consumer's client does with the template: the machine's name, and each ${bound:<provision>:<key>}
+// from the provider's entry.
+func fill(t *testing.T, template string, entry map[string]any) string {
+	t.Helper()
+	values, _ := entry["values"].(map[string]any)
+	out := strings.ReplaceAll(template, "${machine:name}", "anchor")
+	for key, v := range values {
+		raw, _ := json.Marshal(v)
+		out = strings.ReplaceAll(out, "${bound:mcp-endpoint:"+key+"}", string(raw))
+	}
+	return out
+}
+
+func TestTheRuntimeAnswersAHandedConsumersMcpEndpointThroughTheHelper(t *testing.T) {
+	mesh := mt.New(t)
+	bound := mesh.Bucket(t, "node-tools_bound")
+	assignments := mesh.Bucket(t, "mesh-controller_assignments")
+
+	mem := mt.MembershipOf("node-tools", "anchor", false, nil)
+	mem.State = []bus.StateIssued{
+		{Name: "bound", Bucket: "node-tools_bound", Writes: true},
+		{Name: "mesh-controller.assignments", Bucket: "mesh-controller_assignments"},
+	}
+	mesh.Issue(t, mem)
+
+	// claude-code, handed on this machine, is bound to node-tools here for mcp-endpoint (issue 788's plan entry).
+	plan := `{"node":"anchor","module":"claude-code","provisioning":{"provisions":[{"provision":"mcp-endpoint",` +
+		`"provider":"anchor","provider-module":"node-tools","at":"127.0.0.1","from":"anchor","as":"mesh_anchor_claude_code"}]}}`
+	if _, err := assignments.Put("anchor.claude-code", []byte(plan)); err != nil {
+		t.Fatal(err)
+	}
+
+	conn, err := bus.Connect(bus.Credential{URL: mt.URL(t), Module: "node-tools", Node: "anchor"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	conn.Logf = func(string, ...any) {}
+	t.Cleanup(conn.Close)
+	conn.Follow("node-tools")
+
+	said := &mt.Logs{}
+	t.Cleanup(Start(conn, "node-tools", "anchor", 20*time.Millisecond, said.Logf))
+
+	var entry map[string]any
+	mt.Until(t, func() error {
+		kept, err := bound.Get("anchor.claude-code.mcp-endpoint")
+		if err != nil {
+			return err
+		}
+		return json.Unmarshal(kept.Value(), &entry)
+	})
+	values, _ := entry["values"].(map[string]any)
+	for key, want := range map[string]any{"port": float64(4270), "at": "127.0.0.1", "from": "anchor"} {
+		if values[key] != want {
+			t.Errorf("the entry's %s is %v, want %v (entry %v)", key, values[key], want, entry)
+		}
+	}
+	if entry["as"] != "mesh_anchor_claude_code" {
+		t.Errorf("the entry's as is %v", entry["as"])
+	}
+	if c, has := entry["credential"]; has {
+		t.Errorf("an offer with no credential names one: %v", c)
+	}
+	if got := fill(t, factsTemplate, entry); got != factsToday {
+		t.Errorf("claude-code's facts.json fills to\n%s\nwant today's\n%s", got, factsToday)
+	}
+}
+
+// The port the offer serves is the port the manifest serves and the console listens on.
+func TestTheOfferServesThePortTheManifestServes(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Serves   map[string]map[string]any `json:"serves"`
+		Moved    bool                      `json:"moved"`
+		Provides []struct {
+			Name       string `json:"name"`
+			AnsweredBy string `json:"answered-by"`
+		} `json:"provides"`
+		Resources []struct {
+			ID string `json:"id"`
+		} `json:"resources"`
+		Build struct {
+			Artifacts []struct {
+				Name string            `json:"name"`
+				Env  map[string]string `json:"env"`
+			} `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if got := m.Serves[Provision]["port"]; got != float64(ServedPort) {
+		t.Errorf("the manifest serves %v for %s, the offer %d", got, Provision, ServedPort)
+	}
+	if m.Moved {
+		t.Error("node-tools is marked moved: that also hands the runtime's bus account to the vault (issue 791 round 1)")
+	}
+	if len(m.Provides) != 1 || m.Provides[0].Name != Provision || m.Provides[0].AnsweredBy != "helper" {
+		t.Errorf("node-tools does not say its %s is answered by the helper: %+v", Provision, m.Provides)
+	}
+	for _, r := range m.Resources {
+		if r.ID == "consumers" {
+			t.Error("the manifest still carries a consumers file the helper does not need")
+		}
+	}
+	for _, a := range m.Build.Artifacts {
+		if a.Name == "files" || len(a.Env) > 0 {
+			t.Errorf("the build still carries %+v, which only a moved module needs", a)
+		}
+	}
+}
+
+// Only the machine's runtime is the provider: a process on another credential, or with no machine, answers nobody.
+func TestOnlyTheMachinesRuntimeStartsTheHelper(t *testing.T) {
+	said := &mt.Logs{}
+	for _, c := range []struct{ module, node string }{{"claude-code", "anchor"}, {"node-tools", ""}} {
+		Start(nil, c.module, c.node, time.Second, said.Logf)()
+	}
+}