From 36e78f5ff0adaf5718fe47598b0bc700fcae6933 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 17 Nov 2026 23:42:11 +0100 Subject: [PATCH] nodeengineclient: a composition names the digests of the templates archives it was rendered from (A-481, A-481a) Builds: design 47 G A-481, A-481a --- go/clients/nodeengineclient/composed.go | 18 +++++++++++++++--- go/clients/nodeengineclient/composed_test.go | 3 +++ go/seats/nodeengine/contract.go | 4 +++- seats/node-engine/seat.json | 7 +++++++ ts/seats/nodeengine/index.d.ts | 2 ++ 5 files changed, 30 insertions(+), 4 deletions(-) diff --git a/go/clients/nodeengineclient/composed.go b/go/clients/nodeengineclient/composed.go index aded503..88f5891 100644 --- a/go/clients/nodeengineclient/composed.go +++ b/go/clients/nodeengineclient/composed.go @@ -49,6 +49,9 @@ type Composition struct { Own seat.NodeOwn Plan json.RawMessage Refused string + // Templates are the digests ("sha256:"), sorted, of the templates archives the module's files were rendered from + // (design 47 G A-481, A-481a); part of the digest as the resources are. + Templates []string } type adoptionWire struct { @@ -139,6 +142,7 @@ type composedWire struct { Own *ownWire `json:"own,omitempty"` Plan json.RawMessage `json:"plan,omitempty"` Refused string `json:"refused,omitempty"` + Templates []string `json:"templates,omitempty"` // Signature is read and dropped: a composition is unsigned (ADR 0593 ยง6), and a value the ended controller signed // still decodes. Nothing writes it. Signature json.RawMessage `json:"signature,omitempty"` @@ -183,9 +187,17 @@ func (c Composition) check() error { return fmt.Errorf("node-engine: the composition of %s carries the node's own parts, which only .node carries", c.Module) } } - if c.Refused != "" && (len(c.Resources) > 0 || len(c.Filled) > 0 || c.Data || len(c.Plan) > 0) { + if c.Refused != "" && (len(c.Resources) > 0 || len(c.Filled) > 0 || c.Data || len(c.Plan) > 0 || len(c.Templates) > 0) { return fmt.Errorf("node-engine: the composition of %s on %s is refused and holds resources, filled files, data or a plan", c.Module, c.Node) } + for i, d := range c.Templates { + if hex, ok := strings.CutPrefix(d, "sha256:"); !ok || !keys.IsHex64(hex) { + return fmt.Errorf("node-engine: the templates digest %q of %s is not sha256: and 64 lowercase hex digits", d, c.Module) + } + if i > 0 && c.Templates[i-1] >= d { + return fmt.Errorf("node-engine: the templates digests of %s are not sorted and distinct", c.Module) + } + } seen := map[string]bool{} files := map[string][]*declaration.File{} for _, raw := range c.Resources { @@ -245,7 +257,7 @@ func (c Composition) wire() (composedWire, error) { return composedWire{}, err } w := composedWire{V: keys.Version, Node: c.Node, Module: c.Module, FP: c.FP, Data: c.Data, Filled: c.Filled, - Refused: c.Refused, Resources: make([]json.RawMessage, len(c.Resources))} + Refused: c.Refused, Templates: c.Templates, Resources: make([]json.RawMessage, len(c.Resources))} for i, r := range c.Resources { canon, err := canonicalJSON(r) if err != nil { @@ -290,7 +302,7 @@ func DecodeComposition(data []byte) (Composition, error) { return Composition{}, fmt.Errorf("node-engine: a composition does not fit its shape: %w", err) } c := Composition{V: w.V, Node: w.Node, Module: w.Module, FP: w.FP, Data: w.Data, Resources: w.Resources, - Filled: w.Filled, Plan: w.Plan, Refused: w.Refused} + Filled: w.Filled, Plan: w.Plan, Refused: w.Refused, Templates: w.Templates} if w.Own != nil { c.Own = ownFromWire(*w.Own) } diff --git a/go/clients/nodeengineclient/composed_test.go b/go/clients/nodeengineclient/composed_test.go index 0fe22fa..73a1248 100644 --- a/go/clients/nodeengineclient/composed_test.go +++ b/go/clients/nodeengineclient/composed_test.go @@ -60,6 +60,7 @@ func TestCompositionDigests(t *testing.T) { {"one package", Composition{Node: "ace", Module: "buildah", FP: fp(7), Resources: by["buildah"]}, "sha256:84e480a7a62333960b3e4be21a7548bbaa09572ef73ca8fb9dc6dfd1228aeb6b"}, {"a service and a file", Composition{Node: "ace", Module: "mesh-wireguard", FP: fp(14), Resources: by["mesh-wireguard"]}, "sha256:d6edec2474f606503e55d4ee2e0b4f5d1ffc25d016e4bc595e86ea67fe205b8c"}, {"a plan beside the resources", Composition{Node: "ace", Module: "hostname", FP: fp(8), Resources: by["hostname"], Plan: json.RawMessage(`{"files":[{"path":"/etc/hostname"}]}`)}, "sha256:49e17d6c471ee65cdef745ca3ac5cea4d37b6a100e11d8434dc64a6e2949e57e"}, + {"the templates archives it was rendered from", Composition{Node: "ace", Module: "hostname", FP: fp(8), Resources: by["hostname"], Templates: []string{"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}, "sha256:342df17a2e81fc08911452ecf1f37c6267aa58b66b26109b8e10253196248364"}, } for _, c := range cases { got, err := ComposedDigest(c.c) @@ -107,6 +108,8 @@ func TestCompositionRefusals(t *testing.T) { {"a resource of another module", Composition{Node: "ace", Module: "hostname", FP: fp(8), Resources: ok.Resources}, "is of"}, {"the node's own parts on a module", Composition{Node: "ace", Module: "buildah", FP: fp(7), Own: seat.NodeOwn{ProvisionerAccount: "x"}}, "node's own parts"}, {"a refusal that holds resources", Composition{Node: "ace", Module: "buildah", FP: fp(7), Resources: ok.Resources, Refused: "no secret"}, "refused and holds"}, + {"templates digests not sorted", Composition{Node: "ace", Module: "hostname", FP: fp(8), Resources: by["hostname"], Templates: []string{"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}, "not sorted"}, + {"a templates digest of no form", Composition{Node: "ace", Module: "hostname", FP: fp(8), Resources: by["hostname"], Templates: []string{"abc"}}, "templates digest"}, {"the node's own with a fingerprint", Composition{Node: "ace", FP: fp(7)}, "names no fingerprint"}, {"a node name with a dot", Composition{Node: "a.ce"}, "node"}, } diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 4f86ef3..4bd7cdd 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -1649,7 +1649,9 @@ type ComposedByNodeModuleFingerprintValue struct { Refused string `json:"refused,omitempty"` // the declaration resources, each saying its module Resources []map[string]any `json:"resources"` - V int64 `json:"v"` + // the digests, sorted, of the templates archives the composition was rendered from + Templates []string `json:"templates,omitempty"` + V int64 `json:"v"` } // ComposedByNodeNodeValue is one value of the state composed under the key .node. diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 9ba2124..748fbd0 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -1310,6 +1310,13 @@ "refused": { "type": "string", "description": "why the module cannot be composed at this fingerprint" + }, + "templates": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the digests, sorted, of the templates archives the composition was rendered from" } }, "required": [ diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index a9710f1..3c87dec 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -1237,6 +1237,8 @@ export interface ComposedByNodeModuleFingerprintValue { "refused"?: string; /** the declaration resources, each saying its module */ "resources": Record[]; + /** the digests, sorted, of the templates archives the composition was rendered from */ + "templates"?: string[]; "v": number; } -- 2.54.0