diff --git a/internal/catalogue/a_service_process_test.go b/internal/catalogue/a_service_process_test.go new file mode 100644 index 0000000..1e25276 --- /dev/null +++ b/internal/catalogue/a_service_process_test.go @@ -0,0 +1,166 @@ +package catalogue + +import ( + "encoding/json" + "strings" + "testing" +) + +// novox/hq issue 213 (ADR 0188 §1, §3): a module's own Go service is a bundle the host runs as a +// process, not an image. Each test holds one thing that had to change in the composer for the +// controller to be declared that way. + +const aServiceDigest = "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd" + +// aServiceModule is the controller's shape in miniature: it answers tools of its own, its code is a +// Go bundle a process runs as an account it declares, its secrets belong to that account, it +// prepares its state, and its process replaces the container it used to run as. +func aServiceModule(t *testing.T) Manifest { + t.Helper() + raw := `{ + "module": "svc", "version": "1", "tools": ["status"], "prepares": true, + "own-secrets": {"store": "${dir:state}/store"}, + "secrets-owner": "svc", + "resources": [ + {"id": "state", "type": "directory", "mode": "0700", "place": "mesh", "owner": "svc"}, + {"id": "service", "type": "process", "name": "svc", "artifact": "code", + "run": ["./svc", "serve"], "user": "svc", "replaces": ["server"], + "env": {"SVC_STORE_FILE": "${dir:state}/store", "SVC_STORE_PORT": "${seat:mesh-store:5432}"}}, + {"id": "account", "type": "user", "name": "svc", "shell": "/usr/bin/nologin", "home": "/var/lib/svc"} + ], + "build": {"artifacts": [{"name": "code", "kind": "bundle", "language": "go", "system": "arch", + "from": "cmd/svc", "binary": "svc"}]} + }` + m, err := ParseManifest([]byte(raw)) + if err != nil { + t.Fatalf("the service's manifest is refused: %v", err) + } + resolved, err := m.Resolve([]Built{{Name: "code", Kind: ArtifactBundle, + Reference: ArtifactStoreScheme + "svc/code@" + aServiceDigest, Digest: aServiceDigest}}) + if err != nil { + t.Fatal(err) + } + return resolved +} + +func composeTheService(t *testing.T, with Rendering) []map[string]any { + t.Helper() + with.Needed = map[string]map[string]string{"svc": {"store": "sealed-store"}} + with.ArtifactStore = "anchor.internal:5100" + out, err := Resolution{Node: "anchor", Modules: []Manifest{aServiceModule(t)}}.Declaration(with) + if err != nil { + t.Fatalf("the service does not compose: %v", err) + } + return out +} + +func indexOf(out []map[string]any, id string) int { + for i, r := range out { + if r["id"] == id { + return i + } + } + return -1 +} + +// A module that declares tools has every bundle served by the node's runtime unless it says +// otherwise — and the controller declares the verbs it answers as tools. Its service bundle is run +// by its own process; launched a second time by the runtime it would be a second controller +// pretending to be an MCP server. +func TestABundleItsOwnProcessRunsIsNotServedByTheRuntime(t *testing.T) { + m := aServiceModule(t) + if len(m.Bundles) != 1 { + t.Fatalf("the service's bundle was not kept: %+v", m.Bundles) + } + if loads := m.Bundles[0].Loads; len(loads) != 0 { + t.Fatalf("the runtime would launch the service's own bundle as tools: %v", loads) + } + // And a bundle no resource runs still is served, as a module declaring tools always had it. + tools := Manifest{Module: "t", Version: "1", Tools: []string{"x"}, + Build: &Build{Artifacts: []Artifact{{Name: "tools", Kind: ArtifactBundle, Language: "go", + System: "arch", From: "cmd/t"}}}} + resolved, err := tools.Resolve([]Built{{Name: "tools", Kind: ArtifactBundle, + Reference: ArtifactStoreScheme + "t/tools@" + aServiceDigest, Digest: aServiceDigest}}) + if err != nil { + t.Fatal(err) + } + if loads := resolved.Bundles[0].Loads; len(loads) != 1 || loads[0] != "t" { + t.Fatalf("a tools bundle nothing runs is no longer served: %v", loads) + } +} + +// The account is created before anything is given to it. Its secrets are mesh-computed and so +// placed before the module's own resources; given to a user the machine did not have yet, they were +// refused on the first apply and the process started without them. +func TestAModulesAccountComesBeforeWhatBelongsToIt(t *testing.T) { + out := composeTheService(t, Rendering{}) + account, secret := indexOf(out, "svc.account"), indexOf(out, "svc."+NeedID("store")) + if account < 0 || secret < 0 { + t.Fatalf("the account or the secret is missing: %v", out) + } + if account > secret { + t.Fatalf("the secret owned by svc is written before svc exists: account at %d, secret at %d", + account, secret) + } + if owner := out[secret]["owner"]; owner != "svc" { + t.Errorf("the secret belongs to %v, not the account its process runs as", owner) + } +} + +// The process is the module's program; its preparation is the same program asked to prepare, as a +// step before it — with the same account and environment, and handing nothing over. +func TestAProcessIsPreparedByItsOwnProgram(t *testing.T) { + out := composeTheService(t, Rendering{}) + step, process := indexOf(out, "svc.service-prepare"), indexOf(out, "svc.service") + if step < 0 || process < 0 || step > process { + t.Fatalf("the preparation is not a step before the process (%d, %d): %v", step, process, out) + } + s := out[step] + if s["type"] != "process" || s["run-once"] != true || s["name"] != "svc-prepare" { + t.Errorf("the preparation is not a run-once process: %v", s) + } + if run, _ := json.Marshal(s["run"]); string(run) != `["./svc","prepare"]` { + t.Errorf("the preparation runs %s", run) + } + if s["user"] != "svc" || s["source"] != out[process]["source"] { + t.Errorf("the preparation does not run the same bundle as the same account: %v", s) + } + if env, _ := s["env"].(map[string]any); env["SVC_STORE_FILE"] == nil { + t.Errorf("the preparation is not given the process's environment: %v", s["env"]) + } + if _, has := s["replaces"]; has { + t.Errorf("the preparation would hand over what the process replaces: %v", s) + } + if _, has := s["args"]; has { + t.Errorf("the preparation carries a container's args: %v", s) + } +} + +// What the process replaces is named as the host recorded it, `.`; unprefixed, the host +// matches nothing and removes the container first, as before. +func TestWhatAProcessReplacesIsNamedAsTheHostRecordedIt(t *testing.T) { + out := composeTheService(t, Rendering{}) + p := out[indexOf(out, "svc.service")] + if got, _ := json.Marshal(p["replaces"]); string(got) != `["svc.server"]` { + t.Fatalf("the process replaces %s", got) + } +} + +func TestWhatReplacesMayNameIsRefusedNearItsAuthor(t *testing.T) { + for what, resource := range map[string]string{ + "a container": `{"id":"c","type":"container","name":"c","image":"x@` + aServiceDigest + `","replaces":["old"]}`, + "a step": `{"id":"p","type":"process","name":"p","run":["./p"],"run-once":true,"replaces":["old"]}`, + "something declared": `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["p"]}`, + "another module's": `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["other.old"]}`, + "not a list": `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":"old"}`, + } { + raw := `{"module":"m","version":"1","resources":[` + resource + `]}` + if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), "replace") { + t.Errorf("replaces on %s was accepted: %v", what, err) + } + } + ok := `{"module":"m","version":"1","resources":[{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["old"]}]}` + if _, err := ParseManifest([]byte(ok)); err != nil { + t.Errorf("a process replacing what its module no longer declares was refused: %v", err) + } +} diff --git a/internal/catalogue/build.go b/internal/catalogue/build.go index 4db55a1..7a97b3f 100644 --- a/internal/catalogue/build.go +++ b/internal/catalogue/build.go @@ -77,6 +77,7 @@ func (m Manifest) Resolve(built []Built) (Manifest, error) { // build compare equal. out.Bundles = nil if m.Build != nil { + run := runByAResource(m) for _, a := range m.Build.Artifacts { if a.Kind != ArtifactBundle { continue @@ -84,8 +85,13 @@ func (m Manifest) Resolve(built []Built) (Manifest, error) { made := by[a.Name] // What the runtime loads: what the artifact said, else every entrypoint of a module // that declares tools, else nothing (the field's own rule; see Artifact.Loads). + // + // **Never, unasked, a bundle one of the module's own resources runs** (novox/hq issue 213). + // A process the host runs is the module's service, not its tools: the controller declares + // the verbs it answers as `tools` and serves them itself, and its bundle would otherwise + // have been launched a second time by the node's runtime, as an MCP child it is not. loads := append([]string(nil), a.Loads...) - if a.Loads == nil && len(m.Tools) > 0 { + if a.Loads == nil && len(m.Tools) > 0 && !run[a.Name] { loads = append([]string(nil), a.Entrypoints...) // A bundle compiled to a binary has no entrypoints: the binary is what it is, and what // the runtime starts to serve it (novox/hq ADR 0193). So a Go tools bundle is served @@ -453,6 +459,18 @@ func BinaryOf(a Artifact) string { return a.Name } +// runByAResource is the artifacts one of a module's own resources names — a process that runs it, +// a step, an archive that unpacks it — by name. +func runByAResource(m Manifest) map[string]bool { + named := map[string]bool{} + for _, r := range m.Resources { + if a, ok := r["artifact"].(string); ok && a != "" { + named[a] = true + } + } + return named +} + // undeliveredBundles says which of a module's bundles nothing would ever put on a machine (novox/hq // 04-ISSUES/216). A bundle reaches a machine three ways: the node's runtime serves it (it says // `loads`, or its module declares `tools`), a resource names it (a process, a step, an archive), or @@ -463,12 +481,7 @@ func undeliveredBundles(m Manifest) []string { if m.Build == nil || m.Module == RuntimeModule { return nil } - named := map[string]bool{} - for _, r := range m.Resources { - if a, ok := r["artifact"].(string); ok && a != "" { - named[a] = true - } - } + named := runByAResource(m) var problems []string for _, a := range m.Build.Artifacts { if a.Kind != ArtifactBundle || named[a.Name] || len(a.Loads) > 0 || len(m.Tools) > 0 { diff --git a/internal/catalogue/declaration.go b/internal/catalogue/declaration.go index dbd83f6..d69eb7a 100644 --- a/internal/catalogue/declaration.go +++ b/internal/catalogue/declaration.go @@ -693,7 +693,15 @@ func (r Resolution) compose(with Rendering, owner map[string]string, // Now, and not before: a module whose resources are computed replaces them wholesale, and // merging earlier would throw away the files it still needs. - resources = append(append([]map[string]any{}, first...), resources...) + // + // **Except the module's own accounts, which go before even those** (novox/hq issue 213). What + // the mesh computes may belong to one: a module whose code runs as an account it declares has + // its secrets written owned by that account, and a file given to a user the machine does not + // have yet fails — so on the first apply the secrets were refused, the process started without + // them, and the second apply healed it, which is the fault the paragraph above describes. + // An account depends on nothing the mesh computes. + accounts, rest := accountsFirst(resources) + resources = append(append(accounts, first...), rest...) // No container is given the mesh's names (novox/hq ADR 0148). It used to be: every // container got the whole roster as `--add-host` entries at creation, and a name that @@ -872,6 +880,12 @@ func (r Resolution) compose(with Rendering, owner map[string]string, if renamed := reflectsRenamed(m.Module, resource["reload-on"]); renamed != nil { copied["reload-on"] = renamed } + // And what a process replaces (novox/hq issue 213): a resource of this module's that it + // no longer declares, named as the host recorded it, or the host hands nothing over and + // removes it first. + if renamed := reflectsRenamed(m.Module, resource["replaces"]); renamed != nil { + copied["replaces"] = renamed + } // **What reads one of this module's own secrets is restarted when it changes** (novox/hq // issue 203, issue 206). A credential is re-issued by the mesh, and a container that // mounted the old file keeps the old one open: the build machine ran for an hour on a @@ -2010,12 +2024,18 @@ func preparationTarget(m Manifest) string { return "" } for _, r := range m.Resources { - if fmt.Sprint(r["type"]) != "container" || !ownArtifact(r, m.Module) { + // A container, or a process the host runs from a bundle the module built (novox/hq issue + // 213): the same program in the same context, hosted as a unit rather than a container. + kind := fmt.Sprint(r["type"]) + if (kind != "container" && kind != "process") || !ownArtifact(r, m.Module) { continue } if once, _ := r["run-once"].(bool); once { continue } + if r["schedule"] != nil { + continue + } return fmt.Sprint(r["id"]) } return "" @@ -2029,7 +2049,10 @@ func ownArtifact(resource map[string]any, module string) bool { return true } image, _ := resource["image"].(string) - return strings.HasPrefix(image, ArtifactStoreScheme+module+"/") + // A process or an archive carries what was built as its source (novox/hq issue 213). + source, _ := resource["source"].(string) + return strings.HasPrefix(image, ArtifactStoreScheme+module+"/") || + strings.HasPrefix(source, ArtifactStoreScheme+module+"/") } // prepared is the module's own resource as the step that prepares its state: the same image, the same @@ -2051,7 +2074,19 @@ func prepared(from map[string]any) map[string]any { step["id"] = fmt.Sprint(from["id"]) + "-prepare" step["name"] = fmt.Sprint(from["name"]) + "-prepare" step["run-once"] = true - step["args"] = []any{PreparationArgument} + if fmt.Sprint(from["type"]) == "process" { + // A process says its whole command: the program, then its arguments. The step is the same + // program asked to prepare (novox/hq issue 213). It replaces nothing — what the process + // replaces is handed over to the process, never to the step that runs before it — and a + // step is not restarted, it runs again when what it reads changed, which `restart-on` says. + run := stringsIn(from["run"]) + if len(run) > 0 { + step["run"] = []any{run[0], PreparationArgument} + } + delete(step, "replaces") + } else { + step["args"] = []any{PreparationArgument} + } delete(step, "ports") delete(step, "ip") delete(step, "schedule") @@ -2196,3 +2231,16 @@ func withRestartOn(have any, add []string) []any { } return out } + +// accountsFirst splits a module's resources into its accounts and everything else, each in the order +// written. +func accountsFirst(resources []map[string]any) (accounts, rest []map[string]any) { + for _, r := range resources { + if fmt.Sprint(r["type"]) == "user" { + accounts = append(accounts, r) + continue + } + rest = append(rest, r) + } + return accounts, rest +} diff --git a/internal/catalogue/manifest.go b/internal/catalogue/manifest.go index 4c55564..8528c9f 100644 --- a/internal/catalogue/manifest.go +++ b/internal/catalogue/manifest.go @@ -1515,6 +1515,53 @@ func ParseManifest(raw []byte) (Manifest, error) { "program that reads what the mesh delivered and reconciles", m.Module, r["id"])) } + // **What a process replaces is something the module no longer declares** (novox/hq issue 213). + // The host keeps it running until the process is, then removes it: so it is named by the id the + // module used to give it, it is never a resource the module still declares — that would be + // applied and removed by one declaration — and only a process that stays up has anything to + // hand over to. Said here, near the author, as the host would refuse it far away. + ids := map[string]bool{} + for _, r := range m.Resources { + ids[fmt.Sprint(r["id"])] = true + } + for _, r := range m.Resources { + raw, present := r["replaces"] + if !present { + continue + } + if fmt.Sprint(r["type"]) != "process" { + problems = append(problems, fmt.Sprintf( + "%s: %v says what it replaces, and only a process does", m.Module, r["id"])) + continue + } + if once, _ := r["run-once"].(bool); once || r["schedule"] != nil { + problems = append(problems, fmt.Sprintf( + "%s: %v replaces something and runs once or on a schedule — only a process that stays "+ + "up is there a moment later to hand over to", m.Module, r["id"])) + } + list, ok := raw.([]any) + if !ok { + problems = append(problems, fmt.Sprintf( + "%s: %v replaces %v; replaces is a list of the ids this module no longer declares", + m.Module, r["id"], raw)) + continue + } + for _, item := range list { + id, ok := item.(string) + switch { + case !ok || strings.TrimSpace(id) == "": + problems = append(problems, fmt.Sprintf( + "%s: %v replaces %v, which is not an id", m.Module, r["id"], item)) + case strings.Contains(id, "."): + problems = append(problems, fmt.Sprintf( + "%s: %v replaces %q; a process replaces only a resource of its own module, named "+ + "by its own id", m.Module, r["id"], id)) + case ids[id]: + problems = append(problems, fmt.Sprintf( + "%s: %v replaces %q, which this module still declares", m.Module, r["id"], id)) + } + } + } // **A module that prepares its state must have code the mesh can run** (novox/hq ADR 0135). The // preparation is the module's own program in its preparation mode, so it is derived from the // resource that runs that program — and a module declaring none has asked for something the mesh @@ -1522,7 +1569,7 @@ func ParseManifest(raw []byte) (Manifest, error) { // quietly prepares nothing. if m.Prepares && preparationTarget(m) == "" { problems = append(problems, fmt.Sprintf( - "%s says it prepares its state, and declares no container running an artifact it built — "+ + "%s says it prepares its state, and declares no container or process running an artifact it built — "+ "the preparation is this module's own program, so there has to be one for the mesh to "+ "run it in", m.Module)) }