A board that reads through the same interfaces and holds nothing
novox/hq 03-DESIGN/01-to-be/11-a-board.md, built. The board being replaced is one service reading every context's database directly — ADR 0008 violated by the one component with a reason to violate it. The cost is not hypothetical: a boundary nothing may cross can move, and one thing crossing it is enough to freeze it. A board that reads the provisioning tables breaks when provisioning changes them, and the change then gets weighed against the board. So the three questions are read once, by one function, for all three ways of saying them — a person's status, its JSON, and this page. Three implementations of "which machine is not doing what it was told" would be three chances to disagree. Refused and failed stay distinct all the way to the page: refused means the machine is exactly as it was and what is wrong is in what was sent; failed means it is in a state nobody declared. Different places to fix, so one word for both would send half the readers to the wrong one. It stores nothing, changes nothing, and every action it might offer already exists as a command. A board that cannot reach the mesh says so rather than rendering an empty page — an empty page says "nothing is wrong" in the one situation where nobody can know that. One test earns its place twice: a machine's own words are the whole reason the page is useful and the one thing on it nobody in this repository wrote, so they are shown and are not markup.
This commit is contained in:
@@ -0,0 +1,248 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"net/http"
|
||||
"time"
|
||||
)
|
||||
|
||||
// boardCommand serves the three questions as a page.
|
||||
//
|
||||
// **It reads through the same functions everything else does and holds nothing**
|
||||
// (novox/hq 03-DESIGN/01-to-be/11-a-board.md). The board being replaced is one service that reads
|
||||
// every context's database directly — [ADR 0008](novox/hq) violated by the one component with a
|
||||
// reason to violate it, and the cost is that a boundary nothing may cross can move, while one
|
||||
// thing crossing it is enough to freeze it. A board that reads the provisioning tables is a board
|
||||
// that breaks when provisioning changes its tables, and the change then gets weighed against the
|
||||
// board.
|
||||
//
|
||||
// **It stores nothing of its own.** No cache that can disagree, no table of what the mesh looked
|
||||
// like last time. Every request reads the mesh now; if that is slow, the answer belongs in the
|
||||
// context that owns it, where everything else asking gets it too.
|
||||
//
|
||||
// **Reading is the whole of it.** Every action a board could offer already exists as a command,
|
||||
// and a button that does something no command does is a second implementation of a decision.
|
||||
func boardCommand(ctx context.Context, args []string) error {
|
||||
set := flag.NewFlagSet("board", flag.ContinueOnError)
|
||||
// The private network, not everything. A board says which machines are broken and what they
|
||||
// are running, which is exactly the map somebody attacking this would like — and there is no
|
||||
// reason for it to be reachable from further away than the mesh.
|
||||
listen := set.String("listen", "127.0.0.1:8080", "where to serve it")
|
||||
if _, err := parseAround(set, args); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
server := &http.Server{
|
||||
Addr: *listen,
|
||||
ReadHeaderTimeout: 10 * time.Second,
|
||||
Handler: board(),
|
||||
}
|
||||
fmt.Printf("the board is on http://%s\n", *listen)
|
||||
fmt.Printf(" it reads the mesh on every request and keeps nothing\n")
|
||||
|
||||
go func() {
|
||||
<-ctx.Done()
|
||||
closing, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
_ = server.Shutdown(closing)
|
||||
}()
|
||||
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// board is the handler, separate so a test can drive it without a listener.
|
||||
func board() http.Handler {
|
||||
mux := http.NewServeMux()
|
||||
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path != "/" {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
asked, err := ask(r.Context())
|
||||
if err != nil {
|
||||
// **Said, not blank.** A board that cannot reach the mesh and renders an empty page
|
||||
// says "nothing is wrong" in the one situation where nobody can know that.
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
w.WriteHeader(http.StatusServiceUnavailable)
|
||||
_ = page.Execute(w, view{Unreachable: err.Error()})
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
if err := page.Execute(w, asked); err != nil {
|
||||
// The page is half-written by now; there is nothing useful left to say to the
|
||||
// browser, and saying it here is what stops the failure being silent.
|
||||
fmt.Printf("the board could not render: %v\n", err)
|
||||
}
|
||||
})
|
||||
// The same answers for something that is not a person, from the same read. A board and a
|
||||
// script disagreeing about which machine is broken would be worse than either alone.
|
||||
mux.HandleFunc("/mesh.json", func(w http.ResponseWriter, r *http.Request) {
|
||||
inv, err := openInventory(r.Context())
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusServiceUnavailable)
|
||||
return
|
||||
}
|
||||
defer inv.Close()
|
||||
asked, err := theThreeQuestions(r.Context(), inv)
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusServiceUnavailable)
|
||||
return
|
||||
}
|
||||
body, err := statusAsJSON(asked.wrong, asked.nodes, asked.quiet, asked.behind, asked.sources)
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write(append(body, '\n'))
|
||||
})
|
||||
return mux
|
||||
}
|
||||
|
||||
// ask reads the mesh for one request.
|
||||
func ask(ctx context.Context) (view, error) {
|
||||
inv, err := openInventory(ctx)
|
||||
if err != nil {
|
||||
return view{}, err
|
||||
}
|
||||
defer inv.Close()
|
||||
|
||||
asked, err := theThreeQuestions(ctx, inv)
|
||||
if err != nil {
|
||||
return view{}, err
|
||||
}
|
||||
return viewOf(asked), nil
|
||||
}
|
||||
|
||||
// view is what the page is given. Nothing is derived here that the reader could not derive.
|
||||
type view struct {
|
||||
Unreachable string
|
||||
Machines int
|
||||
Broken []brokenMachine
|
||||
Quiet []quietMachine
|
||||
Behind []staleModule
|
||||
At string
|
||||
}
|
||||
|
||||
type brokenMachine struct {
|
||||
Node string
|
||||
// Outcome is refused or failed, and stays distinct all the way to the page. **Refused means
|
||||
// the machine is exactly as it was and what is wrong is in what was sent; failed means it is
|
||||
// in a state nobody declared and what is wrong is on the machine.** They are fixed in
|
||||
// different places, so one word for both would send half the readers to the wrong one.
|
||||
Outcome string
|
||||
Said []string
|
||||
When string
|
||||
}
|
||||
|
||||
type quietMachine struct {
|
||||
Node string
|
||||
// Heard is "never" or how long ago. Never heard from is not the same as quiet for a while:
|
||||
// one may be a machine that was never sent anything.
|
||||
Heard string
|
||||
}
|
||||
|
||||
type staleModule struct {
|
||||
Module string
|
||||
Holds string
|
||||
Source string
|
||||
Running []string
|
||||
}
|
||||
|
||||
func viewOf(asked answers) view {
|
||||
out := view{Machines: len(asked.nodes), At: time.Now().Format("15:04:05")}
|
||||
for _, d := range asked.wrong {
|
||||
one := brokenMachine{Node: d.Node, Outcome: d.Outcome,
|
||||
When: d.At.Local().Format("2006-01-02 15:04")}
|
||||
if d.Refused != "" {
|
||||
// The host's own words. It says exactly what it could not accept, and nothing
|
||||
// written here would say it better.
|
||||
one.Said = append(one.Said, firstLine(d.Refused))
|
||||
}
|
||||
for _, f := range d.Failed {
|
||||
one.Said = append(one.Said, f.ID+": "+firstLine(f.Error))
|
||||
}
|
||||
out.Broken = append(out.Broken, one)
|
||||
}
|
||||
for _, n := range asked.quiet {
|
||||
out.Quiet = append(out.Quiet, quietMachine{Node: n.Name, Heard: heardFrom(n)})
|
||||
}
|
||||
for module, on := range asked.behind {
|
||||
from := asked.sources[module]
|
||||
out.Behind = append(out.Behind, staleModule{
|
||||
Module: module, Holds: short(from.BuiltFrom), Source: short(from.Head), Running: on,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// The page. Deliberately one file with no assets: a board that cannot render without fetching
|
||||
// something is a board that is blank exactly when the mesh is unwell.
|
||||
var page = template.Must(template.New("board").Parse(`<!doctype html>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>the mesh</title>
|
||||
<style>
|
||||
:root { color-scheme: light dark; }
|
||||
body { font: 15px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; margin: 2rem auto;
|
||||
max-width: 52rem; padding: 0 1rem; }
|
||||
h1 { font-size: 1.1rem; font-weight: 600; margin: 0 0 1.5rem; }
|
||||
h2 { font-size: 1rem; font-weight: 600; margin: 2rem 0 .5rem; }
|
||||
.quiet { opacity: .65; }
|
||||
.said { opacity: .8; padding-left: 1.5rem; }
|
||||
.outcome { display: inline-block; min-width: 4.5rem; }
|
||||
.refused { color: #b26b00; }
|
||||
.failed { color: #c0392b; }
|
||||
ul { list-style: none; padding: 0; margin: 0; }
|
||||
li { padding: .15rem 0; }
|
||||
footer { margin-top: 3rem; opacity: .6; font-size: .85rem; }
|
||||
</style>
|
||||
{{if .Unreachable}}
|
||||
<h1>the mesh cannot be read</h1>
|
||||
<p class="failed">{{.Unreachable}}</p>
|
||||
<p class="quiet">This says nothing about whether the mesh is well — only that this page could not
|
||||
find out.</p>
|
||||
{{else}}
|
||||
<h1>{{.Machines}} machine{{if ne .Machines 1}}s{{end}}</h1>
|
||||
|
||||
<h2>Is anything broken?</h2>
|
||||
{{if .Broken}}
|
||||
<ul>
|
||||
{{range .Broken}}
|
||||
<li>
|
||||
<span class="outcome {{.Outcome}}">{{.Outcome}}</span>
|
||||
<strong>{{.Node}}</strong> <span class="quiet">{{.When}}</span>
|
||||
{{range .Said}}<div class="said">{{.}}</div>{{end}}
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
{{else}}<p class="quiet">No. Every machine is doing what it was told.</p>{{end}}
|
||||
|
||||
<h2>Is anything not answering?</h2>
|
||||
{{if .Quiet}}
|
||||
<ul>{{range .Quiet}}<li><strong>{{.Node}}</strong> <span class="quiet">{{.Heard}}</span></li>{{end}}</ul>
|
||||
<p class="quiet">Not heard from is not the same as tried and could not — a machine here may be
|
||||
new, switched off, or unreachable.</p>
|
||||
{{else}}<p class="quiet">No. Every machine has been heard from.</p>{{end}}
|
||||
|
||||
<h2>Is anything out of date?</h2>
|
||||
{{if .Behind}}
|
||||
<ul>
|
||||
{{range .Behind}}
|
||||
<li><strong>{{.Module}}</strong> holds {{.Holds}}, source has {{.Source}}
|
||||
{{if .Running}}<div class="said">running on {{range $i, $n := .Running}}{{if $i}}, {{end}}{{$n}}{{end}}</div>
|
||||
{{else}}<div class="said quiet">assigned to nothing</div>{{end}}
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
{{else}}<p class="quiet">No. Every module is what its source last had.</p>{{end}}
|
||||
{{end}}
|
||||
|
||||
<footer>Read at {{.At}}. This page holds nothing and changes nothing.</footer>
|
||||
`))
|
||||
@@ -0,0 +1,121 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/novox/mesh-control/internal/inventory"
|
||||
)
|
||||
|
||||
// Refused and failed stay distinct all the way to the page.
|
||||
//
|
||||
// **Refused means the machine is exactly as it was and what is wrong is in what was sent; failed
|
||||
// means it is in a state nobody declared and what is wrong is on the machine.** They are fixed in
|
||||
// different places, so a page saying "error" for both sends half its readers to the wrong one.
|
||||
func TestRefusedAndFailedReachThePageAsDifferentThings(t *testing.T) {
|
||||
rendered := render(t, viewOf(answers{
|
||||
nodes: []inventory.Node{{Name: "anchor"}, {Name: "laptop"}},
|
||||
wrong: []inventory.Doing{
|
||||
{Node: "anchor", Outcome: "refused", Refused: "not a declaration this host speaks",
|
||||
At: time.Now()},
|
||||
{Node: "laptop", Outcome: "failed", At: time.Now(),
|
||||
Failed: []inventory.FailedResource{{ID: "web.container", Error: "no such image"}}},
|
||||
},
|
||||
}))
|
||||
// The rendered outcome, not the word anywhere on the page: both words appear in the
|
||||
// stylesheet, so a plain Contains passes whatever the machine actually said. It did.
|
||||
for _, want := range []string{`<span class="outcome refused">refused</span>`,
|
||||
`<span class="outcome failed">failed</span>`} {
|
||||
if !strings.Contains(rendered, want) {
|
||||
t.Fatalf("the page does not distinguish the two — missing %s:\n%s", want, rendered)
|
||||
}
|
||||
}
|
||||
// And the host's own words, which say exactly what it could not accept.
|
||||
for _, want := range []string{"not a declaration this host speaks", "web.container", "no such image"} {
|
||||
if !strings.Contains(rendered, want) {
|
||||
t.Fatalf("the page does not say %q, so a reader must go and ask:\n%s", want, rendered)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Nothing wrong is said, not left blank. An empty page and a well mesh must not look alike.
|
||||
func TestAWellMeshSaysSoRatherThanShowingNothing(t *testing.T) {
|
||||
rendered := render(t, viewOf(answers{nodes: []inventory.Node{{Name: "anchor"}}}))
|
||||
for _, want := range []string{
|
||||
"Every machine is doing what it was told",
|
||||
"Every machine has been heard from",
|
||||
"Every module is what its source last had",
|
||||
} {
|
||||
if !strings.Contains(rendered, want) {
|
||||
t.Fatalf("a well mesh does not say %q:\n%s", want, rendered)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A board that cannot reach the mesh must not render an empty page: that says "nothing is wrong"
|
||||
// in the one situation where nobody can know it.
|
||||
func TestABoardThatCannotReadTheMeshSaysSo(t *testing.T) {
|
||||
rendered := render(t, view{Unreachable: "the store did not answer"})
|
||||
if !strings.Contains(rendered, "the store did not answer") {
|
||||
t.Fatalf("the reason is not on the page:\n%s", rendered)
|
||||
}
|
||||
if strings.Contains(rendered, "Every machine is doing what it was told") {
|
||||
t.Fatal("a board that could not read the mesh reported that the mesh is well")
|
||||
}
|
||||
}
|
||||
|
||||
// Quiet is not broken, and the page says which it is.
|
||||
func TestQuietIsNotReportedAsBroken(t *testing.T) {
|
||||
rendered := render(t, viewOf(answers{
|
||||
nodes: []inventory.Node{{Name: "laptop"}},
|
||||
quiet: []inventory.Node{{Name: "laptop"}},
|
||||
}))
|
||||
if !strings.Contains(rendered, "not the same as tried and could not") {
|
||||
t.Fatalf("the page does not separate quiet from broken:\n%s", rendered)
|
||||
}
|
||||
if !strings.Contains(rendered, "Every machine is doing what it was told") {
|
||||
t.Fatalf("a quiet machine was counted as broken:\n%s", rendered)
|
||||
}
|
||||
}
|
||||
|
||||
// The page renders what a machine said, and a hostile string in it is not markup.
|
||||
//
|
||||
// What is on this page comes from machines, and a machine's own words are the whole reason the
|
||||
// page is useful. They are also the one thing here that nobody in this repository wrote.
|
||||
func TestWhatAMachineSaidIsNotMarkup(t *testing.T) {
|
||||
rendered := render(t, viewOf(answers{
|
||||
nodes: []inventory.Node{{Name: "anchor"}},
|
||||
wrong: []inventory.Doing{{Node: "anchor", Outcome: "refused",
|
||||
Refused: `<script>alert("from the machine")</script>`, At: time.Now()}},
|
||||
}))
|
||||
if strings.Contains(rendered, "<script>alert") {
|
||||
t.Fatalf("a machine's words were rendered as markup:\n%s", rendered)
|
||||
}
|
||||
if !strings.Contains(rendered, "<script>") {
|
||||
t.Fatalf("the words were not shown at all, so the reader cannot see what it said:\n%s", rendered)
|
||||
}
|
||||
}
|
||||
|
||||
// A module behind its source names the machines running the old one — the part with consequences.
|
||||
func TestBeingBehindNamesTheMachinesRunningTheOldOne(t *testing.T) {
|
||||
rendered := render(t, viewOf(answers{
|
||||
nodes: []inventory.Node{{Name: "laptop"}},
|
||||
behind: map[string][]string{"web": {"laptop"}},
|
||||
sources: map[string]inventory.Source{"web": {BuiltFrom: "aaaaaaaaaa", Head: "bbbbbbbbbb"}},
|
||||
}))
|
||||
for _, want := range []string{"web", "aaaaaaaa", "bbbbbbbb", "running on laptop"} {
|
||||
if !strings.Contains(rendered, want) {
|
||||
t.Fatalf("the page does not say %q:\n%s", want, rendered)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func render(t *testing.T, v view) string {
|
||||
t.Helper()
|
||||
var out strings.Builder
|
||||
if err := page.Execute(&out, v); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return out.String()
|
||||
}
|
||||
+59
-32
@@ -71,6 +71,8 @@ func run() error {
|
||||
return buildCommand(ctx, args[1:])
|
||||
case "builder":
|
||||
return builderCommand(ctx, args[1:])
|
||||
case "board":
|
||||
return boardCommand(ctx, args[1:])
|
||||
case "licence":
|
||||
return licenceCommand(ctx, args[1:])
|
||||
case "rotate":
|
||||
@@ -140,6 +142,7 @@ func usage() {
|
||||
module moved <name> <commit> the source has a newer commit than the mesh built
|
||||
module forget <name> remove one, unless a node is running it
|
||||
status [--json] what is wrong, what is quiet, and what is out of date
|
||||
board [--listen ADDR] the same three questions, as a page that holds nothing
|
||||
assign <node> <module> put a module on a node
|
||||
unassign <node> <module> take it off
|
||||
settings set <module> <file> what a module's config should say, for the whole mesh
|
||||
@@ -1791,41 +1794,12 @@ func statusCommand(ctx context.Context, args []string) error {
|
||||
}
|
||||
defer inv.Close()
|
||||
|
||||
// Three questions, in the order somebody asks them: is anything broken, is anything not
|
||||
// answering, is anything out of date. The first has consequences now, the second may, and
|
||||
// the third is a plan for later — and a status that led with the third would bury the first.
|
||||
//
|
||||
// All three are gathered before anything is said, so the two ways of saying it answer the
|
||||
// same questions from the same reads rather than being two implementations.
|
||||
wrong, err := inv.NotDoingWhatTheyWereTold(ctx)
|
||||
asked, err := theThreeQuestions(ctx, inv)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
nodes, err := inv.Nodes(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var quiet []inventory.Node
|
||||
for _, n := range nodes {
|
||||
// Never heard from, or not lately. Different from failing: a machine that says nothing
|
||||
// may be new, switched off, or unreachable, and none of those is a machine that tried
|
||||
// and could not.
|
||||
if n.LastSeen.IsZero() || time.Since(n.LastSeen) > time.Hour {
|
||||
quiet = append(quiet, n)
|
||||
}
|
||||
}
|
||||
behind, err := inv.Behind(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
sources := map[string]inventory.Source{}
|
||||
for module := range behind {
|
||||
from, err := inv.SourceOf(ctx, module)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
sources[module] = from
|
||||
}
|
||||
wrong, nodes, quiet := asked.wrong, asked.nodes, asked.quiet
|
||||
behind, sources := asked.behind, asked.sources
|
||||
|
||||
if *asJSON {
|
||||
body, err := statusAsJSON(wrong, nodes, quiet, behind, sources)
|
||||
@@ -2533,3 +2507,56 @@ func buildAndShow(ctx context.Context, repository, ref string, wait time.Duratio
|
||||
fmt.Println(string(body))
|
||||
return nil
|
||||
}
|
||||
|
||||
// answers is what the three questions came back with, read once.
|
||||
type answers struct {
|
||||
wrong []inventory.Doing
|
||||
nodes []inventory.Node
|
||||
quiet []inventory.Node
|
||||
behind map[string][]string
|
||||
sources map[string]inventory.Source
|
||||
}
|
||||
|
||||
// theThreeQuestions reads what anything answering "is the mesh alright" needs.
|
||||
//
|
||||
// **One reading, for every way of saying it** (novox/hq 03-DESIGN/01-to-be/11-a-board.md). There
|
||||
// are three now — a person's status, its JSON, and a page — and three implementations of "which
|
||||
// machine is not doing what it was told" would be three chances to disagree about it.
|
||||
//
|
||||
// The order is the design and not a convenience: is anything broken, is anything not answering, is
|
||||
// anything out of date. The first has consequences now, the second may, the third is a plan for
|
||||
// later — and anything that led with the third would bury the first.
|
||||
func theThreeQuestions(ctx context.Context, inv *inventory.Inventory) (answers, error) {
|
||||
var out answers
|
||||
var err error
|
||||
|
||||
out.wrong, err = inv.NotDoingWhatTheyWereTold(ctx)
|
||||
if err != nil {
|
||||
return answers{}, err
|
||||
}
|
||||
out.nodes, err = inv.Nodes(ctx)
|
||||
if err != nil {
|
||||
return answers{}, err
|
||||
}
|
||||
for _, n := range out.nodes {
|
||||
// Never heard from, or not lately. Different from failing: a machine that says nothing
|
||||
// may be new, switched off, or unreachable, and none of those is a machine that tried
|
||||
// and could not.
|
||||
if n.LastSeen.IsZero() || time.Since(n.LastSeen) > time.Hour {
|
||||
out.quiet = append(out.quiet, n)
|
||||
}
|
||||
}
|
||||
out.behind, err = inv.Behind(ctx)
|
||||
if err != nil {
|
||||
return answers{}, err
|
||||
}
|
||||
out.sources = map[string]inventory.Source{}
|
||||
for module := range out.behind {
|
||||
from, err := inv.SourceOf(ctx, module)
|
||||
if err != nil {
|
||||
return answers{}, err
|
||||
}
|
||||
out.sources[module] = from
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user