Give every module an identity and ask once to keep a shared folder (hq ADR 0325, issue 575)
A module's containers that declare identity run as an identity the controller allocates once, mesh-wide, from 50000-59999; each access names its users and whether its folder is taken; an access wait is excused for a folder the mesh may not keep yet, and the operator is asked once per folder and machine, the folder taken only on the warrant. All of it is sent only to an engine at contract 5. A placement for an access a newer build brings is judged against that build (issue 575). mesh-host pinned to the ADR 0325 branch head.
This commit is contained in:
@@ -343,6 +343,11 @@ func AskJudgeDirectoriesSubject(node string) string {
|
||||
return "mesh.node." + node + ".ask.judge-directories"
|
||||
}
|
||||
|
||||
// AskAccessActSubject is where the controller asks one machine's node-engine to take a shared folder on the
|
||||
// operator's warrant (novox/hq ADR 0325 §8; mesh-host internal/link AskAccessActSubject): a request answered once,
|
||||
// signed as a hand-over is (link.AccessActContext), for the same reason.
|
||||
func AskAccessActSubject(node string) string { return "mesh.node." + node + ".ask.access-act" }
|
||||
|
||||
// inbox is a principal's own reply space. No user is ever granted a bare `_INBOX.>` (design 25
|
||||
// §4): with one account, inbox privacy is the permission list or it is nothing, so each user's
|
||||
// inbox is derived from its own identity and its permissions name that prefix and no other.
|
||||
@@ -623,7 +628,9 @@ func PermissionsFor(p Principal) (Permissions, error) {
|
||||
// And asking it for a fresh search for setuid programs (novox/hq issue 361), answered the same way.
|
||||
AskSetuidSearchSubject(p.Node),
|
||||
// And asking it to judge its declared directories, read-only (novox/hq issue 358), answered the same way.
|
||||
AskJudgeDirectoriesSubject(p.Node)}
|
||||
AskJudgeDirectoriesSubject(p.Node),
|
||||
// And asking it to take a shared folder on the operator's warrant (novox/hq ADR 0325 §8), answered the same way.
|
||||
AskAccessActSubject(p.Node)}
|
||||
// The node-engine witnesses the core builds it places (novox/hq to-be 45 §8, ADR 0236; the
|
||||
// contract is lease/witness.go): it asks its own machine's node tools PING, and, where the
|
||||
// machine runs the controller, reads the lease's one key — read, never written.
|
||||
|
||||
+1
-1
@@ -34,7 +34,7 @@ accounts {
|
||||
} }
|
||||
{ user: "node.one", password: "$2a$11$nnnnnnnnnnnnnnnnnnnnnn", permissions: {
|
||||
publish: { allow: ["$JS.ACK.NODES.one.>", "$JS.API.CONSUMER.INFO.NODES.one", "$SRV.PING.node-tools.one", "mesh.control.one.>"] }
|
||||
subscribe: { allow: ["_DELIVER.one", "_DELIVER.one.>", "_INBOX.node.one.>", "mesh.node.one.ask.hand-over", "mesh.node.one.ask.judge-directories", "mesh.node.one.ask.report", "mesh.node.one.ask.setuid-search", "mesh.node.one.declare"] }
|
||||
subscribe: { allow: ["_DELIVER.one", "_DELIVER.one.>", "_INBOX.node.one.>", "mesh.node.one.ask.access-act", "mesh.node.one.ask.hand-over", "mesh.node.one.ask.judge-directories", "mesh.node.one.ask.report", "mesh.node.one.ask.setuid-search", "mesh.node.one.declare"] }
|
||||
allow_responses: { max: 1, ttl: "1m" }
|
||||
} }
|
||||
{ user: "one.nats", password: "$2a$11$bbbbbbbbbbbbbbbbbbbbbb", permissions: {
|
||||
|
||||
@@ -101,6 +101,11 @@ var WritersTable = []WriterRow{
|
||||
{State: "a judgement of a machine's directories asked of it", Writer: "controller",
|
||||
KeptIn: "nowhere: the engine answers it and keeps nothing", Others: "the engine verifies the mesh's signature and answers, or refuses",
|
||||
Subjects: []string{"mesh.node.*.ask.judge-directories"}, Writes: isController},
|
||||
// The take of a shared folder asked of a machine's engine on the operator's warrant (novox/hq ADR 0325 §8):
|
||||
// signed as a hand-over is, under a signing context of its own.
|
||||
{State: "the take of a shared folder asked of a machine", Writer: "controller, on the operator's warrant",
|
||||
KeptIn: "the machine, which records the act", Others: "the engine verifies the mesh's signature and takes it, or refuses",
|
||||
Subjects: []string{"mesh.node.*.ask.access-act"}, Writes: isController},
|
||||
{State: "a machine's applied state and its report", Writer: "the node-engine's apply queue",
|
||||
KeptIn: "the machine; the report on the bus", Others: "the reconcile and a delivery enqueue, never apply",
|
||||
// And its health statement between reports (novox/hq ADR 0240): the same writer stating the same
|
||||
|
||||
@@ -18,6 +18,7 @@ var designRows = []string{
|
||||
"a hand-over asked of a machine",
|
||||
"a fresh setuid search asked of a machine",
|
||||
"a judgement of a machine's directories asked of it",
|
||||
"the take of a shared folder asked of a machine",
|
||||
"a machine's applied state and its report",
|
||||
"the controller lease",
|
||||
"plans and their tiers",
|
||||
|
||||
@@ -939,14 +939,16 @@ func replaceGoFiles(from, into string) error {
|
||||
}
|
||||
|
||||
// problemLines are the lines of a module check's output that name a problem: not a manifest found ok, not
|
||||
// the count, not the closing note.
|
||||
// the count, not the closing note, not a warning.
|
||||
func problemLines(s string) []string {
|
||||
var out []string
|
||||
for _, line := range strings.Split(s, "\n") {
|
||||
line = strings.TrimSpace(line)
|
||||
switch {
|
||||
case line == "", strings.Contains(line, ": ok"), strings.Contains(line, "problem(s) in"),
|
||||
strings.Contains(line, "manifest(s) checked"):
|
||||
strings.Contains(line, "manifest(s) checked"),
|
||||
// A warning is said and fails nothing (novox/hq ADR 0325: what is refused once the catalogues moved).
|
||||
strings.HasPrefix(line, "warning: "):
|
||||
continue
|
||||
}
|
||||
out = append(out, line)
|
||||
|
||||
@@ -246,6 +246,21 @@ type Rendering struct {
|
||||
// statement's contract is link.RootContract or later). To an older, strict engine the field is not
|
||||
// sent, and the account it names is not judged — which the self-check says, as not judged.
|
||||
JudgesRoot bool
|
||||
|
||||
// KeepsFolders says this machine's node-engine gives modules their identities and keeps shared folders
|
||||
// (novox/hq ADR 0325: its statement's contract is link.IdentityContract or later). To an older, strict engine none of
|
||||
// it is sent — no `identities`, no container `identity`, no access `users` or `taken`, no owner derived from an
|
||||
// identity — and what it runs is composed as before.
|
||||
KeepsFolders bool
|
||||
// Identities is each module's allocated identity, by module (ADR 0325 §3): the same on every machine. A module
|
||||
// that declares `identity` and has none here is composed without one, as to an older engine.
|
||||
Identities map[string]ModuleIdentity
|
||||
// KeptFolders is every folder the operator let the mesh keep on this machine (ADR 0325 §8), by its clean path.
|
||||
KeptFolders map[string]bool
|
||||
// AccountUIDs is the user number of each account a tool runner runs as here, where the mesh knows it: an access
|
||||
// names the runner's account only with its number, which the node-engine requires (ADR 0325 §4). Nothing states
|
||||
// it to the controller yet, so it is empty and no runner entry is sent.
|
||||
AccountUIDs map[string]int
|
||||
}
|
||||
|
||||
// RootField is a user resource's field saying the account must never become root without a person
|
||||
@@ -320,6 +335,9 @@ type Composed struct {
|
||||
// naming its module and why (novox/hq ADR 0255): that piece is left out and the machine is told
|
||||
// everything else. Push and plan say it; the merge gate refuses a change that adds one.
|
||||
Unplaced []string
|
||||
// Identities is the declaration's `identities` (novox/hq ADR 0325 §3): [{module, name, uid, gid}] for each
|
||||
// module composed with an identity. Empty to an engine that does not keep folders.
|
||||
Identities []map[string]any
|
||||
}
|
||||
|
||||
// ForeseenSealed is what stands for an own secret a send will make, in a composition asked ahead of
|
||||
@@ -358,7 +376,9 @@ func (r Resolution) LeftOutBecause(settings SettingsBy, adopted bool) map[string
|
||||
out[m.Module] = &UnreadManifestError{Module: m.Module, said: why}
|
||||
continue
|
||||
}
|
||||
if err := JudgeSettings(m, settings[m.Module], adopted); err != nil {
|
||||
// A placement stored ahead of the build that declares its access is passed by, not a reason to leave the
|
||||
// module out (novox/hq issue 575): it was judged against that build where it was stored.
|
||||
if err := ComposesWith(m, settings[m.Module], adopted); err != nil {
|
||||
out[m.Module] = err
|
||||
}
|
||||
}
|
||||
@@ -380,7 +400,8 @@ func (r Resolution) Compose(with Rendering) (Composed, error) {
|
||||
received := map[string]map[string][]Contribution{}
|
||||
leftOut := map[string]string{}
|
||||
var foreseen, unplaced []string
|
||||
resources, err := r.compose(with, owner, received, leftOut, &foreseen, &unplaced)
|
||||
var identities []ModuleIdentity
|
||||
resources, err := r.compose(with, owner, received, leftOut, &foreseen, &unplaced, &identities)
|
||||
if err != nil {
|
||||
return Composed{}, err
|
||||
}
|
||||
@@ -394,8 +415,12 @@ func (r Resolution) Compose(with Rendering) (Composed, error) {
|
||||
})
|
||||
}
|
||||
sort.Strings(unplaced)
|
||||
return Composed{Resources: resources, Owner: owner, Received: received, LeftOut: leftOut,
|
||||
Foreseen: foreseen, Unplaced: unplaced}, nil
|
||||
composed := Composed{Resources: resources, Owner: owner, Received: received, LeftOut: leftOut,
|
||||
Foreseen: foreseen, Unplaced: unplaced}
|
||||
if len(identities) > 0 {
|
||||
composed.Identities = identitiesOf(identities)
|
||||
}
|
||||
return composed, nil
|
||||
}
|
||||
|
||||
// BusMembershipID names the resource carrying a machine's membership for the new bus, and
|
||||
@@ -406,7 +431,7 @@ const BusMembershipPath = "/var/lib/mesh/membership-next.json"
|
||||
|
||||
func (r Resolution) compose(with Rendering, owner map[string]string,
|
||||
received map[string]map[string][]Contribution, leftOut map[string]string,
|
||||
foreseen, unplaced *[]string) ([]map[string]any, error) {
|
||||
foreseen, unplaced *[]string, identities *[]ModuleIdentity) ([]map[string]any, error) {
|
||||
// **A setting is judged where it is stored, and an impossible one costs a module, not a
|
||||
// machine** (novox/hq ADR 0163, rule 6). A definition that moved under a stored setting makes
|
||||
// this module uncomposable; it is left out of the declaration — its held things kept, its
|
||||
@@ -553,6 +578,16 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
|
||||
}
|
||||
resources := m.Resources
|
||||
|
||||
// The identity it runs as here (novox/hq ADR 0325 §3, §11): none to an older engine, nor without an allocation.
|
||||
ident, hasIdent, err := identityFor(m, with)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if hasIdent && identities != nil {
|
||||
*identities = append(*identities, ident)
|
||||
}
|
||||
mountedByIdentity := dirsMountedByIdentity(m)
|
||||
|
||||
// What the mesh computes for this module goes FIRST, before the module's own resources.
|
||||
//
|
||||
// **Order is stated, not derived — the host does not sort** (novox/hq ADR 0005), so
|
||||
@@ -1003,6 +1038,11 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
|
||||
return nil, err
|
||||
}
|
||||
ownerInto(copied, placed)
|
||||
// And its identity (novox/hq ADR 0325 §2, §3): a container's resolved, or taken out where none is composed;
|
||||
// the owner of a directory its identity's containers mount. After the placement's owner: the identity wins.
|
||||
if err := identityInto(copied, m, ident, hasIdent, mountedByIdentity); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
// **After settings, and that is the whole reason it is here.** A module's file
|
||||
// content is where a setting lands, so a placeholder may only exist once the setting
|
||||
// has been put in — filling secrets first would look at content that is not yet what
|
||||
@@ -1120,6 +1160,12 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
|
||||
out = append(out, copied)
|
||||
}
|
||||
|
||||
// **Who uses each of its shared folders** (novox/hq ADR 0325 §4, §5, §8): the access's `users` and `taken`, to
|
||||
// an engine that keeps folders.
|
||||
if with.KeepsFolders {
|
||||
usersInto(out, owner, m, ident, hasIdent, r.toolsAccount(m, with), with)
|
||||
}
|
||||
|
||||
// **What only the mesh knows, where this module asked for it.** The graph is the control
|
||||
// plane's; making a name resolve is the module's software. Emitted as ordinary files under
|
||||
// this module's name, so they are applied, reported and removed exactly as anything else
|
||||
|
||||
@@ -1860,6 +1860,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
|
||||
problems = append(problems, replacesProblems(m)...)
|
||||
problems = append(problems, UnitSettingProblems(m)...)
|
||||
problems = append(problems, OwnerSettingProblems(m)...)
|
||||
// How each container's image is told who to run as, and what a module that says so is held to (novox/hq ADR 0325).
|
||||
problems = append(problems, identityProblems(m)...)
|
||||
problems = append(problems, endpointNameProblems(m)...)
|
||||
problems = append(problems, RouteProblems(m)...)
|
||||
for _, port := range m.Guards {
|
||||
|
||||
@@ -0,0 +1,514 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Every module is given an identity of its own, and a container that declares `identity` runs as it (novox/hq ADR
|
||||
// 0325 §2, §3, §11).
|
||||
//
|
||||
// **The manifest says how its image is told who to run as, and nothing else.** A container resource may declare
|
||||
// `identity`: `{"user": "env:PUID", "group": "env:PGID"}` for an image that reads its user and group from its
|
||||
// environment, or `{"user": "run"}` for the container runtime's own user option. It is the image's interface, as its
|
||||
// ports are. The mesh fills it in: the controller allocates the module one user and group number, mesh-wide, once,
|
||||
// from a range of its own (IdentityLow–IdentityHigh), and the node-engine makes the account `mesh-<module>` on each
|
||||
// machine the module is assigned to and tells the image those numbers.
|
||||
//
|
||||
// **The range is 50000–59999, and a module's user and group numbers are one number.** Chosen above the numbers
|
||||
// distributions give people (1000 up) and below the 60000s Debian keeps for its own daemons, and far from root's 0
|
||||
// and every root group a distribution ships (0, adm's 4, wheel's 10): no number in it is 0 or a root group's, so §11
|
||||
// holds by the range alone, and the store refuses a row outside it. Both numbers come from one sequence, so a
|
||||
// module's uid and gid are equal; a number once given is never given again, even after the module is forgotten
|
||||
// (the store keeps the row, inventory.AllocateIdentity).
|
||||
//
|
||||
// **What the controller sends, and only to an engine that reads it** (Rendering.KeepsFolders: its statement's
|
||||
// contract is link.IdentityContract or later):
|
||||
//
|
||||
// - the declaration's `identities`: [{module, name, uid, gid}] for each module of the machine that declares
|
||||
// `identity` on a container;
|
||||
// - a container's `identity` resolved: {"mode": "env", "user_env", "group_env", "uid", "gid"} or {"mode": "run",
|
||||
// "uid", "gid"};
|
||||
// - the owner of each of the module's directories a container declaring `identity` mounts: the identity's
|
||||
// uid:gid (§3). A directory only a process or the tools write keeps the owner it had: what writes it is not the
|
||||
// identity, and owning it by the identity would lock its writer out;
|
||||
// - an access's `users`: the module's identity where a container of it that declares `identity` mounts the
|
||||
// access, and the tool runner's account where the module's tools run there and the account's number is known,
|
||||
// each at the access's use — the node-engine keeps one entry per user on a folder at the widest use any access
|
||||
// to it gives (§4, §5), so the runner's entry is the widest of the modules whose tools use it; and `taken`,
|
||||
// whether the operator let the mesh keep that folder on that machine (§8).
|
||||
//
|
||||
// To an older engine none of it is sent, and a container's `identity` is taken out: it runs as its image says, as
|
||||
// before. A module that declares no `identity` is composed exactly as before, on any engine.
|
||||
|
||||
// The range module identities are allocated from (novox/hq ADR 0325 §3, §11). The store holds the same bounds.
|
||||
const (
|
||||
IdentityLow = 50000
|
||||
IdentityHigh = 59999
|
||||
)
|
||||
|
||||
// AllocatableID says whether n is a number the mesh may give a module's identity: inside the range, so never 0
|
||||
// nor a root group's.
|
||||
func AllocatableID(n int) bool { return n >= IdentityLow && n <= IdentityHigh }
|
||||
|
||||
// IdentityField is a container resource's field saying how its image is told who to run as.
|
||||
const IdentityField = "identity"
|
||||
|
||||
// The two ways an image is told who to run as.
|
||||
const (
|
||||
IdentityEnv = "env"
|
||||
IdentityRun = "run"
|
||||
)
|
||||
|
||||
// IdentitySpec is a container's `identity` as its manifest declares it.
|
||||
type IdentitySpec struct {
|
||||
// Mode is IdentityEnv or IdentityRun.
|
||||
Mode string
|
||||
// UserEnv and GroupEnv are the environment variables an env image reads, such as PUID and PGID.
|
||||
UserEnv, GroupEnv string
|
||||
}
|
||||
|
||||
// ModuleIdentity is one module's allocated identity: its numbers, the same on every machine.
|
||||
type ModuleIdentity struct {
|
||||
Module string
|
||||
UID int
|
||||
GID int
|
||||
}
|
||||
|
||||
// IdentityName is the account a module's identity is on every machine it is assigned to.
|
||||
func IdentityName(module string) string { return "mesh-" + module }
|
||||
|
||||
// Where an access's user comes from (novox/hq ADR 0325 §4, §5).
|
||||
const (
|
||||
FromContainer = "container"
|
||||
FromToolRunner = "tool-runner"
|
||||
)
|
||||
|
||||
// AccessUser is one identity that uses a shared folder, as an access's `users` names it (mesh-host internal/declaration
|
||||
// AccessUser): the account, its user number, the use, and where it runs. The node-engine refuses a user with no
|
||||
// number, so the tool runner's account is named only where its number is known (Rendering.AccountUIDs).
|
||||
type AccessUser struct {
|
||||
Identity string `json:"identity"`
|
||||
UID int `json:"uid"`
|
||||
Use string `json:"use"`
|
||||
From string `json:"from"`
|
||||
}
|
||||
|
||||
var envName = regexp.MustCompile(`^[A-Z_][A-Z0-9_]*$`)
|
||||
|
||||
// ParseIdentity reads a container's `identity`, or refuses it in words.
|
||||
func ParseIdentity(v any) (IdentitySpec, error) {
|
||||
fields, ok := v.(map[string]any)
|
||||
if !ok {
|
||||
return IdentitySpec{}, fmt.Errorf("identity is {\"user\": \"env:<NAME>\", \"group\": \"env:<NAME>\"} or " +
|
||||
"{\"user\": \"run\"}")
|
||||
}
|
||||
for k := range fields {
|
||||
if k != "user" && k != "group" {
|
||||
return IdentitySpec{}, fmt.Errorf("identity says %q, and it says only how the image is told its user "+
|
||||
"and group: \"user\" and \"group\", never an owner or a number (%s §1, §2)", k, ADR0325)
|
||||
}
|
||||
}
|
||||
user, _ := fields["user"].(string)
|
||||
group, hasGroup := fields["group"]
|
||||
switch {
|
||||
case user == IdentityRun:
|
||||
if hasGroup {
|
||||
return IdentitySpec{}, fmt.Errorf("identity {\"user\": \"run\"} takes no group: the runtime's user " +
|
||||
"option carries both numbers")
|
||||
}
|
||||
return IdentitySpec{Mode: IdentityRun}, nil
|
||||
case strings.HasPrefix(user, "env:"):
|
||||
g, _ := group.(string)
|
||||
if !strings.HasPrefix(g, "env:") {
|
||||
return IdentitySpec{}, fmt.Errorf("identity names its user as %q and its group as %v; an image told "+
|
||||
"its user by its environment is told its group the same way, \"env:<NAME>\"", user, group)
|
||||
}
|
||||
u, gr := strings.TrimPrefix(user, "env:"), strings.TrimPrefix(g, "env:")
|
||||
if !envName.MatchString(u) || !envName.MatchString(gr) || u == gr {
|
||||
return IdentitySpec{}, fmt.Errorf("identity names the variables %q and %q; each is an environment "+
|
||||
"variable's name, upper-case letters, digits and underscores, and the two differ", u, gr)
|
||||
}
|
||||
return IdentitySpec{Mode: IdentityEnv, UserEnv: u, GroupEnv: gr}, nil
|
||||
}
|
||||
return IdentitySpec{}, fmt.Errorf("identity says its user is %q; it is \"env:<NAME>\" or \"run\"", user)
|
||||
}
|
||||
|
||||
// DeclaresIdentity says a module has a container that declares `identity`: it is given one (§3).
|
||||
func DeclaresIdentity(m Manifest) bool {
|
||||
for _, r := range m.Resources {
|
||||
if fmt.Sprint(r["type"]) == "container" {
|
||||
if _, has := r[IdentityField]; has {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// containerMounts is what a container of the manifest mounts, read from its volumes as written: the module's own
|
||||
// directories by id, and its accesses by id — or, for a literal source, as "path:<path>".
|
||||
func containerMounts(r map[string]any) (dirs, accesses []string) {
|
||||
volumes, _ := r["volumes"].([]any)
|
||||
for _, v := range volumes {
|
||||
s, _ := v.(string)
|
||||
source := volumeSource(s)
|
||||
if strings.HasPrefix(source, "/") {
|
||||
accesses = append(accesses, "path:"+filepath.Clean(source))
|
||||
continue
|
||||
}
|
||||
for _, m := range dirRef.FindAllStringSubmatch(source, -1) {
|
||||
dirs = append(dirs, m[1])
|
||||
}
|
||||
for _, m := range accessRef.FindAllStringSubmatch(source, -1) {
|
||||
accesses = append(accesses, m[1])
|
||||
}
|
||||
}
|
||||
return dirs, accesses
|
||||
}
|
||||
|
||||
// volumeSource is a volume's source as written: up to its first colon outside a ${…} placeholder, so
|
||||
// "${dir:config}:/config" is "${dir:config}".
|
||||
func volumeSource(v string) string {
|
||||
depth := 0
|
||||
for i, r := range v {
|
||||
switch {
|
||||
case r == '{' && i > 0 && v[i-1] == '$':
|
||||
depth++
|
||||
case r == '}' && depth > 0:
|
||||
depth--
|
||||
case r == ':' && depth == 0:
|
||||
return v[:i]
|
||||
}
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
// accessMode is the mode an access a container mounts was declared at, by id or by "path:<path>"; "" when the
|
||||
// manifest declares no such access.
|
||||
func accessMode(m Manifest, ref string) string {
|
||||
for _, a := range m.Accesses {
|
||||
if (a.ID != "" && a.ID == ref) || (a.Path != "" && ref == "path:"+filepath.Clean(a.Path)) {
|
||||
return a.At()
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// ADR0325 is how the module check names the decision its identity rules come from.
|
||||
const ADR0325 = "novox/hq ADR 0325"
|
||||
|
||||
// identityProblems is what the module check refuses of a manifest's identities (novox/hq ADR 0325 §1, §2, §3):
|
||||
//
|
||||
// - an `identity` on anything but a container, or one that is neither env:<NAME> for both nor run;
|
||||
// - **in a module that declares `identity` on a container** — it says it runs as its own identity, so it is held
|
||||
// to the decision whole: a directory of it naming an owner (§1, §3), and a container of it that declares none
|
||||
// and mounts one of the module's directories or a read-write access (§2).
|
||||
//
|
||||
// A module that declares no `identity` is warned of the last two (IdentityWarnings), never refused for them yet:
|
||||
// every registered container module mounts its own directories without one, and refusing them would stop the
|
||||
// catalogues composing before they can migrate. **This is the narrowest rule that breaks nothing registered**: no
|
||||
// registered manifest declares `identity`, so no registered module is refused anything new.
|
||||
func identityProblems(m Manifest) []string {
|
||||
var problems []string
|
||||
for _, r := range m.Resources {
|
||||
v, has := r[IdentityField]
|
||||
if !has {
|
||||
continue
|
||||
}
|
||||
if fmt.Sprint(r["type"]) != "container" {
|
||||
problems = append(problems, fmt.Sprintf("%s: %v is a %v and says identity; only a container says how its "+
|
||||
"image is told who to run as (%s §2)", m.Module, r["id"], r["type"], ADR0325))
|
||||
continue
|
||||
}
|
||||
if _, err := ParseIdentity(v); err != nil {
|
||||
problems = append(problems, fmt.Sprintf("%s: the container %v: %v (%s §2)", m.Module, r["id"], err, ADR0325))
|
||||
}
|
||||
}
|
||||
if !DeclaresIdentity(m) {
|
||||
return problems
|
||||
}
|
||||
return append(problems, identityRules(m)...)
|
||||
}
|
||||
|
||||
// IdentityWarnings is what the module check warns of a module that declares no `identity` (novox/hq ADR 0325): each
|
||||
// thing the decision refuses once the module migrates, said now so the catalogues can. Refusing comes when no
|
||||
// registered module still does any of it. Empty for a module that declares `identity`: it is refused these instead.
|
||||
func IdentityWarnings(m Manifest) []string {
|
||||
if DeclaresIdentity(m) {
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for _, p := range identityRules(m) {
|
||||
out = append(out, p+"; accepted while registered modules still do it, refused once they have moved")
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// identityRules is every place a manifest breaks what ADR 0325 §1–§3 refuse: a directory naming an owner, and a
|
||||
// container declaring no identity that mounts the module's own directory or a read-write access.
|
||||
func identityRules(m Manifest) []string {
|
||||
var out []string
|
||||
for _, r := range m.Resources {
|
||||
switch fmt.Sprint(r["type"]) {
|
||||
case "directory":
|
||||
if owner, said := r["owner"]; said {
|
||||
out = append(out, fmt.Sprintf("%s: the directory %v names its owner %v; a directory a module owns is "+
|
||||
"owned by the module's identity, and no manifest names an owner (%s §1, §3)", m.Module, r["id"],
|
||||
owner, ADR0325))
|
||||
}
|
||||
case "container":
|
||||
if _, has := r[IdentityField]; has {
|
||||
continue
|
||||
}
|
||||
dirs, accesses := containerMounts(r)
|
||||
seen := map[string]bool{}
|
||||
for _, d := range dirs {
|
||||
if !seen[d] {
|
||||
seen[d] = true
|
||||
out = append(out, fmt.Sprintf("%s: the container %v declares no identity and mounts the module's "+
|
||||
"own directory %s; only a container that declares identity mounts its module's directories, "+
|
||||
"so what writes them is the module's identity (%s §2)", m.Module, r["id"], d, ADR0325))
|
||||
}
|
||||
}
|
||||
for _, a := range accesses {
|
||||
if accessMode(m, a) == AccessReadWrite && !seen["access:"+a] {
|
||||
seen["access:"+a] = true
|
||||
out = append(out, fmt.Sprintf("%s: the container %v declares no identity and mounts the read-write "+
|
||||
"access %s; a container that runs as its image says is given no entry on a shared folder, so "+
|
||||
"it is refused write (%s §2)", m.Module, r["id"], strings.TrimPrefix(a, "path:"), ADR0325))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// PlacesOwnerProblem refuses an owner a `places` setting names for a module that declares `identity` (novox/hq ADR
|
||||
// 0325 §1, §3): its directories are owned by its identity. Nil for a module that declares none, whose placed owner
|
||||
// is still applied, and warned of by PlacesOwnerWarnings.
|
||||
func PlacesOwnerProblem(m Manifest, layers []Layer) error {
|
||||
if !DeclaresIdentity(m) {
|
||||
return nil
|
||||
}
|
||||
if owned := placedOwners(m, layers); len(owned) > 0 {
|
||||
return fmt.Errorf("%s places %s with an owner, and declares identity: its directories are owned by its "+
|
||||
"identity, and no setting names an owner (%s §1, §3)", m.Module, strings.Join(owned, ", "), ADR0325)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// PlacesOwnerWarnings is a warning for each directory a `places` setting gives an owner, for a module that declares
|
||||
// no `identity` (novox/hq ADR 0325 §1): accepted while registered modules still do it, refused once they have moved.
|
||||
func PlacesOwnerWarnings(m Manifest, layers []Layer) []string {
|
||||
if DeclaresIdentity(m) {
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for _, id := range placedOwners(m, layers) {
|
||||
out = append(out, fmt.Sprintf("warning: %s's setting places.%s.owner names an owner; a directory a module owns "+
|
||||
"is owned by the module's identity, and no setting names an owner (%s §1, §3). Accepted while "+
|
||||
"registered modules still do it, refused once they have moved", m.Module, id, ADR0325))
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func placedOwners(m Manifest, layers []Layer) []string {
|
||||
placed, err := Places(m, layers)
|
||||
if err != nil {
|
||||
// empty-on-error: a placement Places refuses is refused by name where it is judged and composed; it names no owner here
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for id, p := range placed {
|
||||
if p.Owner != "" {
|
||||
out = append(out, id)
|
||||
}
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// resolvedIdentity is a container's `identity` as the node-engine is told it: the mode, the variables an env image
|
||||
// reads, and the module's numbers.
|
||||
func resolvedIdentity(spec IdentitySpec, id ModuleIdentity) map[string]any {
|
||||
out := map[string]any{"mode": spec.Mode, "uid": id.UID, "gid": id.GID}
|
||||
if spec.Mode == IdentityEnv {
|
||||
out["user_env"], out["group_env"] = spec.UserEnv, spec.GroupEnv
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// identityFor is the identity module m runs as here, and whether one is composed: a module that declares `identity`,
|
||||
// to an engine that keeps folders, with an allocation the composition was given. A number outside the range is
|
||||
// refused (§11), never sent.
|
||||
func identityFor(m Manifest, with Rendering) (ModuleIdentity, bool, error) {
|
||||
if !with.KeepsFolders || !DeclaresIdentity(m) {
|
||||
return ModuleIdentity{}, false, nil
|
||||
}
|
||||
id, allocated := with.Identities[m.Module]
|
||||
if !allocated {
|
||||
return ModuleIdentity{}, false, nil
|
||||
}
|
||||
if !AllocatableID(id.UID) || !AllocatableID(id.GID) {
|
||||
return ModuleIdentity{}, false, fmt.Errorf("%s's identity is %d:%d, outside %d–%d: no module identity is root "+
|
||||
"or a root group's, and none is sent (%s §11)", m.Module, id.UID, id.GID, IdentityLow, IdentityHigh, ADR0325)
|
||||
}
|
||||
id.Module = m.Module
|
||||
return id, true, nil
|
||||
}
|
||||
|
||||
// identityInto composes one resource of module m for its identity: a container's `identity` resolved, or taken out
|
||||
// where none is composed; and the owner of a directory one of its identity's containers mounts.
|
||||
func identityInto(resource map[string]any, m Manifest, id ModuleIdentity, has bool, mountedByIdentity map[string]bool) error {
|
||||
switch fmt.Sprint(resource["type"]) {
|
||||
case "container":
|
||||
v, declared := resource[IdentityField]
|
||||
if !declared {
|
||||
return nil
|
||||
}
|
||||
if !has {
|
||||
delete(resource, IdentityField)
|
||||
return nil
|
||||
}
|
||||
spec, err := ParseIdentity(v)
|
||||
if err != nil {
|
||||
return fmt.Errorf("%s: the container %v: %w", m.Module, resource["id"], err)
|
||||
}
|
||||
resource[IdentityField] = resolvedIdentity(spec, id)
|
||||
case "directory":
|
||||
if has && mountedByIdentity[fmt.Sprint(resource["id"])] {
|
||||
resource["owner"] = fmt.Sprintf("%d:%d", id.UID, id.GID)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// dirsMountedByIdentity is the ids of module m's directories one of its containers declaring `identity` mounts.
|
||||
func dirsMountedByIdentity(m Manifest) map[string]bool {
|
||||
out := map[string]bool{}
|
||||
for _, r := range m.Resources {
|
||||
if fmt.Sprint(r["type"]) != "container" {
|
||||
continue
|
||||
}
|
||||
if _, has := r[IdentityField]; !has {
|
||||
continue
|
||||
}
|
||||
dirs, _ := containerMounts(r)
|
||||
for _, d := range dirs {
|
||||
out[d] = true
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// identitiesOf is the declaration's `identities`, by module.
|
||||
func identitiesOf(ids []ModuleIdentity) []map[string]any {
|
||||
sort.Slice(ids, func(i, j int) bool { return ids[i].Module < ids[j].Module })
|
||||
out := make([]map[string]any, 0, len(ids))
|
||||
for _, id := range ids {
|
||||
out = append(out, map[string]any{"module": id.Module, "name": IdentityName(id.Module), "uid": id.UID,
|
||||
"gid": id.GID})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// toolsAccount is the account module m's tools run as on this machine, or empty where they run nowhere as one: no
|
||||
// runtime here, no bundle it loads, or a module left out of an adopted machine's declaration.
|
||||
func (r Resolution) toolsAccount(m Manifest, with Rendering) string {
|
||||
if !r.runtimeHere() || (with.Adopted && m.Filtering != nil) {
|
||||
return ""
|
||||
}
|
||||
loads := false
|
||||
for _, b := range m.Bundles {
|
||||
if len(b.Loads) > 0 {
|
||||
loads = true
|
||||
}
|
||||
}
|
||||
if !loads {
|
||||
return ""
|
||||
}
|
||||
if m.RunsAs != "" {
|
||||
return m.RunsAs
|
||||
}
|
||||
return r.Account
|
||||
}
|
||||
|
||||
// usersInto writes `users` and `taken` on every access of module m among the resources composed so far: its identity
|
||||
// where a container of it that declares `identity` mounts the access's path, and the tool runner's account where the
|
||||
// module's tools run as it and its number is known, each at the access's use (§4: the engine keeps the widest).
|
||||
func usersInto(out []map[string]any, owner map[string]string, m Manifest, id ModuleIdentity, has bool, account string,
|
||||
with Rendering) {
|
||||
var containers []map[string]any
|
||||
for _, res := range out {
|
||||
if res["type"] == "container" && owner[fmt.Sprint(res["id"])] == m.Module {
|
||||
if _, declares := res[IdentityField]; declares && has {
|
||||
containers = append(containers, res)
|
||||
}
|
||||
}
|
||||
}
|
||||
runnerUID, runnerKnown := with.AccountUIDs[account]
|
||||
for _, res := range out {
|
||||
if res["type"] != "access" || owner[fmt.Sprint(res["id"])] != m.Module {
|
||||
continue
|
||||
}
|
||||
path, _ := res["path"].(string)
|
||||
mode, _ := res["mode"].(string)
|
||||
if mode == "" {
|
||||
mode = AccessRead
|
||||
}
|
||||
users := []AccessUser{}
|
||||
for _, c := range containers {
|
||||
if mounts(c, path) {
|
||||
users = append(users, AccessUser{Identity: IdentityName(m.Module), UID: id.UID, Use: mode, From: FromContainer})
|
||||
break // one identity per module, whichever of its containers mounts it
|
||||
}
|
||||
}
|
||||
if account != "" && runnerKnown && runnerUID > 0 {
|
||||
users = append(users, AccessUser{Identity: account, UID: runnerUID, Use: mode, From: FromToolRunner})
|
||||
}
|
||||
if len(users) > 0 {
|
||||
res["users"] = users
|
||||
}
|
||||
res["taken"] = with.KeptFolders[filepath.Clean(path)]
|
||||
}
|
||||
}
|
||||
|
||||
// mounts says whether a composed container mounts path, or something below it, from the machine. A path that merely
|
||||
// begins with the same letters — /storage/media2 beside /storage/media — is another path.
|
||||
func mounts(container map[string]any, path string) bool {
|
||||
volumes, _ := container["volumes"].([]any)
|
||||
path = filepath.Clean(path)
|
||||
for _, v := range volumes {
|
||||
s, ok := v.(string)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
source, _, _ := strings.Cut(s, ":")
|
||||
if !strings.HasPrefix(source, "/") {
|
||||
continue // a named volume: the runtime's, not the operator's path
|
||||
}
|
||||
source = filepath.Clean(source)
|
||||
if source == path || strings.HasPrefix(source, path+"/") {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// AccessPathOn is where access id of module m is on a machine with these settings: its placement, else the
|
||||
// definition's default; false where neither says, or the module declares no such access.
|
||||
func AccessPathOn(m Manifest, layers []Layer, id string) (string, bool) {
|
||||
_, byID, err := accessesFor(m, layers)
|
||||
if err != nil {
|
||||
return "", false
|
||||
}
|
||||
path, has := byID[id]
|
||||
if !has || path == "" {
|
||||
return "", false
|
||||
}
|
||||
return filepath.Clean(path), true
|
||||
}
|
||||
@@ -0,0 +1,339 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/novox/mesh-host/validate"
|
||||
)
|
||||
|
||||
// Defends novox/hq ADR 0325 on the controller's side, row by row of its "How it is checked" table: the module check
|
||||
// (rows 1, 2), the identity composed (row 3), the tool runner's entry (row 4), no identity root (row 11) — and none
|
||||
// of it sent to a node-engine older than the contract, which would refuse the whole declaration.
|
||||
|
||||
const identityImage = "x@sha256:1111111111111111111111111111111111111111111111111111111111111111"
|
||||
|
||||
// aLibrarian files films: a container told its identity by PUID and PGID that mounts its config and the movies it
|
||||
// writes; a sidecar that declares none and reads the music; a directory only its tools write; and tools served by the
|
||||
// machine's runtime.
|
||||
func aLibrarian(t *testing.T) Manifest {
|
||||
t.Helper()
|
||||
m := aToolsModule(t, "librarian", "tools/index.js")
|
||||
m.Accesses = []Access{
|
||||
{ID: "movies", Path: "/storage/media/movies", Mode: AccessReadWrite},
|
||||
{ID: "music", Path: "/storage/media/music", Mode: AccessRead},
|
||||
}
|
||||
m.Resources = []map[string]any{
|
||||
{"id": "config", "type": "directory", "mode": "0750"},
|
||||
{"id": "notes", "type": "directory", "mode": "0700"},
|
||||
{"id": "app", "type": "container", "name": "librarian", "image": identityImage,
|
||||
"identity": map[string]any{"user": "env:PUID", "group": "env:PGID"},
|
||||
"volumes": []any{"${dir:config}:/config", "${access:movies}:/movies"}},
|
||||
{"id": "sidecar", "type": "container", "name": "librarian-sidecar", "image": identityImage,
|
||||
"volumes": []any{"${access:music}:/music:ro"}},
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
// aPlayer reads the movies the librarian writes, as its own identity through the runtime's user option, and has
|
||||
// tools of its own that read them too.
|
||||
func aPlayer(t *testing.T) Manifest {
|
||||
t.Helper()
|
||||
m := aToolsModule(t, "player", "tools/index.js")
|
||||
m.Accesses = []Access{{ID: "movies", Path: "/storage/media/movies", Mode: AccessRead}}
|
||||
m.Resources = []map[string]any{
|
||||
{"id": "app", "type": "container", "name": "player", "image": identityImage,
|
||||
"identity": map[string]any{"user": "run"}, "volumes": []any{"${access:movies}:/movies:ro"}},
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
func keepingFolders(ids map[string]ModuleIdentity, kept ...string) Rendering {
|
||||
with := Rendering{KeepsFolders: true, Identities: ids, KeptFolders: map[string]bool{}}
|
||||
for _, k := range kept {
|
||||
with.KeptFolders[k] = true
|
||||
}
|
||||
return with
|
||||
}
|
||||
|
||||
func composeFolders(t *testing.T, r Resolution, with Rendering) Composed {
|
||||
t.Helper()
|
||||
with.Needed = map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}
|
||||
with.ArtifactStore = "anchor.internal:5101"
|
||||
composed, err := r.Compose(with)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return composed
|
||||
}
|
||||
|
||||
var identities = map[string]ModuleIdentity{"librarian": {UID: 50001, GID: 50001}, "player": {UID: 50002, GID: 50002}}
|
||||
|
||||
// Row 3: the identity composed — the same on every machine, the container told it, the module's directories its
|
||||
// containers mount owned by it, and the declaration's identities naming the account.
|
||||
func TestAModuleRunsAsItsIdentityTheSameOnEveryMachine(t *testing.T) {
|
||||
var seen []string
|
||||
for _, node := range []string{"ace", "novox"} {
|
||||
r := Resolution{Node: node, Account: "jochen", Modules: []Manifest{aLibrarian(t), aPlayer(t), theRuntime(t)}}
|
||||
composed := composeFolders(t, r, keepingFolders(identities))
|
||||
got := byID(composed.Resources)
|
||||
|
||||
app := got["librarian.app"]
|
||||
ident, _ := app[IdentityField].(map[string]any)
|
||||
want := map[string]any{"mode": "env", "user_env": "PUID", "group_env": "PGID", "uid": 50001, "gid": 50001}
|
||||
if fmt.Sprint(ident) != fmt.Sprint(want) {
|
||||
t.Errorf("%s: the container is told %v; want %v", node, ident, want)
|
||||
}
|
||||
player, _ := got["player.app"][IdentityField].(map[string]any)
|
||||
if fmt.Sprint(player) != fmt.Sprint(map[string]any{"mode": "run", "uid": 50002, "gid": 50002}) {
|
||||
t.Errorf("%s: the player is told %v", node, player)
|
||||
}
|
||||
if _, has := got["librarian.sidecar"][IdentityField]; has {
|
||||
t.Errorf("%s: a container declaring no identity was given one", node)
|
||||
}
|
||||
if owner := got["librarian.config"]["owner"]; owner != "50001:50001" {
|
||||
t.Errorf("%s: the directory its identity's container mounts is owned by %v", node, owner)
|
||||
}
|
||||
if owner, has := got["librarian.notes"]["owner"]; has {
|
||||
t.Errorf("%s: a directory no identity container mounts was given the owner %v: what writes it is not "+
|
||||
"the identity", node, owner)
|
||||
}
|
||||
raw, _ := json.Marshal(composed.Identities)
|
||||
seen = append(seen, string(raw))
|
||||
if !strings.Contains(string(raw), `"name":"mesh-librarian"`) || !strings.Contains(string(raw), `"uid":50001`) {
|
||||
t.Errorf("%s: the declaration's identities are %s", node, raw)
|
||||
}
|
||||
}
|
||||
// What the node-engine this controller pins (the ADR 0325 half) makes of it: nothing refused.
|
||||
r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aLibrarian(t), aPlayer(t), theRuntime(t)}}
|
||||
with := keepingFolders(identities, "/storage/media/movies")
|
||||
with.AccountUIDs = map[string]int{"jochen": 1000}
|
||||
composed := composeFolders(t, r, with)
|
||||
body, err := json.Marshal(map[string]any{"declaration": validate.Version, "resources": composed.Resources,
|
||||
"identities": composed.Identities})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if problems := validate.Declaration(body); len(problems) > 0 {
|
||||
t.Fatalf("the pinned node-engine refuses it: %v", problems)
|
||||
}
|
||||
if seen[0] != seen[1] {
|
||||
t.Fatalf("the identities differ between machines: %s and %s", seen[0], seen[1])
|
||||
}
|
||||
}
|
||||
|
||||
// Rows 2, 4 and 8's composed part: each access names its users — the module's identity where a container declaring
|
||||
// identity mounts it, never a container declaring none — and the tool runner's account where its number is known,
|
||||
// each at the access's own use (the node-engine keeps one entry per user at the widest use any access gives it, so
|
||||
// the runner's is the widest among the modules whose tools use the folder); and whether the folder is taken.
|
||||
func TestAnAccessNamesItsUsers(t *testing.T) {
|
||||
r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aLibrarian(t), aPlayer(t), theRuntime(t)}}
|
||||
with := keepingFolders(identities, "/storage/media/movies")
|
||||
with.AccountUIDs = map[string]int{"jochen": 1000}
|
||||
got := byID(composeFolders(t, r, with).Resources)
|
||||
|
||||
users := func(id string) string {
|
||||
raw, _ := json.Marshal(got[id]["users"])
|
||||
return string(raw)
|
||||
}
|
||||
movies := "librarian." + AccessID("/storage/media/movies")
|
||||
if want := `[{"identity":"mesh-librarian","uid":50001,"use":"read-write","from":"container"},` +
|
||||
`{"identity":"jochen","uid":1000,"use":"read-write","from":"tool-runner"}]`; users(movies) != want {
|
||||
t.Errorf("the librarian's movies name %s; want %s", users(movies), want)
|
||||
}
|
||||
played := "player." + AccessID("/storage/media/movies")
|
||||
if want := `[{"identity":"mesh-player","uid":50002,"use":"read","from":"container"},` +
|
||||
`{"identity":"jochen","uid":1000,"use":"read","from":"tool-runner"}]`; users(played) != want {
|
||||
t.Errorf("the player's movies name %s; want %s", users(played), want)
|
||||
}
|
||||
// The sidecar declares no identity: no entry for it (§2); the runner reads the music for the librarian's tools.
|
||||
music := "librarian." + AccessID("/storage/media/music")
|
||||
if want := `[{"identity":"jochen","uid":1000,"use":"read","from":"tool-runner"}]`; users(music) != want {
|
||||
t.Errorf("the music names %s; want only the tool runner's read", users(music))
|
||||
}
|
||||
if got[movies]["taken"] != true || got[music]["taken"] != false {
|
||||
t.Errorf("taken is %v for the movies (taken) and %v for the music (not)", got[movies]["taken"], got[music]["taken"])
|
||||
}
|
||||
|
||||
// The runner's number unknown: no entry for it, never one the engine refuses for uid 0.
|
||||
got = byID(composeFolders(t, r, keepingFolders(identities)).Resources)
|
||||
if want := `[{"identity":"mesh-librarian","uid":50001,"use":"read-write","from":"container"}]`; users(movies) != want {
|
||||
t.Errorf("with no number for the runner's account, the movies name %s; want %s", users(movies), want)
|
||||
}
|
||||
if _, has := got[music]["users"]; has {
|
||||
t.Errorf("an access nobody with a known number uses names users: %s", users(music))
|
||||
}
|
||||
}
|
||||
|
||||
// The contract: to an engine that does not state link.IdentityContract nothing of ADR 0325 is sent — no identities, no
|
||||
// container identity, no users, no taken, no owner from an identity — and what is sent is what the pinned node-engine
|
||||
// accepts, as before.
|
||||
func TestNothingOfTheIdentityIsSentToAnOlderEngine(t *testing.T) {
|
||||
r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aLibrarian(t), aPlayer(t), theRuntime(t)}}
|
||||
composed := composeFolders(t, r, Rendering{Identities: identities})
|
||||
if len(composed.Identities) > 0 {
|
||||
t.Fatalf("identities were composed for an older engine: %v", composed.Identities)
|
||||
}
|
||||
for _, res := range composed.Resources {
|
||||
for _, field := range []string{IdentityField, "users", "taken"} {
|
||||
if _, has := res[field]; has {
|
||||
t.Errorf("%v carries %s for an older engine", res["id"], field)
|
||||
}
|
||||
}
|
||||
if res["id"] == "librarian.config" && res["owner"] != nil {
|
||||
t.Errorf("the directory was given the owner %v for an older engine", res["owner"])
|
||||
}
|
||||
}
|
||||
body, err := json.Marshal(map[string]any{"declaration": validate.Version, "resources": composed.Resources})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if problems := validate.Declaration(body); len(problems) > 0 {
|
||||
t.Fatalf("the pinned node-engine refuses it: %v", problems)
|
||||
}
|
||||
// An engine that keeps folders, with no allocation yet (a question asked before the first send): composed
|
||||
// without an identity, never with a made-up one.
|
||||
none := composeFolders(t, r, keepingFolders(nil))
|
||||
if len(none.Identities) > 0 || byID(none.Resources)["librarian.app"][IdentityField] != nil {
|
||||
t.Fatal("an identity was composed with no allocation")
|
||||
}
|
||||
}
|
||||
|
||||
// Row 11: no identity outside the range is ever sent — 0 above all — and the composition says why.
|
||||
func TestNoModuleIdentityIsRoot(t *testing.T) {
|
||||
for _, n := range []int{0, 4, 10, 1000, IdentityLow - 1, IdentityHigh + 1} {
|
||||
if AllocatableID(n) {
|
||||
t.Errorf("%d is allocatable", n)
|
||||
}
|
||||
r := Resolution{Node: "ace", Account: "jochen", Modules: []Manifest{aLibrarian(t), theRuntime(t)}}
|
||||
with := keepingFolders(map[string]ModuleIdentity{"librarian": {UID: n, GID: n}})
|
||||
with.Needed = map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}
|
||||
with.ArtifactStore = "anchor.internal:5101"
|
||||
if _, err := r.Compose(with); err == nil || !strings.Contains(err.Error(), "§11") {
|
||||
t.Errorf("an identity of %d composed: %v", n, err)
|
||||
}
|
||||
}
|
||||
for _, n := range []int{IdentityLow, IdentityHigh} {
|
||||
if !AllocatableID(n) {
|
||||
t.Errorf("%d is not allocatable", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func manifestJSON(t *testing.T, m map[string]any) []byte {
|
||||
t.Helper()
|
||||
raw, err := json.Marshal(m)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return raw
|
||||
}
|
||||
|
||||
func aContainerModule(name string, resources ...map[string]any) map[string]any {
|
||||
return map[string]any{"module": name, "version": "1", "capabilities": []any{"container-runtime"},
|
||||
"accesses": []any{map[string]any{"id": "movies", "path": "/storage/media/movies", "mode": "read-write"}},
|
||||
"resources": resources}
|
||||
}
|
||||
|
||||
// Rows 1 and 2: the module check accepts identity as env:<NAME> or run and refuses every other shape and an owner in
|
||||
// it; a module that declares identity is refused a directory naming its owner and a container declaring none that
|
||||
// mounts its own directory or a read-write access; a directory's mode is accepted.
|
||||
func TestTheModuleCheckHoldsAnIdentityModuleToTheDecision(t *testing.T) {
|
||||
ok := func(identity any) map[string]any {
|
||||
return map[string]any{"id": "app", "type": "container", "name": "app", "image": identityImage,
|
||||
"identity": identity, "volumes": []any{"${dir:config}:/config", "${access:movies}:/movies"}}
|
||||
}
|
||||
config := map[string]any{"id": "config", "type": "directory", "mode": "0750"}
|
||||
for _, identity := range []any{
|
||||
map[string]any{"user": "env:PUID", "group": "env:PGID"},
|
||||
map[string]any{"user": "run"},
|
||||
} {
|
||||
if _, err := ParseManifest(manifestJSON(t, aContainerModule("app", config, ok(identity)))); err != nil {
|
||||
t.Errorf("identity %v refused: %v", identity, err)
|
||||
}
|
||||
}
|
||||
for _, c := range []struct {
|
||||
identity any
|
||||
want string
|
||||
}{
|
||||
{map[string]any{"user": "1000", "group": "1000"}, `"env:<NAME>" or "run"`},
|
||||
{map[string]any{"user": "env:PUID"}, "told its group the same way"},
|
||||
{map[string]any{"user": "run", "group": "env:PGID"}, "takes no group"},
|
||||
{map[string]any{"user": "env:puid", "group": "env:PGID"}, "environment variable's name"},
|
||||
{map[string]any{"user": "env:PUID", "group": "env:PGID", "owner": "1000:1000"}, "never an owner or a number"},
|
||||
{"run", "identity is"},
|
||||
} {
|
||||
_, err := ParseManifest(manifestJSON(t, aContainerModule("app", config, ok(c.identity))))
|
||||
if err == nil || !strings.Contains(err.Error(), c.want) || !strings.Contains(err.Error(), "ADR 0325") {
|
||||
t.Errorf("identity %v: %v, want it refused saying %q", c.identity, err, c.want)
|
||||
}
|
||||
}
|
||||
// An identity on anything but a container.
|
||||
onAFile := map[string]any{"id": "f", "type": "directory", "mode": "0750", "identity": map[string]any{"user": "run"}}
|
||||
if _, err := ParseManifest(manifestJSON(t, aContainerModule("app", onAFile))); err == nil {
|
||||
t.Error("an identity on a directory was accepted")
|
||||
}
|
||||
|
||||
// Held to the decision whole once it declares identity (§1, §2, §3).
|
||||
owned := map[string]any{"id": "config", "type": "directory", "mode": "0750", "owner": "1000:1000"}
|
||||
bare := map[string]any{"id": "helper", "type": "container", "name": "helper", "image": identityImage,
|
||||
"volumes": []any{"${dir:config}:/config", "${access:movies}:/movies"}}
|
||||
_, err := ParseManifest(manifestJSON(t, aContainerModule("app", owned, ok(map[string]any{"user": "run"}), bare)))
|
||||
for _, want := range []string{"names its owner 1000:1000", "declares no identity and mounts the module's own directory config",
|
||||
"declares no identity and mounts the read-write access movies"} {
|
||||
if err == nil || !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("an identity module: %v, want it refused saying %q", err, want)
|
||||
}
|
||||
}
|
||||
// A setting's owner too.
|
||||
settingOwned := map[string]any{"id": "config", "type": "directory", "mode": "0750", "owner": "${setting:puid}:${setting:pgid}"}
|
||||
identityModule := aContainerModule("app", settingOwned, ok(map[string]any{"user": "run"}))
|
||||
identityModule["settings"] = map[string]any{"puid": map[string]any{"default": "1000"}, "pgid": map[string]any{"default": "1000"}}
|
||||
if _, err := ParseManifest(manifestJSON(t, identityModule)); err == nil || !strings.Contains(err.Error(), "names its owner") {
|
||||
t.Errorf("a setting's owner in an identity module: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// Rows 1 and 2 for what is registered today: a module that declares no identity is warned, never refused — a
|
||||
// directory naming its owner, a container mounting its own directory or a read-write access — and each warning
|
||||
// names ADR 0325. A placement's owner is refused for an identity module and warned of for any other.
|
||||
func TestAModuleWithoutIdentityIsWarnedNotRefused(t *testing.T) {
|
||||
owned := map[string]any{"id": "config", "type": "directory", "mode": "0750", "owner": "1000:1000"}
|
||||
bare := map[string]any{"id": "app", "type": "container", "name": "app", "image": identityImage,
|
||||
"volumes": []any{"${dir:config}:/config", "${access:movies}:/movies"}}
|
||||
m, err := ParseManifest(manifestJSON(t, aContainerModule("legacy", owned, bare)))
|
||||
if err != nil {
|
||||
t.Fatalf("a registered shape was refused: %v", err)
|
||||
}
|
||||
warnings := IdentityWarnings(m)
|
||||
sort.Strings(warnings)
|
||||
if len(warnings) != 3 {
|
||||
t.Fatalf("warned %d times: %q", len(warnings), warnings)
|
||||
}
|
||||
for _, w := range warnings {
|
||||
if !strings.Contains(w, "ADR 0325") || !strings.Contains(w, "refused once they have moved") {
|
||||
t.Errorf("a warning that does not name ADR 0325 or say refusal comes later: %q", w)
|
||||
}
|
||||
}
|
||||
|
||||
placed := []Layer{{From: "ace", Values: map[string]any{PlacesSetting: map[string]any{
|
||||
"config": map[string]any{"path": "/srv/legacy", "owner": "1000:1000"}}}}}
|
||||
if err := PlacesOwnerProblem(m, placed); err != nil {
|
||||
t.Errorf("a placement's owner refused for a module without identity: %v", err)
|
||||
}
|
||||
if w := PlacesOwnerWarnings(m, placed); len(w) != 1 || !strings.Contains(w[0], "places.config.owner") {
|
||||
t.Errorf("a placement's owner warned %q", w)
|
||||
}
|
||||
withIdentity := aLibrarian(t)
|
||||
placedLibrarian := []Layer{{From: "ace", Values: map[string]any{PlacesSetting: map[string]any{
|
||||
"config": map[string]any{"path": "/srv/librarian", "owner": "1000:1000"}}}}}
|
||||
if err := PlacesOwnerProblem(withIdentity, placedLibrarian); err == nil || !strings.Contains(err.Error(), "ADR 0325") {
|
||||
t.Errorf("a placement's owner for an identity module: %v", err)
|
||||
}
|
||||
if len(IdentityWarnings(withIdentity)) != 0 {
|
||||
t.Error("an identity module was warned rather than refused")
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,7 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
@@ -270,6 +271,31 @@ func Places(m Manifest, layers []Layer) (map[string]Placement, error) {
|
||||
// It refuses an id the module declares no access under, and a path that is not absolute. An
|
||||
// access declared by path alone cannot be placed — it has no name to place it by.
|
||||
func AccessPlaces(m Manifest, layers []Layer) (map[string]string, error) {
|
||||
return accessPlaces(m, layers, true)
|
||||
}
|
||||
|
||||
// UndeclaredAccessError is a layer placing an access the definition does not declare (novox/hq issue 575): refused
|
||||
// where a setting is stored, unless a newer build of the module declares it; passed by where a machine is composed.
|
||||
type UndeclaredAccessError struct {
|
||||
Module, ID string
|
||||
said string
|
||||
}
|
||||
|
||||
func (e *UndeclaredAccessError) Error() string { return e.said }
|
||||
|
||||
// UndeclaredAccessPlaces refuses a layer that places an access the definition does not declare.
|
||||
func UndeclaredAccessPlaces(m Manifest, layers []Layer) error {
|
||||
_, err := accessPlaces(m, layers, true)
|
||||
var undeclared *UndeclaredAccessError
|
||||
if errors.As(err, &undeclared) {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// accessPlaces is AccessPlaces; where strict is false an access the definition does not declare is passed by
|
||||
// (novox/hq issue 575), as a placement stored ahead of the build that declares it.
|
||||
func accessPlaces(m Manifest, layers []Layer, strict bool) (map[string]string, error) {
|
||||
declared := map[string]bool{}
|
||||
for _, a := range m.Accesses {
|
||||
if a.ID != "" {
|
||||
@@ -289,9 +315,12 @@ func AccessPlaces(m Manifest, layers []Layer) (map[string]string, error) {
|
||||
}
|
||||
for id, body := range blocks {
|
||||
if !declared[id] {
|
||||
return nil, fmt.Errorf(
|
||||
if !strict {
|
||||
continue
|
||||
}
|
||||
return nil, &UndeclaredAccessError{Module: m.Module, ID: id, said: fmt.Sprintf(
|
||||
"%s places the access %q, which it does not declare — the setting reaches "+
|
||||
"nothing. It declares %s", m.Module, id, orNothing(namesOfAccesses(m)))
|
||||
"nothing. It declares %s", m.Module, id, orNothing(namesOfAccesses(m)))}
|
||||
}
|
||||
path, _ := body.(string)
|
||||
path = strings.TrimSpace(path)
|
||||
@@ -324,7 +353,7 @@ type placedAccess struct {
|
||||
// placed one, the definition's where it carries a default, and refused where neither says — an
|
||||
// access that resolves to nowhere would reach the machine as a mount of nothing.
|
||||
func accessesFor(m Manifest, layers []Layer) ([]placedAccess, map[string]string, error) {
|
||||
placed, err := AccessPlaces(m, layers)
|
||||
placed, err := accessPlaces(m, layers, false)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
|
||||
@@ -509,6 +509,18 @@ var networkName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]*$`)
|
||||
// refused where it is stored (SetSettings, with UnusedSettings) and said where a plan is read,
|
||||
// and never costs a module its place.
|
||||
func JudgeSettings(m Manifest, layers []Layer, adopted bool) error {
|
||||
if err := UndeclaredAccessPlaces(m, layers); err != nil {
|
||||
return err
|
||||
}
|
||||
return ComposesWith(m, layers, adopted)
|
||||
}
|
||||
|
||||
// ComposesWith is JudgeSettings for a layer stored ahead of the definition that reads it (novox/hq issue 575): an
|
||||
// access placed that this definition does not declare yet is not refused, because composition passes it by — it
|
||||
// reaches nothing until the build that declares it registers, and then it places that access. Where a machine is
|
||||
// declared (LeftOutBecause), and where a setting judged against a newer build of the module is held to still compose
|
||||
// with the one registered.
|
||||
func ComposesWith(m Manifest, layers []Layer, adopted bool) error {
|
||||
if err := settingsHoldOneLine(m.Module, layers); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
@@ -958,7 +958,28 @@ func (i *Inventory) judgeSettings(ctx context.Context, nodeName, module string,
|
||||
}
|
||||
layers = append(layers, catalogue.Layer{From: from, Values: values})
|
||||
if err := catalogue.JudgeSettings(m, layers, adopted); err != nil {
|
||||
return fmt.Errorf("refused: %s on %s cannot compose with the layer %q — %w", module, where, from, err)
|
||||
// **A placement for an access the module's newer build brings** (novox/hq issue 575): judged against the
|
||||
// manifest of the module's newest build on the branch it follows, where the registered one does not declare
|
||||
// the access yet — so an access can be placed before or with the delivery that adds it. It must still compose
|
||||
// with the registered manifest, which passes the placement by until the build registers.
|
||||
var undeclared *catalogue.UndeclaredAccessError
|
||||
if !errors.As(err, &undeclared) {
|
||||
return fmt.Errorf("refused: %s on %s cannot compose with the layer %q — %w", module, where, from, err)
|
||||
}
|
||||
ahead, has, aerr := i.NewestManifestOnBranch(ctx, module)
|
||||
if aerr != nil {
|
||||
return aerr
|
||||
}
|
||||
if !has || catalogue.JudgeSettings(ahead, layers, adopted) != nil || catalogue.ComposesWith(m, layers, adopted) != nil {
|
||||
return fmt.Errorf("refused: %s on %s cannot compose with the layer %q — %w; nor does the newest build of "+
|
||||
"%s on the branch it follows declare it", module, where, from, err, module)
|
||||
}
|
||||
m = ahead
|
||||
}
|
||||
// A module that runs as its own identity owns its directories by it: no setting names their owner (novox/hq ADR
|
||||
// 0325 §1, §3). A module that does not yet keeps its placed owner, warned of where it is set.
|
||||
if err := catalogue.PlacesOwnerProblem(m, layers); err != nil {
|
||||
return fmt.Errorf("refused: %w", err)
|
||||
}
|
||||
// And a key that reaches nothing, refused here where somebody can still fix the spelling:
|
||||
// stored, it would be a setting somebody believes they made.
|
||||
@@ -969,6 +990,29 @@ func (i *Inventory) judgeSettings(ctx context.Context, nodeName, module string,
|
||||
return nil
|
||||
}
|
||||
|
||||
// NewestManifestOnBranch is the manifest of a module's newest successful build on the branch its record follows
|
||||
// (novox/hq issue 575): what the delivery under way brings, before it registers — or the registered one's own, when
|
||||
// nothing newer was built. False when no build of the module with a manifest is kept.
|
||||
func (i *Inventory) NewestManifestOnBranch(ctx context.Context, module string) (catalogue.Manifest, bool, error) {
|
||||
var raw []byte
|
||||
err := i.store.Pool().QueryRow(ctx,
|
||||
`select b.manifest from build b join module m on m.name = b.module
|
||||
where b.module = $1 and b.failed = '' and b.manifest is not null and b.manifest::text <> 'null'
|
||||
and (coalesce(m.ref, '') = '' or b.ref = '' or b.ref = m.ref)
|
||||
order by b.at desc limit 1`, module).Scan(&raw)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
return catalogue.Manifest{}, false, nil
|
||||
}
|
||||
if err != nil {
|
||||
return catalogue.Manifest{}, false, err
|
||||
}
|
||||
m, err := catalogue.ParseManifest(raw)
|
||||
if err != nil {
|
||||
return catalogue.Manifest{}, false, nil // a build the mesh cannot read judges nothing
|
||||
}
|
||||
return m, true, nil
|
||||
}
|
||||
|
||||
// givenIn is the machine ports a node-level settings layer gives a module, software port →
|
||||
// machine port (novox/hq ADR 0100). Nothing when the layer gives none; what is not a port is left
|
||||
// for composition to refuse in its own words.
|
||||
|
||||
@@ -38,13 +38,17 @@ type ResourceHealth struct {
|
||||
Waits []Wait `json:"waits,omitempty"`
|
||||
}
|
||||
|
||||
// Wait is one thing a waiting resource waits for the operator to give: exactly one of Secret and Setting
|
||||
// (novox/hq ADR 0283), as link.Wait carries it.
|
||||
// Wait is one thing a waiting resource waits for the operator to give: exactly one of Secret, Setting and Access
|
||||
// (novox/hq ADR 0283, ADR 0325 §7), as link.Wait carries it.
|
||||
type Wait struct {
|
||||
Part string `json:"part"`
|
||||
Secret string `json:"secret,omitempty"`
|
||||
Setting string `json:"setting,omitempty"`
|
||||
What string `json:"what"`
|
||||
// Access is an access of the module by its own id for it, from the engine's access-waits, and Disk that it
|
||||
// waits for the disk that holds its folder rather than for the operator's word (novox/hq ADR 0325 §7, §9).
|
||||
Access string `json:"access,omitempty"`
|
||||
Disk bool `json:"disk,omitempty"`
|
||||
What string `json:"what"`
|
||||
}
|
||||
|
||||
// NodeHealth is a machine's newest statement, as kept.
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
package inventory
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"github.com/jackc/pgx/v5"
|
||||
|
||||
"github.com/novox/mesh-controller/internal/catalogue"
|
||||
)
|
||||
|
||||
// Module identities and taken folders (novox/hq ADR 0325 §3, §8, §11; migration 0096).
|
||||
|
||||
// AllocateIdentity is module's identity, allocated now when it has none: one number from the range of its own,
|
||||
// mesh-wide, kept for ever. Two controllers allocating at once agree: the second's insert finds the first's row.
|
||||
func (i *Inventory) AllocateIdentity(ctx context.Context, module string) (catalogue.ModuleIdentity, error) {
|
||||
if strings.TrimSpace(module) == "" {
|
||||
return catalogue.ModuleIdentity{}, errors.New("an identity is allocated for a module, and none was named")
|
||||
}
|
||||
if id, had, err := i.IdentityOf(ctx, module); err != nil || had {
|
||||
return id, err
|
||||
}
|
||||
// The number is drawn only when the row is new; a draw lost to a concurrent insert is a gap in the range, never
|
||||
// a number given twice.
|
||||
_, err := i.store.Pool().Exec(ctx,
|
||||
`insert into module_identity (module, uid, gid)
|
||||
select $1, n, n from (select nextval('module_identity_number')::integer as n) drawn
|
||||
on conflict (module) do nothing`, module)
|
||||
if err != nil {
|
||||
return catalogue.ModuleIdentity{}, fmt.Errorf("%s could not be given an identity: %w", module, err)
|
||||
}
|
||||
id, had, err := i.IdentityOf(ctx, module)
|
||||
if err == nil && !had {
|
||||
err = fmt.Errorf("%s was given an identity and it cannot be read back", module)
|
||||
}
|
||||
return id, err
|
||||
}
|
||||
|
||||
// IdentityOf is module's identity, and false when it was never allocated one.
|
||||
func (i *Inventory) IdentityOf(ctx context.Context, module string) (catalogue.ModuleIdentity, bool, error) {
|
||||
id := catalogue.ModuleIdentity{Module: module}
|
||||
err := i.store.Pool().QueryRow(ctx, `select uid, gid from module_identity where module = $1`, module).
|
||||
Scan(&id.UID, &id.GID)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
return catalogue.ModuleIdentity{}, false, nil
|
||||
}
|
||||
if err != nil {
|
||||
return catalogue.ModuleIdentity{}, false, err
|
||||
}
|
||||
return id, true, nil
|
||||
}
|
||||
|
||||
// Identities is every module's identity, by module.
|
||||
func (i *Inventory) Identities(ctx context.Context) (map[string]catalogue.ModuleIdentity, error) {
|
||||
rows, err := i.store.Pool().Query(ctx, `select module, uid, gid from module_identity`)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
out := map[string]catalogue.ModuleIdentity{}
|
||||
for rows.Next() {
|
||||
var id catalogue.ModuleIdentity
|
||||
if err := rows.Scan(&id.Module, &id.UID, &id.GID); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out[id.Module] = id
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
// TakenFolder is one folder the operator let the mesh keep on a machine (ADR 0325 §8).
|
||||
type TakenFolder struct {
|
||||
Path string
|
||||
By string
|
||||
Ask string
|
||||
Warrant string
|
||||
Said string
|
||||
}
|
||||
|
||||
// KeptFolders is every folder taken on a machine, by its clean path.
|
||||
func (i *Inventory) KeptFolders(ctx context.Context, nodeName string) (map[string]TakenFolder, error) {
|
||||
rows, err := i.store.Pool().Query(ctx,
|
||||
`select k.path, k.taken_by, k.ask, k.warrant, k.said from kept_folder k join node n on n.id = k.node
|
||||
where n.name = $1`, nodeName)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
out := map[string]TakenFolder{}
|
||||
for rows.Next() {
|
||||
var t TakenFolder
|
||||
if err := rows.Scan(&t.Path, &t.By, &t.Ask, &t.Warrant, &t.Said); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out[t.Path] = t
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
// RecordTaken keeps that a folder was taken on a machine, under the operator's warrant. A take is recorded once:
|
||||
// a second for the same folder keeps the first.
|
||||
func (i *Inventory) RecordTaken(ctx context.Context, nodeName string, t TakenFolder) error {
|
||||
switch {
|
||||
case !strings.HasPrefix(t.Path, "/"):
|
||||
return fmt.Errorf("a taken folder is an absolute path, not %q", t.Path)
|
||||
case strings.TrimSpace(t.Warrant) == "" || strings.TrimSpace(t.Ask) == "":
|
||||
return errors.New("a folder is taken only on the operator's warrant, and this names none")
|
||||
}
|
||||
node, err := i.NodeByName(ctx, nodeName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
_, err = i.store.Pool().Exec(ctx,
|
||||
`insert into kept_folder (node, path, taken_by, ask, warrant, said) values ($1, $2, $3, $4, $5, $6)
|
||||
on conflict (node, path) do nothing`, node.ID, filepath.Clean(t.Path), t.By, t.Ask, t.Warrant, t.Said)
|
||||
return err
|
||||
}
|
||||
@@ -0,0 +1,158 @@
|
||||
package inventory
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/novox/mesh-controller/internal/catalogue"
|
||||
)
|
||||
|
||||
// novox/hq ADR 0325 §3, §11: a module gets one allocation, the same whoever asks and however often, from the range
|
||||
// of its own; no allocation is 0 or a root group's; a number once given is never given again.
|
||||
func TestAModuleIsGivenOneIdentityOnceAndNeverRoot(t *testing.T) {
|
||||
inv := fresh(t)
|
||||
ctx := t.Context()
|
||||
radarr, err := inv.AllocateIdentity(ctx, "radarr")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
again, err := inv.AllocateIdentity(ctx, "radarr")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if radarr != again {
|
||||
t.Fatalf("radarr was given %+v, then %+v: one allocation per module", radarr, again)
|
||||
}
|
||||
plex, err := inv.AllocateIdentity(ctx, "plex")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, id := range []catalogue.ModuleIdentity{radarr, plex} {
|
||||
if id.UID == 0 || id.GID == 0 || !catalogue.AllocatableID(id.UID) || !catalogue.AllocatableID(id.GID) ||
|
||||
id.UID != id.GID {
|
||||
t.Errorf("%s was given %d:%d: within %d–%d, never 0, uid and gid one number", id.Module, id.UID, id.GID,
|
||||
catalogue.IdentityLow, catalogue.IdentityHigh)
|
||||
}
|
||||
}
|
||||
if radarr.UID == plex.UID {
|
||||
t.Fatalf("radarr and plex share %d", plex.UID)
|
||||
}
|
||||
|
||||
// Read back as composition reads it, from another connection's view: the same numbers (stable across restarts
|
||||
// and machines, since every machine's composition reads this one row).
|
||||
all, err := inv.Identities(ctx)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if all["radarr"].UID != radarr.UID || all["plex"].UID != plex.UID {
|
||||
t.Fatalf("the identities read back are %+v", all)
|
||||
}
|
||||
|
||||
// A module forgotten keeps its row, and the next module is given a new number: never one given before.
|
||||
if _, err := inv.store.Pool().Exec(ctx, `delete from module_identity where module = 'plex'`); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
sonarr, err := inv.AllocateIdentity(ctx, "sonarr")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if sonarr.UID == plex.UID || sonarr.UID == radarr.UID {
|
||||
t.Fatalf("sonarr was given %d, a number given before", sonarr.UID)
|
||||
}
|
||||
|
||||
// The store itself refuses a number outside the range, root's above all: no write by hand makes one root.
|
||||
for _, n := range []int{0, 10, 1000, 49999, 60000} {
|
||||
if _, err := inv.store.Pool().Exec(ctx,
|
||||
`insert into module_identity (module, uid, gid) values ($1, $2, $2)`, "byhand", n); err == nil {
|
||||
t.Errorf("the store took %d as an identity", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// novox/hq ADR 0325 §8: a folder taken is recorded once per machine, under a warrant, and read back by its path.
|
||||
func TestAFolderIsTakenOnceUnderAWarrant(t *testing.T) {
|
||||
inv := fresh(t)
|
||||
ctx := t.Context()
|
||||
if _, err := inv.AddNode(ctx, "ace"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := inv.RecordTaken(ctx, "ace", TakenFolder{Path: "/storage/media/movies/", By: "the operator"}); err == nil {
|
||||
t.Fatal("a folder was recorded taken with no warrant")
|
||||
}
|
||||
first := TakenFolder{Path: "/storage/media/movies/", By: "the operator", Ask: "c01", Warrant: "c01", Said: "started"}
|
||||
if err := inv.RecordTaken(ctx, "ace", first); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := inv.RecordTaken(ctx, "ace", TakenFolder{Path: "/storage/media/movies", By: "someone else", Ask: "c02",
|
||||
Warrant: "c02"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
kept, err := inv.KeptFolders(ctx, "ace")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got, has := kept["/storage/media/movies"]
|
||||
if !has || got.Ask != "c01" || got.By != "the operator" {
|
||||
t.Fatalf("the taken folder reads %+v (%v): the first take, by its clean path", got, has)
|
||||
}
|
||||
}
|
||||
|
||||
// novox/hq issue 575: a module registered without the access movies, whose newest build on its branch declares it —
|
||||
// the build the delivery under way brings — takes a proposal placing movies: judged against that build, not refused.
|
||||
// Without such a build it is refused, as before.
|
||||
func TestAPlacementIsJudgedAgainstTheBuildThatBringsTheAccess(t *testing.T) {
|
||||
inv := fresh(t)
|
||||
ctx := t.Context()
|
||||
if _, err := inv.AddNode(ctx, "ace"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
registered := catalogue.Manifest{Module: "media-importer", Version: "1",
|
||||
Accesses: []catalogue.Access{{ID: "downloads", Path: "/services/media/downloads", Mode: catalogue.AccessReadWrite}},
|
||||
Resources: []map[string]any{{"id": "server", "type": "container", "name": "importer", "image": "x",
|
||||
"volumes": []any{"${access:downloads}:/downloads"}}}}
|
||||
if err := inv.RegisterModule(ctx, registered, Source{Repository: "https://forge.invalid/media.git",
|
||||
Ref: "main", BuiltFrom: "c0ffee33"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
placing := map[string]any{catalogue.AccessesSetting: map[string]any{"movies": "/storage/media/movies"}}
|
||||
|
||||
err := inv.JudgeSettings(ctx, "ace", "media-importer", placing)
|
||||
if err == nil || !strings.Contains(err.Error(), `places the access "movies", which it does not declare`) {
|
||||
t.Fatalf("a placement no build declares: %v", err)
|
||||
}
|
||||
|
||||
// main's manifest — the build of #34 — declares movies.
|
||||
ahead := registered
|
||||
ahead.Accesses = append([]catalogue.Access{}, registered.Accesses...)
|
||||
ahead.Accesses = append(ahead.Accesses, catalogue.Access{ID: "movies", Path: "/services/media/movies",
|
||||
Mode: catalogue.AccessReadWrite})
|
||||
raw, err := json.Marshal(ahead)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
b := aBuild("b34", "media-importer", "")
|
||||
b.Ref, b.Manifest = "main", raw
|
||||
if err := inv.RecordBuild(ctx, b); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := inv.JudgeSettings(ctx, "ace", "media-importer", placing); err != nil {
|
||||
t.Fatalf("the proposal placing movies, which main's build declares, was refused: %v", err)
|
||||
}
|
||||
if err := inv.SetSettings(ctx, "ace", "media-importer", placing); err != nil {
|
||||
t.Fatalf("the layer placing movies was not stored: %v", err)
|
||||
}
|
||||
// Stored ahead, it does not cost the registered module its place: composition passes it by.
|
||||
layers, err := inv.SettingsFor(ctx, "ace", "media-importer")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := catalogue.ComposesWith(registered, layers, false); err != nil {
|
||||
t.Fatalf("the registered module no longer composes with the layer stored ahead: %v", err)
|
||||
}
|
||||
// A typo is still a typo: an access neither build declares is refused.
|
||||
typo := map[string]any{catalogue.AccessesSetting: map[string]any{"moveis": "/storage/media/movies"}}
|
||||
if err := inv.JudgeSettings(ctx, "ace", "media-importer", typo); err == nil {
|
||||
t.Fatal("a placement no build declares was taken")
|
||||
}
|
||||
}
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
-- Every module is given an identity of its own, and the mesh takes a shared folder once, on the operator's word
|
||||
-- (novox/hq ADR 0325 §3, §8, §11).
|
||||
--
|
||||
-- **One number per module, mesh-wide, allocated once and never again.** The node-engine makes the account
|
||||
-- mesh-<module> on each machine the module is assigned to, with these numbers, so a container that declares
|
||||
-- `identity` runs as the same uid and gid everywhere and a folder's entries mean the same on every machine. The
|
||||
-- numbers come from a sequence of their own, 50000–59999 (catalogue.IdentityLow and IdentityHigh): above the
|
||||
-- numbers distributions give people, below the 60000s Debian keeps for its daemons, and nowhere near root's 0 or a
|
||||
-- root group's (0, 4, 10). The checks refuse a row outside the range, so no write, by hand or by a later bug, can make
|
||||
-- an identity root (§11). uid and gid are one number. A sequence never hands a number back, and a row is kept after
|
||||
-- its module is forgotten, so a number once given is never given to another module: a file left owned by a removed
|
||||
-- module's identity is never inherited by a new one.
|
||||
create sequence module_identity_number as integer minvalue 50000 maxvalue 59999 start 50000 no cycle;
|
||||
|
||||
create table module_identity (
|
||||
module text primary key,
|
||||
uid integer not null unique check (uid between 50000 and 59999),
|
||||
gid integer not null unique check (gid between 50000 and 59999),
|
||||
allocated timestamptz not null default now(),
|
||||
check (uid = gid)
|
||||
);
|
||||
|
||||
-- **A folder taken, per machine** (§8). The first time a placed folder that already holds data is to be kept, the
|
||||
-- operator is asked once for that folder on that machine; on the warrant the node-engine adds the entries to
|
||||
-- everything there, and the folder is taken: kept from then on without asking, a module that gains the access
|
||||
-- added with no wait. The row is the record of that act — who approved it, under which warrant — and what tells a
|
||||
-- later module's access that it joins a taken folder (`taken` on the access). The path is the folder as placed,
|
||||
-- clean and absolute.
|
||||
create table kept_folder (
|
||||
node uuid not null references node (id) on delete cascade,
|
||||
path text not null check (path like '/%'),
|
||||
taken_at timestamptz not null default now(),
|
||||
-- Who approved it, as the hand-act log says it, and the ask and warrant it was taken under.
|
||||
taken_by text not null,
|
||||
ask text not null,
|
||||
warrant text not null,
|
||||
-- What the node-engine answered when it started the take.
|
||||
said text not null default '',
|
||||
primary key (node, path)
|
||||
);
|
||||
@@ -8,6 +8,7 @@ package link
|
||||
|
||||
import (
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"github.com/novox/mesh-host/rootsearch"
|
||||
"strconv"
|
||||
"strings"
|
||||
@@ -436,6 +437,14 @@ const ReadinessContract = 2
|
||||
// parses strictly and would refuse the whole declaration for it.
|
||||
const RootContract = 3
|
||||
|
||||
// IdentityContract is the statement of an engine that gives each module its identity and keeps shared folders
|
||||
// (novox/hq ADR 0325; mesh-host internal/link IdentityContract): it reads a declaration's `identities`, a container's
|
||||
// resolved `identity`, an access's `users` and `taken`, states an access it may not keep yet as waiting
|
||||
// (ResourceHealth.AccessWaits), and hears the take act (AskAccessAct). Only to such an engine is any of it sent: an
|
||||
// older one parses strictly and would refuse the whole declaration for it. Four, the grant's number (ADR 0312,
|
||||
// superseded), is what engines stated before; the controller sends no grant to any engine (#270).
|
||||
const IdentityContract = 5
|
||||
|
||||
// ReasonRoot starts the reason of an account verdict that found a way to root (ADR 0266); the node-engine's
|
||||
// own words (mesh-host internal/accounts ReasonRoot).
|
||||
const ReasonRoot = "can become root without a person"
|
||||
@@ -580,6 +589,36 @@ type Wait struct {
|
||||
What string `json:"what"`
|
||||
}
|
||||
|
||||
// WaitKindAccess is the kind of a wait on an access (novox/hq ADR 0325 §7; mesh-host internal/link).
|
||||
const WaitKindAccess = "access"
|
||||
|
||||
// AccessWait is one access waiting for the operator (novox/hq ADR 0325 §7): the access by its module's own id for
|
||||
// it, the part (its module), and what the operator gives, in words with no path — "let the mesh keep the shared
|
||||
// folder movies", or "mount the disk that holds books". Beside Waits because mesh-sdk's health.Wait names a secret or
|
||||
// a setting and nothing else. From an engine at IdentityContract or later.
|
||||
type AccessWait struct {
|
||||
Kind string `json:"kind"`
|
||||
Access string `json:"access"`
|
||||
Part string `json:"part"`
|
||||
What string `json:"what"`
|
||||
}
|
||||
|
||||
// WaitsForDisk says an access wait is for a disk that is not there (ADR 0325 §9) rather than for the operator's word
|
||||
// to keep a folder: read from the engine's words, the one thing its wait says of which it is.
|
||||
func (w AccessWait) WaitsForDisk() bool {
|
||||
return strings.HasPrefix(strings.TrimSpace(w.What), "mount the disk")
|
||||
}
|
||||
|
||||
// KeptEntry is one user of a kept folder as the engine's listing says it (ADR 0325 §4), with a note beside the tool
|
||||
// runner's entry.
|
||||
type KeptEntry struct {
|
||||
Identity string `json:"identity"`
|
||||
UID int `json:"uid"`
|
||||
Use string `json:"use"`
|
||||
From string `json:"from"`
|
||||
Note string `json:"note,omitempty"`
|
||||
}
|
||||
|
||||
// ResourceHealth is one long-running resource's state.
|
||||
type ResourceHealth struct {
|
||||
Module string `json:"module"`
|
||||
@@ -606,6 +645,11 @@ type ResourceHealth struct {
|
||||
// Waits is what a resource in StateWaiting waits for (novox/hq ADR 0283). Empty otherwise, and from an
|
||||
// engine older than that.
|
||||
Waits []Wait `json:"waits,omitempty"`
|
||||
// AccessWaits is what an access stated waiting waits for (novox/hq ADR 0325 §7); Act the last walk under its
|
||||
// folder, kept as the engine said it; Entries the kept folder's listing. From an engine at IdentityContract only.
|
||||
AccessWaits []AccessWait `json:"access-waits,omitempty"`
|
||||
Act json.RawMessage `json:"act,omitempty"`
|
||||
Entries []KeptEntry `json:"entries,omitempty"`
|
||||
}
|
||||
|
||||
// HealthSaid is the health event's body: the machine and its statement. The machine is read from the
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
package link
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/rand"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/nats-io/nats.go"
|
||||
|
||||
"github.com/novox/mesh-controller/internal/broker"
|
||||
)
|
||||
|
||||
// The take act: a shared folder that already holds data is taken by the mesh once, on the operator's word
|
||||
// (novox/hq ADR 0325 §8).
|
||||
//
|
||||
// The controller asks the operator once for that folder on that machine (ADR 0259, at the level approve). On the
|
||||
// warrant it asks the machine's node-engine, on the engine's own subject (broker.AskAccessActSubject), signed with
|
||||
// the mesh's key as a hand-over is (SignedHandOver) under a signing context of its own (AccessActContext), to take
|
||||
// the folder: the engine adds the entries of the users it was declared for that folder to everything under it —
|
||||
// following no link, entering no other filesystem — answers at once that it started or why it refused, and states
|
||||
// the walk on the access's verdict. **Nothing is taken without a warrant**: the ask names the warrant the operator
|
||||
// gave, and the controller sends it only from the warrant (cmd/mesh-controller decideTake).
|
||||
//
|
||||
// The engine's own shape (mesh-host internal/link AccessActAsk, AnswerAccessAct): a hand-over's fields and
|
||||
// {act: "take", access: <the access's resource id in the declaration>, warrant}.
|
||||
|
||||
// AccessActContext is prefixed to an act ask's bytes before signing: never another ask's signature, nor a
|
||||
// declaration's. The engine holds the same words.
|
||||
const AccessActContext = "novox-mesh access-act v2\n"
|
||||
|
||||
// ActTake is the one act the controller asks.
|
||||
const ActTake = "take"
|
||||
|
||||
// AccessActAsk is what the controller asks: a hand-over's fields — the node it is for, the folder's absolute path as
|
||||
// the declaration places it, who asked, when the ask stops being good and a nonce the engine takes once — and the
|
||||
// act's own: which act, the access by its resource id, and the warrant the operator gave.
|
||||
type AccessActAsk struct {
|
||||
Node string `json:"node"`
|
||||
Path string `json:"path"`
|
||||
By string `json:"by"`
|
||||
Expires time.Time `json:"expires"`
|
||||
Nonce string `json:"nonce"`
|
||||
Act string `json:"act"`
|
||||
Access string `json:"access"`
|
||||
Warrant string `json:"warrant"`
|
||||
}
|
||||
|
||||
// MaxActField bounds an access id and a warrant, as the engine does.
|
||||
const MaxActField = 200
|
||||
|
||||
// TakeWithin is how long the controller waits for the engine's answer: it starts the walk and answers, and the
|
||||
// walk's end is stated on the access's verdict.
|
||||
const TakeWithin = 30 * time.Second
|
||||
|
||||
// SignTake fills a take ask's act, expiry and nonce and signs it with the mesh's key over AccessActContext. It refuses
|
||||
// an ask with no warrant, no path or no access — and one the engine would refuse for its shape: nothing is ever asked
|
||||
// of an engine that it would have to refuse.
|
||||
func SignTake(ctx context.Context, signer Signer, ask AccessActAsk) ([]byte, error) {
|
||||
ask.Access, ask.Warrant = strings.TrimSpace(ask.Access), strings.TrimSpace(ask.Warrant)
|
||||
switch {
|
||||
case signer == nil:
|
||||
return nil, errors.New("no signing key, so nothing can be asked of an engine")
|
||||
case ask.Warrant == "":
|
||||
return nil, errors.New("a take is asked only on the operator's warrant, and this one names none")
|
||||
case ask.Node == "" || !strings.HasPrefix(ask.Path, "/"):
|
||||
return nil, errors.New("a take names its machine and the folder's absolute path")
|
||||
case ask.Access == "":
|
||||
return nil, errors.New("a take names the access whose folder it takes")
|
||||
}
|
||||
// The warrant is one short name; the access is the resource id the declaration gave it, which may hold a path's
|
||||
// slashes (catalogue.AccessID) — the engine judges it against what it was declared.
|
||||
if len(ask.Warrant) > MaxActField || strings.ContainsAny(ask.Warrant, "\r\n\x00/") {
|
||||
return nil, fmt.Errorf("the take's warrant %q is not one short name", ask.Warrant)
|
||||
}
|
||||
if len(ask.Access) > MaxActField || strings.ContainsAny(ask.Access, "\r\n\x00") {
|
||||
return nil, fmt.Errorf("the take's access %q is not one line", ask.Access)
|
||||
}
|
||||
nonce := make([]byte, 16)
|
||||
if _, err := rand.Read(nonce); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
ask.Act, ask.Nonce, ask.Expires = ActTake, hex.EncodeToString(nonce), time.Now().UTC().Add(HandOverGood)
|
||||
raw, err := json.Marshal(ask)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
signature, err := signer.Sign(ctx, append([]byte(AccessActContext), raw...))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("cannot sign the ask: %w", err)
|
||||
}
|
||||
return json.Marshal(SignedHandOver{Ask: raw, Signature: signature})
|
||||
}
|
||||
|
||||
// AskTake asks one machine's node-engine to take a shared folder on the operator's warrant, and reads its answer. An
|
||||
// error is the ask not reaching an engine, or an answer that is not one; a refusal is the engine's and comes back in
|
||||
// the answer.
|
||||
func AskTake(ctx context.Context, conn *nats.Conn, signer Signer, ask AccessActAsk, timeout time.Duration) (HandOverAnswer, error) {
|
||||
if conn == nil {
|
||||
return HandOverAnswer{}, errors.New("this controller is not on the bus")
|
||||
}
|
||||
body, err := SignTake(ctx, signer, ask)
|
||||
if err != nil {
|
||||
return HandOverAnswer{}, err
|
||||
}
|
||||
return askSigned(ctx, conn, broker.AskAccessActSubject(ask.Node), body, ask.Node, timeout, askWords{
|
||||
what: "the take of a shared folder", nothing: "nothing was taken", issue: "ADR 0325",
|
||||
unknown: "whether it started is not known — the access's verdict on the machine says whether it is kept",
|
||||
record: "a start"})
|
||||
}
|
||||
Reference in New Issue
Block a user