node hand-over: the terminal hands a directory used as found to the mesh, asked of the node's engine (hq issue 356)

A module's condition told the operator to run the node-engine's hand-over at the machine, as root (issue 339), and the mesh had no channel for it. Now node hand-over <node> <path> is the controller's terminal's — a node subcommand that is not a read, so every verb and mesh-cli outside the terminal refuse it — and asks that node's engine on mesh.node.<node>.ask.hand-over, a request only the controller may publish and only that node's engine may hear and answer (its grant gains the subject and the right to answer what it was asked). The line's node and path are judged before anything is asked; the engine's answer is printed, a refusal as a refusal. Every text addressed to the operator names the nox line (ADR 0272); the condition's words stay plain.

cmd/mesh-controller/nodes.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"net"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -17,6 +18,7 @@ import (
 	"github.com/novox/mesh-controller/internal/catalogue"
 	"github.com/novox/mesh-controller/internal/conditions"
 	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
 	"github.com/novox/mesh-controller/internal/token"
 )
 
@@ -28,7 +30,7 @@ import (
 
 func nodeCommand(ctx context.Context, args []string) error {
 	if len(args) == 0 {
-		return errors.New("node add <name>, node list, node show <name>, or " + publicDomainUsage)
+		return errors.New("node add <name>, node list, node show <name>, " + publicDomainUsage + ", or " + handOverUsage)
 	}
 	open, err := openStores(ctx)
 	if err != nil {
@@ -112,11 +114,82 @@ func nodeCommand(ctx context.Context, args []string) error {
 		// an optional second argument is the home when it is not /home/<account>.
 		return nodeAccount(ctx, inv, args[1:])
 
+	case "hand-over":
+		// A directory the node-engine uses as found, handed to the mesh (novox/hq issue 356, issue 339). Here, at
+		// the controller's terminal, and nowhere else: at the next apply root gives the directory to the account
+		// the module declares, and whoever may call a verb includes agents.
+		return nodeHandOver(ctx, inv, args[1:])
+
 	default:
-		return fmt.Errorf("node has no %q; it has add, list, show, public-domain, account and agent-account", args[0])
+		return fmt.Errorf("node has no %q; it has add, list, show, public-domain, account, agent-account and hand-over", args[0])
 	}
 }
 
+const handOverUsage = "node hand-over <node> <directory> — hand a directory the node-engine on <node> uses as found " +
+	"to the mesh: its next apply gives it the declared owner and mode. The directory's absolute path, as the module's " +
+	"condition names it"
+
+// handOverLine reads a hand-over's line: the node and the directory's absolute path, exactly as the engine states
+// it. Judged before anything is asked, and judged again by the engine, which is the one that acts.
+func handOverLine(args []string) (node, path string, err error) {
+	if len(args) != 2 {
+		return "", "", errors.New(handOverUsage)
+	}
+	node, path = args[0], args[1]
+	if node == "" || strings.HasPrefix(node, "-") {
+		return "", "", fmt.Errorf("%q is not a node's name; %s", node, handOverUsage)
+	}
+	if !filepath.IsAbs(path) {
+		return "", "", fmt.Errorf("%q is not an absolute path; %s", path, handOverUsage)
+	}
+	if filepath.Clean(path) != path {
+		return "", "", fmt.Errorf("%q is not the directory's path as the engine states it (no `..`, no doubled or "+
+			"trailing separator); %s", path, handOverUsage)
+	}
+	return node, path, nil
+}
+
+// handOverBy is who hands the directory over, in the words a verb's caller is recorded in: the operator through
+// mesh-cli on the control-node, or whoever runs this controller's binary at its terminal.
+func handOverBy() string {
+	if by := strings.TrimSpace(os.Getenv(link.CallerVar)); by != "" {
+		return by
+	}
+	return "the controller's terminal"
+}
+
+// nodeHandOver asks the node's engine to take a directory it uses as found as the mesh's, and says what came of
+// it. The engine records the hand-over or refuses; nothing is recorded here, because the directory is the
+// machine's and the engine is the one that reads it.
+func nodeHandOver(ctx context.Context, inv *inventory.Inventory, args []string) error {
+	node, path, err := handOverLine(args)
+	if err != nil {
+		return err
+	}
+	if _, err := inv.NodeByName(ctx, node); err != nil {
+		return err
+	}
+	address, err := broker.BusAddress()
+	if err != nil {
+		return err
+	}
+	js, err := broker.Dial(address)
+	if err != nil {
+		return fmt.Errorf("cannot reach the bus, so nothing was asked of %s: %w", node, err)
+	}
+	defer js.Close()
+	answer, err := link.AskHandOver(ctx, js.Conn(), node, path, handOverBy(), link.HandOverWithin)
+	if err != nil {
+		return err
+	}
+	if answer.Refused != "" {
+		return fmt.Errorf("%s refused: %s", node, answer.Refused)
+	}
+	fmt.Println(answer.Said)
+	fmt.Printf("  the module's condition clears once %s applies; `nox push %s` applies it now\n", node, node)
+	return nil
+}
+
 // addNode creates a node record, adopted when the operator says so (novox/hq ADR 0100).
 func addNode(ctx context.Context, inv *inventory.Inventory, args []string) error {
 	set := flag.NewFlagSet("node add", flag.ContinueOnError)