Where the answer to a requirement is allowed to live

Two different things were both written `requires`. A shell, a display
server and a private network have to be on the machine that needs them.
A database does not — it runs somewhere and is reached over the network.
Both were answered the same way, so requiring a database installed
PostgreSQL on every machine that ran a web application.

What a module provides now carries a scope, the same idea claims already
use, written short in the ordinary case:

  "provides": ["shell"]
  "provides": [{"name": "database", "scope": "mesh"}]

A mesh-scoped requirement is answered by finding the node already running
it — never by installing it here. Choosing a machine to put a database on
is a decision with consequences, and nothing resolving a web application
should make it silently. With nothing anywhere it refuses and says which
module to assign; with two it refuses and says how to choose.

Choosing is `pin <node> <provision> <from>`, kept per node because that
is the granularity the choice has. A pin at a machine that does not
provide it refuses rather than falling back — a fallback would quietly
move somebody's data. One provider does not overrule a pin either.

Resolving a node now needs to know what the others offer, and working
that out needs them resolved, so it is two passes: the first answers only
what each node offers, the second answers everything. Nothing is ever
declared from the first.

A node's plan says what it takes from elsewhere. It is the only part of a
set that stops working when a different machine goes away, and nothing
else in that output would have said so. It is also where a credential
will hang once there is a mechanism for handing one back.

One test found passing for the wrong reason: it read pins through a join
on the provider, which hides a dangling row whether or not it was cleaned
up. It counts rows now, and bites when the cascade is removed.

internal/catalogue/contributes_test.go

@@ -23,7 +23,7 @@ func published(module, host string, port int) Manifest {
 
 func proxy() Manifest {
 	return Manifest{Module: "traefik", Version: "1",
-		Provides: []string{"reverse-proxy"},
+		Provides: Offers("reverse-proxy"),
 		Receives: map[string]string{"reverse-proxy": "/etc/traefik/mesh.json"},
 		Resources: []map[string]any{
 			{"id": "up", "type": "service", "unit": "traefik", "state": "running",
@@ -58,8 +58,8 @@ func received(t *testing.T, out []map[string]any) []Contribution {
 func TestTheFileTheProviderGetsIsMachineReadable(t *testing.T) {
 	// It is written for a program, and the first version put a `//` header above the JSON — a
 	// file that says "do not edit" to a person and fails to parse for the thing meant to read it.
-	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	for _, r := range mustDeclare(t, got) {
 		if r["path"] != "/etc/traefik/mesh.json" {
 			continue
@@ -79,8 +79,8 @@ func TestTheFileTheProviderGetsIsMachineReadable(t *testing.T) {
 }
 
 func TestAModuleTellsItsProviderWhatItNeeds(t *testing.T) {
-	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -100,8 +100,8 @@ func TestAModuleTellsItsProviderWhatItNeeds(t *testing.T) {
 func TestContributingToSomethingIsRequiringIt(t *testing.T) {
 	// Asking to be published means a publisher must exist. A module that had to say both would
 	// eventually say one, and the failure would be a machine where nothing serves the route.
-	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -111,8 +111,8 @@ func TestContributingToSomethingIsRequiringIt(t *testing.T) {
 }
 
 func TestNothingToContributeToIsRefused(t *testing.T) {
-	_, err := Resolve(shelf(published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	_, err := Resolve(shelf(published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	if err == nil {
 		t.Fatal("a module was published through a proxy that does not exist")
 	}
@@ -125,7 +125,8 @@ func TestEveryPublisherOnTheMachineIsInOneFile(t *testing.T) {
 	got, err := Resolve(shelf(proxy(),
 		published("board", "board", 8080),
 		published("archive", "archive", 9000),
-	), []string{"board", "archive"}, workstation(), nil)
+	), []string{"board", "archive"}, workstation(), World{})
+
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -144,7 +145,7 @@ func TestAProviderWithNoConsumersStillGetsTheFile(t *testing.T) {
 	// Empty rather than absent. A provider that finds no file cannot tell "nothing asked for me"
 	// from "the mesh never wrote it", and those want completely different responses — the same
 	// rule the host follows about a service that does not exist.
-	got, err := Resolve(shelf(proxy()), []string{"traefik"}, workstation(), nil)
+	got, err := Resolve(shelf(proxy()), []string{"traefik"}, workstation(), World{})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -157,8 +158,8 @@ func TestTheProviderCanReloadWhenTheRoutesChange(t *testing.T) {
 	// A proxy that got a new route and did not reload is a route that silently does not work.
 	// The same fault the private network had when a peer list changed under a running interface,
 	// which is why the received file has a name a module can point at.
-	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	out := mustDeclare(t, got)
 	for _, r := range out {
 		if r["type"] != "service" {
@@ -179,8 +180,8 @@ func TestTheProviderCanReloadWhenTheRoutesChange(t *testing.T) {
 func TestARouteCanBeSetPerMesh(t *testing.T) {
 	// The hostname is exactly the kind of thing that differs between one mesh and the next. A
 	// module whose route could not be set would have to be edited to be reused anywhere.
-	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)),
-		[]string{"board"}, workstation(), nil)
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
 	out, err := got.Declaration(Rendering{Settings: SettingsBy{
 		"board": {{From: "the mesh", Values: map[string]any{"host": "dashboard"}}},
 	}})