Feature 57 (config and provisioning): modules declare config and provisions, their files rendered from templates; synced with main (issues of feature 57, 874)

2026-10-16 07:37:43 +00:00
parent 1a2c917abf
commit 9652b2d5ce
771 changed files with 52063 additions and 1774 deletions
@@ -20,7 +20,7 @@ WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /mesh-route-proxy ./examples/route-proxy
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -buildvcs=false -ldflags=-buildid= -o /mesh-route-proxy ./examples/route-proxy

 # A small runtime with the public CA roots the ACME client needs to reach a real authority, and run
 # as root so it can bind :80 and :443 — the two privileged ports a public front door listens on.
@@ -84,3 +84,10 @@ traffic.
 | `ACME_CACHE` | `/acme` | where issued certificates persist; required when `TLS_LISTEN` is set, so a restart does not re-order |
 | `ACME_DIRECTORY` | Let's Encrypt **staging** in the binary; production in the module's `acme.env` | the issuer |
 | `ACME_CA_BUNDLE` | *(unset)* | a file of roots to trust for the issuer's own API — set only for a private/lab authority whose API certificate the world does not yet trust |
+
+## Answered by the provider helper (issue 792)
+
+A small Go program beside the proxy (`cmd/route-provider`) runs the SDK's provider helper for `route`, with no credential,
+and the offer says `"answered-by": "helper"`: a handed consumer (gitea's origins file) is filled by its machine's client
+from this module's entry, which carries the public names the controller composed for it. The module is **not** marked
+moved: its own files, `acme.env` and the broker secret, are composed as before, and the proxy itself is unchanged.
@@ -0,0 +1,37 @@
+// route-provider: route-proxy's Go half, one binary the node's runtime launches and speaks MCP to over stdio
+// through the Go SDK. It serves no tools; it runs the SDK's provider helper that answers the consumers of `route`
+// (issue 792). The TypeScript adapter beside it keeps writing the proxy's files.
+//
+// stdout is the MCP channel; everything this module says, it says on stderr.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/provider"
+)
+
+func say(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "[route-proxy] "+format+"\n", args...)
+}
+
+func main() {
+	node := os.Getenv("MESH_NODE")
+	if node == "" {
+		say("MESH_NODE is not set; answering no consumers")
+	} else {
+		p := newProvider(node, provider.StateBus(ModuleName), say)
+		go func() {
+			if err := p.Run(context.Background()); err != nil {
+				say("the provider helper stopped: %v", err)
+			}
+		}()
+	}
+	if err := stdio.Serve("", nil); err != nil {
+		say("%v", err)
+		os.Exit(1)
+	}
+}
@@ -0,0 +1,36 @@
+package main
+
+// route-proxy handed to the provisioner (novox/hq ADR 0349 clause 12, issue 792): the module runs the SDK's provider
+// helper for `route`, so a consumer of a route — a handed gitea reading `${bound:route:name-web}` — is told its public
+// name from the entry in this module's bucket, the one its machine's client fills its files from.
+//
+// **It composes nothing.** A route's public name is the label its consumer chose joined to the node's public domain,
+// which only the controller knows (the domain is placement), so the controller composes it and carries it in the
+// consumer's plan entry (`names`); the helper copies it into the entry's values unchanged. There is no credential for
+// a route and nothing to make: the traefik files stay the TypeScript adapter's, written from the contributions the
+// mesh still gives it.
+
+import (
+	"git.novox.be/novox/mesh-sdk/go/provider"
+)
+
+// ProvisionName is what route-proxy provides, as its manifest says.
+const ProvisionName = "route"
+
+// ModuleName is this module.
+const ModuleName = "route-proxy"
+
+// newProvider is route-proxy answering its consumers over bus on node: the route, served as the manifest serves it
+// (nothing of its own), with no credential, and nothing to make or retire for a consumer.
+func newProvider(node string, bus provider.Bus, logf func(string, ...any)) *provider.Provider {
+	return provider.New(provider.Options{
+		Node:   node,
+		Module: ModuleName,
+		Offers: map[string]provider.Offer{ProvisionName: {
+			Credential: provider.NoCredential,
+			Serves:     map[string]any{},
+		}},
+		Bus:  bus,
+		Logf: logf,
+	})
+}
@@ -0,0 +1,108 @@
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"sync"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/provider"
+)
+
+// bucketBus is the helper's bus over in-memory buckets.
+type bucketBus struct {
+	mu      sync.Mutex
+	buckets map[string]map[string][]byte
+}
+
+func (b *bucketBus) Watch(_ context.Context, bucket string, handle func(string, []byte)) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for k, v := range b.buckets[bucket] {
+		handle(k, v)
+	}
+	return nil
+}
+
+func (b *bucketBus) Put(_ context.Context, bucket, key string, value []byte) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if b.buckets[bucket] == nil {
+		b.buckets[bucket] = map[string][]byte{}
+	}
+	b.buckets[bucket][key] = append([]byte(nil), value...)
+	return nil
+}
+
+func (b *bucketBus) Delete(_ context.Context, bucket, key string) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	delete(b.buckets[bucket], key)
+	return nil
+}
+
+// A consumer of a route is answered with the names its plan's entry carries, and nothing of a credential (issue 792):
+// the entry's values are the controller's composition, copied unchanged, and no vault is asked.
+func TestAConsumerOfARouteIsToldItsNamesFromItsPlanEntry(t *testing.T) {
+	bus := &bucketBus{buckets: map[string]map[string][]byte{}}
+	plan, _ := json.Marshal(map[string]any{"node": "g14", "module": "gitea", "provisioning": map[string]any{
+		"provisions": []any{map[string]any{"provision": ProvisionName, "provider": "novox",
+			"provider-module": ModuleName, "at": "10.7.0.1", "from": "novox", "as": "mesh_g14_gitea",
+			"names": map[string]any{"name": "git.example.org", "internal-name": "git.novox.internal",
+				"name-web": "git.example.org"}}}}})
+	if err := bus.Put(context.Background(), provider.AssignmentsBucket, "g14.gitea", plan); err != nil {
+		t.Fatal(err)
+	}
+	p := newProvider("novox", bus, t.Logf)
+	out, err := p.Pass(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(out) != 1 || out[0].Status != provider.Answered {
+		t.Fatalf("the pass did %+v", out)
+	}
+	var e provider.Entry
+	if err := json.Unmarshal(bus.buckets[provider.BucketOf(ModuleName)]["g14.gitea.route"], &e); err != nil {
+		t.Fatal(err)
+	}
+	if e.Values["name-web"] != "git.example.org" || e.Values["name"] != "git.example.org" ||
+		e.Values["internal-name"] != "git.novox.internal" || e.Credential != "" || e.User != "" || e.Refused != "" {
+		t.Fatalf("the entry is %+v", e)
+	}
+}
+
+// route-proxy's own files and resources stay as they were (issue 792): the module answers its route through the
+// helper but is not marked moved, so its acme.env, its broker secret and its containers are composed as today and
+// the public ingress does not change. Everything of the manifest but its build, what it provides and the state it
+// keeps is pinned by this digest; changing the ingress means changing it here, on purpose.
+func TestRouteProxyIsNotMovedAndKeepsItsOwnFiles(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if _, moved := m["moved"]; moved {
+		t.Fatal("route-proxy is marked moved: its own files would be handed")
+	}
+	provides, _ := m["provides"].([]any)
+	if len(provides) != 1 || provides[0].(map[string]any)["answered-by"] != "helper" {
+		t.Fatalf("route is not said to be answered by the helper: %v", provides)
+	}
+	for _, k := range []string{"build", "provides", "state", "reads"} {
+		delete(m, k)
+	}
+	pinned, err := json.Marshal(m) // sorted keys, compact
+	if err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(pinned)
+	if got := hex.EncodeToString(sum[:]); got != "57a39de0943d8b33b9db6cb998ce97f8793602cca6cdfa5849c1c392390454a3" {
+		t.Fatalf("route-proxy's own manifest changed: digest %s", got)
+	}
+}
@@ -0,0 +1,3 @@
+ACME_DIRECTORY=https://acme-v02.api.letsencrypt.org:443/directory
+ACME_ROOTS=https://acme-v02.api.letsencrypt.org:443
+ACME_ROOTS_PATH=
@@ -0,0 +1,3 @@
+INTERNAL_ACME_DIRECTORY=https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:path}
+INTERNAL_ACME_ROOTS=https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}
+INTERNAL_ACME_ROOTS_PATH=${bound:internal-acme-ca:roots}
@@ -0,0 +1,5 @@
+module route-proxy
+
+go 1.25.0
+
+require git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261015210729-d3e182503c19
@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261015210729-d3e182503c19 h1:mAMt3KFmrHzDiBv4MLL94opWcG9y73ISMrBUyisapQE=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261015210729-d3e182503c19/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
@@ -9,7 +9,8 @@
    {
      "name": "route",
      "scope": "mesh",
-      "identity": false
+      "identity": false,
+      "answered-by": "helper"
    }
  ],
  "serves": {
@@ -95,14 +96,14 @@
      "type": "file",
      "path": "${dir:state}/acme.env",
      "mode": "0600",
-      "content": "ACME_DIRECTORY=https://acme-v02.api.letsencrypt.org:443/directory\nACME_ROOTS=https://acme-v02.api.letsencrypt.org:443\nACME_ROOTS_PATH=\n"
+      "template": "files/acme.env"
    },
    {
      "id": "internal-acme-env",
      "type": "file",
      "path": "${dir:state}/internal-acme.env",
      "mode": "0600",
-      "content": "INTERNAL_ACME_DIRECTORY=https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:path}\nINTERNAL_ACME_ROOTS=https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}\nINTERNAL_ACME_ROOTS_PATH=${bound:internal-acme-ca:roots}\n"
+      "template": "files/internal-acme.env"
    },
    {
      "id": "trust",
@@ -207,6 +208,22 @@
        "name": "trust",
        "kind": "upstream",
        "from": "alpine@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b"
+      },
+      {
+        "name": "provider",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/route-provider",
+        "binary": "route-provider",
+        "loads": [
+          "route-provider"
+        ]
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
      }
    ],
    "on": [
@@ -226,5 +243,11 @@
      "failregex": "^.*TLS handshake error from <HOST>:\\d+: (?:no public route for|acme/autocert: missing server name)\n            ^.*refused: no route for .*, asked from <HOST>:\\d+$",
      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=route-proxy\nport = http,https\nmaxretry = 10\nfindtime = 1d\nbantime = 1d"
    }
+  ],
+  "state": [
+    "bound"
+  ],
+  "reads": [
+    "mesh-controller.assignments"
  ]
 }