Report what an adopted node holds, its firewall and what is reachable, and speak unasked when that changes (hq ADR 0100)

internal/link/messages.go

@@ -1,5 +1,7 @@
 package link
 
+import "time"
+
 // The wire formats shared with the control plane, which defines them separately because this
 // binary requires nothing present and does not import it. A test on each side asserts the field
 // names, so a rename breaks both at once rather than on a real machine months later.
@@ -85,4 +87,44 @@ type Report struct {
 	// than the send, and the machine reads as caught up with words it has not read yet. Clocks
 	// cannot answer "which"; the digest is the answer itself.
 	Declared string `json:"declared,omitempty"`
+
+	// Held is what this adopted node found and is keeping as it was until its module is taken
+	// (novox/hq ADR 0100). Without it an adopted node reads as converged.
+	Held []Held `json:"held,omitempty"`
+
+	// Firewall is the firewall found on this machine — "ufw" or "none" — and empty on a node that
+	// was never asked, which is every converged one.
+	Firewall string `json:"firewall,omitempty"`
+
+	// Reachable is what can be reached on this machine now: every listening socket and every
+	// published container port. Only an adopted node reports it; it is what converging the node
+	// previews, so nothing closes without being named first.
+	Reachable []Reach `json:"reachable,omitempty"`
+}
+
+// Held is one file or container found on an adopted node and kept as it was.
+type Held struct {
+	ID     string    `json:"id"`
+	Module string    `json:"module"`
+	Kind   string    `json:"kind"`
+	Target string    `json:"target"`
+	Since  time.Time `json:"since"`
+	// Changed is what something other than the mesh did to it since — rewritten, stopped,
+	// replaced or gone — and empty while it is as found.
+	Changed string `json:"changed,omitempty"`
+	// Kept is where a file's original was kept.
+	Kept string `json:"kept,omitempty"`
+}
+
+// Reach is one thing reachable on the machine: a listening socket, or a published container port.
+type Reach struct {
+	Protocol string `json:"protocol"`
+	Address  string `json:"address"`
+	Port     int    `json:"port"`
+	// By is what holds it — a process, or a container's name.
+	By string `json:"by,omitempty"`
+	// Published is a container port the runtime publishes, reached on the forwarded path; its
+	// container's own port is ContainerPort.
+	Published     bool `json:"published,omitempty"`
+	ContainerPort int  `json:"container-port,omitempty"`
 }

internal/link/messages_test.go

@@ -120,6 +120,14 @@ func TestTheWireFormatIsExactlyTheseFieldNames(t *testing.T) {
 		{Signed{Declaration: []byte("{}"), Signature: []byte("x")}, []string{"declaration", "signature"}},
 		{Report{Node: "n", Applied: []string{"a"}, Failed: map[string]string{"k": "v"}, Refused: "r"},
 			[]string{"node", "applied", "failed", "refused"}},
+		// novox/hq ADR 0100: what an adopted node holds, the firewall it was found with, and what
+		// is reachable on it.
+		{Report{Node: "n", Held: []Held{{ID: "i"}}, Firewall: "ufw", Reachable: []Reach{{Port: 1}}},
+			[]string{"node", "held", "firewall", "reachable"}},
+		{Held{ID: "i", Module: "m", Kind: "file", Target: "/t", Changed: "rewritten", Kept: "/k"},
+			[]string{"id", "module", "kind", "target", "since", "changed", "kept"}},
+		{Reach{Protocol: "tcp", Address: "0.0.0.0", Port: 8080, By: "c", Published: true, ContainerPort: 80},
+			[]string{"protocol", "address", "port", "by", "published", "container-port"}},
 	} {
 		raw, err := json.Marshal(c.value)
 		if err != nil {

internal/link/run.go

@@ -70,15 +70,21 @@ type Announce func(string)
 type Roused <-chan struct{}
 
 func Hold(ctx context.Context, m Membership, apply Applier, say Announce, timeout time.Duration) error {
-	return HoldRoused(ctx, m, apply, say, timeout, nil)
+	return HoldRoused(ctx, m, apply, say, timeout, nil, nil)
 }
 
-// HoldRoused is Hold, told when the machine has reason to think its link is stale.
+// Outbox carries reports the node has to say without having been sent anything — what a
+// reconcile found changed on an adopted node (novox/hq ADR 0100). Published while the link is up;
+// a report made while it is down waits in the channel for the next one. Nil is allowed.
+type Outbox <-chan Report
+
+// HoldRoused is Hold, told when the machine has reason to think its link is stale, and handed
+// reports to publish between deliveries.
 func HoldRoused(ctx context.Context, m Membership, apply Applier, say Announce,
-	timeout time.Duration, roused Roused) error {
+	timeout time.Duration, roused Roused, outbox Outbox) error {
 
 	return holdWith(ctx, func(ctx context.Context) error {
-		return Run(ctx, m, apply, say, timeout)
+		return Run(ctx, m, apply, say, timeout, outbox)
 	}, say, roused)
 }
 
@@ -171,7 +177,8 @@ func holdWith(ctx context.Context, run attempt, say Announce, roused Roused) err
 //
 // Outbound only, and nothing listens on this machine. Returns when the link ends, for any reason;
 // Hold is what decides whether to open it again.
-func Run(ctx context.Context, m Membership, apply Applier, say Announce, timeout time.Duration) error {
+func Run(ctx context.Context, m Membership, apply Applier, say Announce, timeout time.Duration,
+	outbox Outbox) error {
 	if say == nil {
 		say = func(string) {}
 	}
@@ -254,6 +261,10 @@ func Run(ctx context.Context, m Membership, apply Applier, say Announce, timeout
 			return nil
 		case <-beat.C:
 			publishAlive(ctx, channel, m, say, timeout)
+		case report := <-outbox:
+			// Said without having been asked: a reconcile found what an adopted node holds, or
+			// its firewall, changed since it last said.
+			publishReport(ctx, channel, m, report, say, timeout)
 		case reason := <-closed:
 			return fmt.Errorf("the link closed: %v", reason)
 		case delivery, ok := <-deliveries: