Hold a joining module at the build it ran, own its directories by its own group, and take a library only when its act is done (hq ADR 0328 review, ADR 0334)

A held module is composed exactly as before it joined, at the build its machine runs, so its port, resources and contributions stay. A joining module's directories belong to its user and its own group, and its tools' directories are refused closed to that group; the runner joins it where the engine can say so. A take records the root and is taken only when the engine states the act done. Libraries' paths and verdicts count modules pulled in by a requirement, and a unit takes the identity.
2026-10-13 00:03:18 +02:00
parent 7ea6d36eab
commit 96e15f8693
16 changed files with 763 additions and 106 deletions
@@ -88,8 +88,8 @@ func TestAJoiningModuleIsComposedWithItsIdentityAndLibraries(t *testing.T) {
 		"PUID=50020\nPGID=50010\nUSER=mesh-radarr\nGROUP=mesh-media\nUMASK=002\n" {
 		t.Errorf("the identity file reads %q", content)
 	}
-	if owner := got["radarr.config"]["owner"]; owner != "50020:50010" {
-		t.Errorf("its directory is owned by %v; want its user and primary group", owner)
+	if owner := got["radarr.config"]["owner"]; owner != "50020:50020" {
+		t.Errorf("its directory is owned by %v; want its user and own group (ADR 0334 §1)", owner)
 	}
 	if len(composed.Identities) != 1 || !reflect.DeepEqual(composed.Identities[0], IdentityEntry{Module: "radarr",
 		Name: "mesh-radarr", UID: 50020, GID: 50010, Groups: []int{50011}}) {
@@ -144,37 +144,46 @@ func TestALibraryNotReachingTheMachineLeavesItsModuleOut(t *testing.T) {
 	}
 }

-// Row 8: a joining module that ran here before keeps the user it ran as until its libraries are taken — left out, its
-// containers untouched — while its libraries are still named, so the engine states the wait and the take can come.
-func TestAJoiningModuleIsHeldUntilItsLibrariesAreTaken(t *testing.T) {
-	with := librariesRendering()
-	with.TakenLibraries["media"] = false
-	with.Held = map[string]string{"radarr": "media"}
-	composed := composeLibraries(t, Resolution{Node: "ace", Account: "jochen",
-		Modules: []Manifest{aRadarr(t), theRuntime(t)}}, with)
-	if why := composed.LeftOut["radarr"]; !strings.Contains(why, "keeps the user it ran as until the library media is taken") {
-		t.Fatalf("radarr while media is not taken: %q", why)
-	}
-	if byID(composed.Resources)["radarr.app"] != nil {
-		t.Fatal("a held module's container was sent")
-	}
-	found := false
-	for _, l := range composed.Libraries {
-		found = found || (l.Library == "media" && !l.Taken)
-	}
-	if !found {
-		t.Fatalf("the library a held module waits on is not named: %+v", composed.Libraries)
-	}
-}
-
-// Row 14: a module that neither declares libraries nor uses its identity is composed exactly as before, on an engine
-// that keeps libraries or not; and a joining module on an older engine is left out, naming why.
+// Row 14: a module that neither declares libraries nor uses its identity is composed exactly as before — the whole
+// declaration: its resources, the filter its port reaches, the contributions it makes — on an engine that keeps
+// libraries or not; on a machine a library reaches, only that library's group is added. A joining module on an older
+// engine is left out, naming why.
 func TestAModuleThatDoesNotJoinIsComposedAsBefore(t *testing.T) {
-	r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aPlain(), theRuntime(t)}}
-	before := composeLibraries(t, r, Rendering{})
-	after := composeLibraries(t, r, librariesRendering())
-	if !reflect.DeepEqual(before.Resources, after.Resources) {
-		t.Fatalf("a module that does not join composed otherwise:\n %v\n %v", before.Resources, after.Resources)
+	plain := aPlain()
+	plain.Listens = []Listening{{Port: 8080, From: FromEverywhere, Name: "web", Why: "its page"}}
+	plain.Contributes = map[string]map[string]any{"reverse-proxy": {"host": "plain", "port": 8080}}
+	plain.Requires = []string{"reverse-proxy"}
+	modules := []Manifest{plain, proxy(), {Module: "nftables", Filtering: &Filtering{Into: "/etc/mesh/filter.nft"}},
+		theRuntime(t)}
+	base := Rendering{Mesh: []string{"198.51.100.2"}, OutwardLinks: []string{"eth0"}, TunnelInterface: "mesh0"}
+	keeping := func(node string) Rendering {
+		with := librariesRendering()
+		with.Mesh, with.OutwardLinks, with.TunnelInterface = base.Mesh, base.OutwardLinks, base.TunnelInterface
+		return with
+	}
+	for _, node := range []string{"far", "ace"} {
+		r := Resolution{Node: node, Account: "jochen", Modules: modules}
+		before := composeLibraries(t, r, base)
+		after := composeLibraries(t, r, keeping(node))
+		if node == "far" {
+			if !reflect.DeepEqual(before, after) {
+				t.Fatalf("on a machine no library reaches, a module that does not join composed otherwise:\n %+v\n %+v",
+					before, after)
+			}
+			continue
+		}
+		groups := after.Groups
+		after.Groups, after.Libraries = nil, nil
+		if !reflect.DeepEqual(before, after) {
+			t.Fatalf("on %s, a module that does not join composed otherwise:\n %+v\n %+v", node, before, after)
+		}
+		if len(groups) == 0 || len(after.Identities) > 0 {
+			t.Fatalf("on the library's home: groups %v, identities %v", groups, after.Identities)
+		}
+		filter := fmt.Sprint(byID(before.Resources)["nftables."+FilteringID()]["content"])
+		if !strings.Contains(filter, "8080") || received(t, before.Resources)[0].From != "plain" {
+			t.Fatalf("the comparison held no filter or contribution of the module: %s", filter)
+		}
 	}
 	if Joins(aPlain()) || !Joins(aRadarr(t)) {
 		t.Fatal("joining is not read from the libraries and the identity")
@@ -338,3 +347,73 @@ func TestTheEngineTakesWhatIsComposedForLibraries(t *testing.T) {
 		}
 	}
 }
+
+// novox/hq ADR 0334 §1, §2 (the review of 7ea6d36e, item 2): a joining module's own directories are owned by its user
+// and its own group, not the library's; and the tool runner's account joins the own group of every joining module whose
+// tools run on the machine — sent only to an engine that reads it (link.OwnGroupContract).
+func TestAJoiningModulesOwnDirectoriesAreItsOwnGroups(t *testing.T) {
+	r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aRadarr(t), theRuntime(t)}}
+	got := byID(composeLibraries(t, r, librariesRendering()).Resources)
+	if owner := got["radarr.config"]["owner"]; owner != "50020:50020" {
+		t.Errorf("its directory is owned by %v; want its user and its own group", owner)
+	}
+	if env := got["radarr.app"]["env"].(map[string]any); env["PGID"] != "50010" {
+		t.Errorf("its process's primary group is %v; want the library's, so what it makes there keeps the group", env["PGID"])
+	}
+	older := composeLibraries(t, r, librariesRendering())
+	if older.Identities[0].Runner != "" {
+		t.Errorf("an engine that cannot put the runner in a module's own group was told %q", older.Identities[0].Runner)
+	}
+	with := librariesRendering()
+	with.RunnerJoinsOwnGroups = true
+	if got := composeLibraries(t, r, with).Identities[0].Runner; got != "jochen" {
+		t.Errorf("the runner joins %q's own group; want jochen, whose tools it runs", got)
+	}
+}
+
+// novox/hq ADR 0334 §3: a joining module whose tools name a directory whose mode closes it to its group is refused at
+// the module check, naming the directory.
+func TestAToolsDirectoryIsOpenToItsGroup(t *testing.T) {
+	closed := map[string]any{
+		"libraries": []any{map[string]any{"id": "movies", "library": "media", "path": "movies", "use": "read"}},
+		"resources": []any{
+			map[string]any{"id": "config", "type": "directory", "mode": "0700"},
+			map[string]any{"id": "app", "type": "container", "name": "app", "image": libraryImage,
+				"volumes": []any{"${dir:config}:/config", "${library:movies}:/movies"}}},
+		"build": map[string]any{"artifacts": []any{map[string]any{"name": "tools", "kind": "bundle",
+			"language": "go", "system": "arch", "from": "cmd/app", "binary": "app", "loads": []any{"app"},
+			"env": map[string]any{"APP_CONFIG": "${dir:config}/config.xml"}}}}}
+	_, err := ParseManifest(libraryManifest(t, closed))
+	if err == nil || !strings.Contains(err.Error(), "config") || !strings.Contains(err.Error(), "ADR 0334") {
+		t.Fatalf("a tools' directory closed to its group: %v", err)
+	}
+	open := closed
+	open["resources"] = []any{
+		map[string]any{"id": "config", "type": "directory", "mode": "0750"},
+		map[string]any{"id": "app", "type": "container", "name": "app", "image": libraryImage,
+			"volumes": []any{"${dir:config}:/config", "${library:movies}:/movies"}}}
+	if _, err := ParseManifest(libraryManifest(t, open)); err != nil {
+		t.Fatalf("a tools' directory open to its group was refused: %v", err)
+	}
+}
+
+// The review of 7ea6d36e, item 6: a service's unit takes the identity too — `User=${identity:user}` — at the module
+// check and in what is composed.
+func TestAServicesUnitTakesTheIdentity(t *testing.T) {
+	unit := "[Service]\nUser=${identity:user}\nGroup=${identity:group}\nUMask=0002\nExecStart=/usr/bin/importer\n"
+	raw := libraryManifest(t, map[string]any{"resources": []any{
+		map[string]any{"id": "app", "type": "container", "name": "app", "image": libraryImage,
+			"volumes": []any{"${library:movies}:/movies"}},
+		map[string]any{"id": "watch", "type": "service", "name": "app-watch", "unit": unit}}})
+	m, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatalf("a unit naming the identity was refused: %v", err)
+	}
+	with := librariesRendering()
+	with.Identities["app"] = ModuleIdentity{Module: "app", UID: 50030}
+	composed := composeLibraries(t, Resolution{Node: "ace", Modules: []Manifest{m}}, with)
+	got := fmt.Sprint(byID(composed.Resources)["app.watch"]["unit"])
+	if !strings.Contains(got, "User=mesh-app\nGroup=mesh-media\n") {
+		t.Fatalf("the unit reads %q", got)
+	}
+}