Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jschoubben
|
ab74988f1c |
@@ -153,26 +153,6 @@ func (b *Build) problems(module string) []string {
|
||||
"%s: %q is a bundle and says no language, so nothing can choose a compiler "+
|
||||
"for it", module, a.Name))
|
||||
}
|
||||
// **A system, for a language that compiles to a binary** (novox/hq ADR 0142). A binary
|
||||
// is pinned to one operating system at link time so a host refuses to touch a machine
|
||||
// it was not built for (novox/hq ADR 0005); an artifact that says nothing would be
|
||||
// compiled for whatever the build machine happened to be, which reads as portable and
|
||||
// is not.
|
||||
if compiled := compilesToABinary(a.Language); compiled && strings.TrimSpace(a.System) == "" {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s: %q is compiled to a binary and says no system, so it would be built for "+
|
||||
"whatever the build machine happens to be. Declare one artifact per "+
|
||||
"system: %s", module, a.Name, spokenSystems()))
|
||||
} else if !compiled && strings.TrimSpace(a.System) != "" {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s: %q names the system %q and is written in %q, which compiles to code that "+
|
||||
"runs anywhere — a system that decides nothing reads as though it did",
|
||||
module, a.Name, a.System, a.Language))
|
||||
} else if compiled && !knownSystem(a.System) {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s: %q is built for %q, and a system is %s",
|
||||
module, a.Name, a.System, spokenSystems()))
|
||||
}
|
||||
} else {
|
||||
if a.From == "" {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
@@ -213,42 +193,3 @@ func oneOrOther(n int) string {
|
||||
}
|
||||
return "them"
|
||||
}
|
||||
|
||||
// Systems the mesh builds binaries for, which is the set a host may be pinned to (novox/hq ADR 0005).
|
||||
//
|
||||
// **A closed list, and the host's own, not the compiler's.** These are not the values a Go toolchain
|
||||
// would call an operating system — the difference between two of them is a C library, not a kernel.
|
||||
// They are what a machine reports itself to be and what a host is linked to refuse, so the list that
|
||||
// matters is the one the host understands.
|
||||
var systems = []string{"alpine", "android", "arch"}
|
||||
|
||||
// knownSystem is whether the mesh builds for it.
|
||||
func knownSystem(system string) bool {
|
||||
want := strings.ToLower(strings.TrimSpace(system))
|
||||
for _, s := range systems {
|
||||
if s == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// spokenSystems is the list as a refusal says it, so a reader is one edit from right.
|
||||
func spokenSystems() string {
|
||||
return strings.Join(systems, ", ")
|
||||
}
|
||||
|
||||
// compilesToABinary is whether this language's bundle is a binary for one operating system rather
|
||||
// than code that runs wherever its interpreter does.
|
||||
//
|
||||
// **Asked of the language, not of the artifact.** A module says what it is written in; what that
|
||||
// implies is the mesh's to know, exactly as the compiler is (novox/hq ADR 0142). Asking the artifact
|
||||
// would let two artifacts in one language disagree about whether they are portable.
|
||||
func compilesToABinary(language string) bool {
|
||||
switch strings.ToLower(strings.TrimSpace(language)) {
|
||||
case "go":
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// bundleFor is a manifest whose one artifact is a bundle in the given language and system.
|
||||
func bundleFor(language, system string) Manifest {
|
||||
return Manifest{Module: "a-component", Build: &Build{Artifacts: []Artifact{
|
||||
{Name: "binary", Kind: ArtifactBundle, Language: language, System: system},
|
||||
}}}
|
||||
}
|
||||
|
||||
func problemsOf(t *testing.T, m Manifest) string {
|
||||
t.Helper()
|
||||
return strings.Join(m.Build.problems(m.Module), "\n")
|
||||
}
|
||||
|
||||
// **A language that compiles to a binary must say which system.**
|
||||
//
|
||||
// A binary is pinned to one operating system at link time, so a host refuses to touch a machine it
|
||||
// was not built for. An artifact that says nothing would be compiled for whatever the build machine
|
||||
// happened to be — which reads as portable and is not, and is the fault this check exists for.
|
||||
func TestABinaryMustSayWhichSystemItIsFor(t *testing.T) {
|
||||
got := problemsOf(t, bundleFor("go", ""))
|
||||
if !strings.Contains(got, "says no system") {
|
||||
t.Fatalf("a compiled bundle with no system was accepted:\n%s", got)
|
||||
}
|
||||
// And the refusal names what it could have said, so a reader is one edit from right.
|
||||
for _, system := range []string{"alpine", "android", "arch"} {
|
||||
if !strings.Contains(got, system) {
|
||||
t.Fatalf("the refusal does not name %q as a choice:\n%s", system, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestABinaryThatNamesASystemIsAccepted(t *testing.T) {
|
||||
if got := problemsOf(t, bundleFor("go", "arch")); got != "" {
|
||||
t.Fatalf("a compiled bundle naming a system was refused:\n%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
// A system the mesh does not build for is refused where it is written. These are the host's own
|
||||
// names, not a compiler's: the difference between two of them is a C library rather than a kernel,
|
||||
// so a value that looks like an operating system to a toolchain is still wrong here.
|
||||
func TestASystemTheMeshDoesNotBuildForIsRefused(t *testing.T) {
|
||||
for _, wrong := range []string{"linux", "debian", "darwin"} {
|
||||
got := problemsOf(t, bundleFor("go", wrong))
|
||||
if !strings.Contains(got, "and a system is") {
|
||||
t.Fatalf("%q was accepted as a system:\n%s", wrong, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **And a language that runs anywhere must not name one.** A system that decides nothing reads as
|
||||
// though it did, which is the same fault as a restriction that restricts nothing (novox/hq ADR 0045).
|
||||
func TestAPortableBundleMayNotNameASystem(t *testing.T) {
|
||||
got := problemsOf(t, bundleFor("typescript", "arch"))
|
||||
if !strings.Contains(got, "runs anywhere") {
|
||||
t.Fatalf("a portable bundle was allowed to name a system:\n%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAPortableBundleNamingNoSystemIsAccepted(t *testing.T) {
|
||||
if got := problemsOf(t, bundleFor("typescript", "")); got != "" {
|
||||
t.Fatalf("an ordinary bundle was refused:\n%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
// One component, one artifact per system: the shape the mesh's own binaries are declared in, and the
|
||||
// reason the target is the artifact's rather than the recipe's.
|
||||
func TestOneArtifactPerSystemIsAccepted(t *testing.T) {
|
||||
m := Manifest{Module: "the-host", Build: &Build{Artifacts: []Artifact{
|
||||
{Name: "arch", Kind: ArtifactBundle, Language: "go", System: "arch"},
|
||||
{Name: "alpine", Kind: ArtifactBundle, Language: "go", System: "alpine"},
|
||||
{Name: "android", Kind: ArtifactBundle, Language: "go", System: "android"},
|
||||
}}}
|
||||
if got := problemsOf(t, m); got != "" {
|
||||
t.Fatalf("one artifact per system was refused:\n%s", got)
|
||||
}
|
||||
}
|
||||
@@ -897,35 +897,6 @@ func (r Resolution) Rules(with Rendering) ([]Rule, error) {
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
// And how far each endpoint reaches, which says the same thing to the filter and more
|
||||
// besides (novox/hq ADR 0138). Folded in here rather than beside: the filter has one
|
||||
// question — from where — and a reach answers it, so giving it two inputs would let them
|
||||
// disagree. Reaches refuses a port that both name, so this cannot silently prefer one.
|
||||
reaches, err := Reaches(m, with.Settings[m.Module])
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
// **Only for an endpoint the proxy does not serve.** A routed endpoint's port is how the
|
||||
// proxy reaches it and nothing else (ADR 0045), so `public` there asks for a public name and
|
||||
// says nothing about the port — opening it to the world as well would undo the arrangement
|
||||
// the proxy exists for, and would silently reopen a port an operator had narrowed.
|
||||
//
|
||||
// Found by trying to express a real module: one whose routed name must be public and whose
|
||||
// machine-side port must not be. Under one value for both, there was no way to say it.
|
||||
routed := RoutedPorts(m)
|
||||
for port, reach := range reaches {
|
||||
if routed[port] {
|
||||
continue
|
||||
}
|
||||
source, ok := FilterSource(reach)
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("%s: %q is not a reach the filter can read", m.Module, reach)
|
||||
}
|
||||
if e == nil {
|
||||
e = map[int]string{}
|
||||
}
|
||||
e[port] = source
|
||||
}
|
||||
if e != nil {
|
||||
exposure[m.Module] = e
|
||||
}
|
||||
@@ -1094,11 +1065,7 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s contributing to %s: %w", m.Module, to, err)
|
||||
}
|
||||
reaches, err := Reaches(m, settings[m.Module])
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s contributing to %s: %w", m.Module, to, err)
|
||||
}
|
||||
composeName(values, r.PublicDomain, r.At, reaches, endpointPorts(m))
|
||||
composeName(values, r.PublicDomain, r.At)
|
||||
out[to] = append(out[to], Contribution{From: m.Module, Values: values})
|
||||
}
|
||||
// Several contributions to one requirement (ADR 0094's sibling for `contributes`): an
|
||||
@@ -1112,11 +1079,7 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s contributing %s to %s: %w", m.Module, local, to, err)
|
||||
}
|
||||
reaches, err := Reaches(m, settings[m.Module])
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s contributing %s to %s: %w", m.Module, local, to, err)
|
||||
}
|
||||
composeName(values, r.PublicDomain, r.At, reaches, endpointPorts(m))
|
||||
composeName(values, r.PublicDomain, r.At)
|
||||
out[to] = append(out[to], Contribution{From: m.Module, Values: values})
|
||||
}
|
||||
}
|
||||
@@ -1147,35 +1110,10 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
|
||||
// the running mesh keeps serving the full names it has. And a labelled contribution on a node with
|
||||
// no public domain composes nothing — there is nothing to join it to — which reads downstream as a
|
||||
// route that named no host, the same as it would have before this existed.
|
||||
func composeName(values map[string]any, publicDomain, internalDomain string, reaches map[int]string,
|
||||
ports map[string]int) {
|
||||
func composeName(values map[string]any, publicDomain, internalDomain string) {
|
||||
if values == nil {
|
||||
return
|
||||
}
|
||||
// **How far the endpoint this route serves reaches decides which names exist** (novox/hq ADR
|
||||
// 0138). Both were composed whenever the node had both domains, so every routed module got a
|
||||
// public name and an internal one whether anybody wanted them or not — and a certificate for
|
||||
// each, because the proxy certifies the names it is given.
|
||||
//
|
||||
// Joined by the port: a route entry names the port it serves and the module declares a listen on
|
||||
// it. An entry with no port is not an endpoint's route but a rule about a name — a path-level
|
||||
// refusal shadowing another route — and it inherits whatever that route's names turned out to
|
||||
// be, which is why it is left alone here.
|
||||
//
|
||||
// Nothing said is both names, as before. That is what keeps every mesh already running identical
|
||||
// until an assignment speaks.
|
||||
wantPublic, wantInternal := true, true
|
||||
if port, ok := endpointPortOf(values, ports); ok {
|
||||
if reach, said := reaches[port]; said {
|
||||
wantPublic, wantInternal = WantsPublicName(reach), WantsInternalName(reach)
|
||||
}
|
||||
}
|
||||
if !wantPublic {
|
||||
publicDomain = ""
|
||||
}
|
||||
if !wantInternal {
|
||||
internalDomain = ""
|
||||
}
|
||||
if _, already := values["name"]; already {
|
||||
// A full name was given rather than a label. Left as-is: this is the legacy shape, and the
|
||||
// point of the label is to not have to write the full name — a contribution that wrote both
|
||||
@@ -1795,28 +1733,3 @@ func prepared(from map[string]any) map[string]any {
|
||||
delete(step, "reload-on")
|
||||
return step
|
||||
}
|
||||
|
||||
// endpointPortOf is the port the endpoint a route serves listens on: looked up by the name the route
|
||||
// gives, or read from the port it repeats (novox/hq ADR 0138).
|
||||
//
|
||||
// `ports` maps this module's endpoint names to their ports, computed once per module rather than
|
||||
// re-scanned per contribution.
|
||||
func endpointPortOf(values map[string]any, ports map[string]int) (int, bool) {
|
||||
if name, ok := values[RouteEndpoint].(string); ok {
|
||||
if port, found := ports[strings.TrimSpace(name)]; found {
|
||||
return port, true
|
||||
}
|
||||
}
|
||||
return asPort(values["port"])
|
||||
}
|
||||
|
||||
// endpointPorts is a module's endpoint names against the ports they listen on.
|
||||
func endpointPorts(m Manifest) map[string]int {
|
||||
out := map[string]int{}
|
||||
for _, l := range m.Listens {
|
||||
if name := strings.TrimSpace(l.Name); name != "" {
|
||||
out[name] = l.Port
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
@@ -1,141 +0,0 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// aMediaServer is the shape one port number per key cannot express: two endpoints of different kinds.
|
||||
// A web surface a proxy serves under a subdomain, and a protocol port clients dial directly because
|
||||
// the client expects that number.
|
||||
func aMediaServer() Manifest {
|
||||
return Manifest{
|
||||
Module: "media",
|
||||
Listens: []Listening{
|
||||
{Name: "web", Port: 80, From: FromMesh, Why: "the app, behind the proxy"},
|
||||
{Name: "stream", Port: 32400, From: FromEverywhere, Fixed: true,
|
||||
Why: "the client dials this number; the protocol chose it"},
|
||||
},
|
||||
Contributes: map[string]map[string]any{
|
||||
"route": {"label": "media", RouteEndpoint: "web"},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// **A route names the endpoint it serves.** A route and a listen both carried a port and nothing said
|
||||
// they were the same thing; now one of them says so.
|
||||
func TestARouteNamesTheEndpointItServes(t *testing.T) {
|
||||
m := aMediaServer()
|
||||
if port, ok := EndpointPort(m, "web"); !ok || port != 80 {
|
||||
t.Fatalf("the web endpoint resolves to %d (%v), want 80", port, ok)
|
||||
}
|
||||
if port, ok := EndpointPort(m, "stream"); !ok || port != 32400 {
|
||||
t.Fatalf("the stream endpoint resolves to %d (%v), want 32400", port, ok)
|
||||
}
|
||||
if _, ok := EndpointPort(m, "absent"); ok {
|
||||
t.Fatal("an endpoint the module does not declare resolved to a port")
|
||||
}
|
||||
}
|
||||
|
||||
// And the routed set is read through the name, so the endpoint the proxy serves is known without a
|
||||
// reader joining two numbers.
|
||||
func TestTheRoutedEndpointIsFoundByName(t *testing.T) {
|
||||
routed := RoutedPorts(aMediaServer())
|
||||
if !routed[80] {
|
||||
t.Fatalf("the routed endpoint was not found by name: %v", routed)
|
||||
}
|
||||
// And the directly-dialled one is not routed, which is what lets its reach govern its port.
|
||||
if routed[32400] {
|
||||
t.Fatalf("the endpoint clients dial directly reads as routed: %v", routed)
|
||||
}
|
||||
}
|
||||
|
||||
// **Two endpoints of different shapes, configured as themselves.** The web endpoint's reach asks for
|
||||
// names and leaves its port to the proxy; the stream endpoint's reach governs its port, because
|
||||
// clients dial it and there is no name.
|
||||
func TestTwoEndpointsOfDifferentShapesAreConfiguredSeparately(t *testing.T) {
|
||||
m := aMediaServer()
|
||||
settings := SettingsBy{"media": {{From: "node anchor", Values: map[string]any{
|
||||
ReachSetting: map[string]any{"80": ReachBoth, "32400": ReachPublic},
|
||||
}}}}
|
||||
|
||||
r := Resolution{Node: "anchor", Modules: []Manifest{m},
|
||||
PublicDomain: "example.test", At: "anchor.internal"}
|
||||
rules, err := r.Rules(Rendering{Settings: settings})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, rule := range rules {
|
||||
switch rule.Port {
|
||||
case 80:
|
||||
if rule.From != FromMesh {
|
||||
t.Fatalf("the routed endpoint's port opened to %q; the proxy is how it is reached",
|
||||
rule.From)
|
||||
}
|
||||
case 32400:
|
||||
if rule.From != FromEverywhere {
|
||||
t.Fatalf("the directly-dialled endpoint's port is %q, want anywhere", rule.From)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// And the routed one carries both names, asked for by the same statement.
|
||||
given, err := r.contributions(settings, nil, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var public, internal string
|
||||
for _, c := range given["route"] {
|
||||
public, _ = c.Values["name"].(string)
|
||||
internal, _ = c.Values["internal-name"].(string)
|
||||
}
|
||||
if public != "media.example.test" || internal != "media.anchor.internal" {
|
||||
t.Fatalf("names are %q and %q, want both", public, internal)
|
||||
}
|
||||
}
|
||||
|
||||
// A route naming an endpoint the module does not declare reaches nothing, and is refused where it is
|
||||
// written rather than resolving to no port and serving nothing.
|
||||
func TestARouteNamingAnEndpointTheModuleLacksIsRefused(t *testing.T) {
|
||||
m := aMediaServer()
|
||||
m.Contributes["route"][RouteEndpoint] = "absent"
|
||||
got := strings.Join(RouteProblems(m), "\n")
|
||||
if !strings.Contains(got, "does not declare") {
|
||||
t.Fatalf("a route naming an absent endpoint was accepted:\n%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
// **Two endpoints called the same would make an assignment configure whichever was read last.** The
|
||||
// point of a name is that it identifies one thing.
|
||||
func TestTwoEndpointsWithOneNameAreRefused(t *testing.T) {
|
||||
m := Manifest{Module: "twice", Listens: []Listening{
|
||||
{Name: "web", Port: 80, From: FromMesh},
|
||||
{Name: "web", Port: 8080, From: FromMesh},
|
||||
}}
|
||||
got := strings.Join(endpointNameProblems(m), "\n")
|
||||
if !strings.Contains(got, "could mean either") {
|
||||
t.Fatalf("two endpoints with one name were accepted:\n%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
// A name that is not a name is refused where it is written: it ends up in something a person types.
|
||||
func TestAnEndpointNameIsHeldToItsShape(t *testing.T) {
|
||||
for _, wrong := range []string{"Web", "web port", "3000", "-web", "web_surface"} {
|
||||
m := Manifest{Module: "odd", Listens: []Listening{{Name: wrong, Port: 80, From: FromMesh}}}
|
||||
if got := strings.Join(endpointNameProblems(m), "\n"); !strings.Contains(got, "a name is lowercase") {
|
||||
t.Fatalf("%q was accepted as an endpoint name:\n%s", wrong, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **Every endpoint in the catalogue is unnamed today, and must stay valid.** The word ships one
|
||||
// release before anything uses it.
|
||||
func TestAnUnnamedEndpointIsStillValid(t *testing.T) {
|
||||
m := Manifest{Module: "ordinary", Listens: []Listening{{Port: 443, From: FromEverywhere}}}
|
||||
if got := endpointNameProblems(m); len(got) != 0 {
|
||||
t.Fatalf("an unnamed endpoint was refused: %v", got)
|
||||
}
|
||||
if got := RouteProblems(m); len(got) != 0 {
|
||||
t.Fatalf("a module with no route was refused: %v", got)
|
||||
}
|
||||
}
|
||||
@@ -701,198 +701,3 @@ func sortedPorts(of map[int]int) []int {
|
||||
sort.Ints(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// ReachSetting is the settings key that says how far one of a module's endpoints reaches, per node
|
||||
// (novox/hq ADR 0138):
|
||||
//
|
||||
// {"reach": {"3000": "internal"}}
|
||||
//
|
||||
// **One value, three readers.** Reachability used to be settled three times over: the filter read a
|
||||
// listen's source, which `expose` could override; the proxy composed a public name and an internal
|
||||
// name for every route it was given, because it could; and the certificate authority followed from
|
||||
// which names existed. Each was defensible and the combination was unstated, so "this endpoint must
|
||||
// not be public" could not be written and was therefore enforced by nothing — while a public
|
||||
// certificate for that very name was obtained anyway.
|
||||
//
|
||||
// It keys on the port the module declares, the same key `ports` and `expose` use. A route names that
|
||||
// port too, which is what lets one statement reach the names as well as the filter: of the 36 route
|
||||
// entries in the catalogue, 35 name a port that the same module declares a listen on, and the one
|
||||
// that does not is a path-level refusal — a rule about a name rather than an endpoint.
|
||||
const ReachSetting = "reach"
|
||||
|
||||
// How far an endpoint reaches. Four values, because they have to cover everything `expose` could say
|
||||
// as well as the two names.
|
||||
const (
|
||||
// ReachMachine is this machine only: not the private network, not the world, and no name.
|
||||
ReachMachine = "machine"
|
||||
// ReachInternal is the private network, under the internal name and not the public one.
|
||||
ReachInternal = "internal"
|
||||
// ReachPublic is the world, under the public name and not the internal one.
|
||||
ReachPublic = "public"
|
||||
// ReachBoth is the world, under both names — each certified by its own authority.
|
||||
//
|
||||
// The filter cannot distinguish this from ReachPublic, and should not try: the mesh's addresses
|
||||
// are a subset of anywhere. What differs is the names, which is the whole reason reach is not
|
||||
// simply the filter's vocabulary with nicer words.
|
||||
ReachBoth = "both"
|
||||
)
|
||||
|
||||
// reaches is every value, in the order a refusal lists them.
|
||||
var reaches = []string{ReachMachine, ReachInternal, ReachPublic, ReachBoth}
|
||||
|
||||
// RoutedPorts are the ports a module serves through a proxy, taken from its route contributions.
|
||||
//
|
||||
// **A routed endpoint's port is how the proxy reaches it, and nothing else.** That is ADR 0045's
|
||||
// decision and it is older than reach: a public service listens `from: mesh`, only the proxy reaches
|
||||
// it, and it is exposed by name. So `public` on a routed endpoint asks for a public *name*; opening
|
||||
// that port to the world as well would undo the arrangement the proxy exists for.
|
||||
//
|
||||
// Measured before this was written, not reasoned: a module's routed name answered from the internet
|
||||
// over TLS while its machine-side port was refused from the same place. The port is not the path.
|
||||
func RoutedPorts(m Manifest) map[int]bool {
|
||||
out := map[int]bool{}
|
||||
note := func(values map[string]any) {
|
||||
// **The endpoint it serves, by name where it says one.** A route repeating a port number is
|
||||
// the older shape and still read: 35 of the catalogue's 36 route entries name a port their
|
||||
// module declares a listen on (novox/hq ADR 0138).
|
||||
if name, ok := values[RouteEndpoint].(string); ok {
|
||||
if port, found := EndpointPort(m, name); found {
|
||||
out[port] = true
|
||||
return
|
||||
}
|
||||
}
|
||||
if port, ok := asPort(values["port"]); ok {
|
||||
out[port] = true
|
||||
}
|
||||
}
|
||||
if values, ok := m.Contributes["route"]; ok {
|
||||
note(values)
|
||||
}
|
||||
for _, values := range m.ContributesMany["route"] {
|
||||
note(values)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// FilterSource is the source a reach means to the packet filter.
|
||||
//
|
||||
// `public` and `both` are the same here. A reach that opened a port to the mesh and not to the world
|
||||
// would be `internal`; there is no reach that opens it to the world and *not* to the mesh, because a
|
||||
// filter cannot express "everyone except these" and nobody has asked for it.
|
||||
func FilterSource(reach string) (string, bool) {
|
||||
switch reach {
|
||||
case ReachMachine:
|
||||
return FromMachine, true
|
||||
case ReachInternal:
|
||||
return FromMesh, true
|
||||
case ReachPublic, ReachBoth:
|
||||
return FromEverywhere, true
|
||||
default:
|
||||
return "", false
|
||||
}
|
||||
}
|
||||
|
||||
// WantsPublicName is whether a reach asks for the route's public name to be composed.
|
||||
func WantsPublicName(reach string) bool { return reach == ReachPublic || reach == ReachBoth }
|
||||
|
||||
// WantsInternalName is whether a reach asks for the route's internal name to be composed.
|
||||
func WantsInternalName(reach string) bool { return reach == ReachInternal || reach == ReachBoth }
|
||||
|
||||
// Reaches reads a module's per-node reach settings: declared port → how far it reaches.
|
||||
//
|
||||
// It refuses a reach for a port the module does not listen on, or a value that is not one of the
|
||||
// four — the "reads as a restriction and is none" fault this whole mechanism exists to prevent
|
||||
// (novox/hq ADR 0043/0045). It also refuses a port that `expose` names as well: the two say the same
|
||||
// thing in different words, and a module whose reach and exposure disagree would have the filter
|
||||
// following one and the names following the other, which is the very confusion ADR 0138 removes.
|
||||
//
|
||||
// A module with no `reach` setting yields nothing, and everything behaves exactly as before: the
|
||||
// filter follows the manifest's `from`, and both names are composed. That is what keeps every machine
|
||||
// already running unchanged until an assignment says otherwise.
|
||||
func Reaches(m Manifest, layers []Layer) (map[int]string, error) {
|
||||
listened := make(map[int]bool, len(m.Listens))
|
||||
for _, l := range m.Listens {
|
||||
listened[l.Port] = true
|
||||
}
|
||||
|
||||
exposed, err := Exposure(m, layers)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
out := map[int]string{}
|
||||
for _, layer := range layers {
|
||||
raw, ok := layer.Values[ReachSetting]
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
entries, ok := raw.(map[string]any)
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("%s: %s is a { port: reach } map, and %q set it to something else",
|
||||
m.Module, ReachSetting, layer.From)
|
||||
}
|
||||
for portText, value := range entries {
|
||||
port, err := strconv.Atoi(portText)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s says how far %q reaches, which is not a port", m.Module, portText)
|
||||
}
|
||||
if !listened[port] {
|
||||
return nil, fmt.Errorf(
|
||||
"%s says how far port %d reaches, which it does not listen on — the setting "+
|
||||
"reaches nothing", m.Module, port)
|
||||
}
|
||||
reach, ok := value.(string)
|
||||
if !ok || !slices.Contains(reaches, reach) {
|
||||
return nil, fmt.Errorf("%s says port %d reaches %v; a reach is %s",
|
||||
m.Module, port, value, strings.Join(reaches, ", "))
|
||||
}
|
||||
if _, both := exposed[port]; both {
|
||||
return nil, fmt.Errorf(
|
||||
"%s sets both %s and %s for port %d. They say the same thing in different "+
|
||||
"words, and the filter would follow one while its names followed the other "+
|
||||
"— which is what %s exists to stop. Keep %s",
|
||||
m.Module, ReachSetting, ExposeSetting, port, ReachSetting, ReachSetting)
|
||||
}
|
||||
out[port] = reach
|
||||
}
|
||||
}
|
||||
if len(out) == 0 {
|
||||
return nil, nil
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// RouteEndpoint is the key a route contribution names the endpoint it serves with, instead of
|
||||
// repeating that endpoint's port (novox/hq ADR 0138).
|
||||
//
|
||||
// **A route and a listen both carried a port, and nothing said they were the same thing.** They
|
||||
// always were — a route serves one of the module's own endpoints — but a reader had to join two
|
||||
// numbers, and an assignment configuring "the web endpoint" had to know which number that was. A
|
||||
// route that names the endpoint says what it means, and the mesh looks the port up.
|
||||
const RouteEndpoint = "endpoint"
|
||||
|
||||
// RouteProblems holds a module's route contributions to naming an endpoint it actually has.
|
||||
//
|
||||
// A route naming an endpoint the module does not declare reaches nothing, and is refused where it is
|
||||
// written rather than resolving to no port and serving nothing — the fault this repository names most
|
||||
// often, a declaration that reads as though it did something.
|
||||
func RouteProblems(m Manifest) []string {
|
||||
var problems []string
|
||||
check := func(where string, values map[string]any) {
|
||||
name, ok := values[RouteEndpoint].(string)
|
||||
if !ok || strings.TrimSpace(name) == "" {
|
||||
return
|
||||
}
|
||||
if _, found := EndpointPort(m, name); !found {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s routes %s to the endpoint %q, which it does not declare", m.Module, where, name))
|
||||
}
|
||||
}
|
||||
if values, ok := m.Contributes["route"]; ok {
|
||||
check("a name", values)
|
||||
}
|
||||
for local, values := range m.ContributesMany["route"] {
|
||||
check(local, values)
|
||||
}
|
||||
return problems
|
||||
}
|
||||
|
||||
@@ -571,21 +571,6 @@ type Artifact struct {
|
||||
// image built from this same module's own repository, the same as every other artifact.
|
||||
Context *ArtifactContext `json:"context,omitempty"`
|
||||
|
||||
// System is the operating system this artifact is compiled for, for a bundle whose output is a
|
||||
// binary rather than portable code (novox/hq ADR 0142).
|
||||
//
|
||||
// **Named by the artifact, not by the recipe.** A toolchain deliberately accepts nothing from
|
||||
// the module — anything a module could override there it would be writing a Dockerfile to
|
||||
// override — and yet a compiled binary is per operating system, pinned at link time so a host
|
||||
// refuses to touch a machine it was not built for (novox/hq ADR 0005). The way out is that the
|
||||
// target is a property of the artifact: one artifact declared per system, one build each, and
|
||||
// the recipe stays the mesh's.
|
||||
//
|
||||
// Empty for a bundle whose output runs anywhere, which is every interpreted language, and for
|
||||
// every other kind. A bundle in a language that compiles to a binary must say one, because
|
||||
// "compiled for whatever the build machine happened to be" is the fault this exists to prevent.
|
||||
System string `json:"system,omitempty"`
|
||||
|
||||
// Language is what this module's code is written in, for a bundle.
|
||||
//
|
||||
// **Declared, never guessed.** Inferring it from what files happen to be present makes a
|
||||
@@ -657,23 +642,8 @@ const (
|
||||
// on is a fact, and it should be written once.
|
||||
const ArtifactStoreProvision = "artifact-store"
|
||||
|
||||
// Listening is one endpoint a module serves: a port it accepts connections on, and what may be said
|
||||
// about that port from outside the module.
|
||||
// Listening is one port a module accepts connections on.
|
||||
type Listening struct {
|
||||
// Name is what this endpoint is called, so an assignment and a route can refer to it as one thing
|
||||
// (novox/hq ADR 0138).
|
||||
//
|
||||
// **Because a port number is not a name.** Three facts have to be said about an endpoint when a
|
||||
// module is assigned — which machine port it lands on, the subdomain a proxy serves it under, and
|
||||
// how far it reaches — and they were said in three places keyed by the port. A module with two
|
||||
// endpoints of different shapes, a web surface behind a proxy and a protocol port clients dial
|
||||
// directly, cannot be configured that way without a reader joining numbers by hand.
|
||||
//
|
||||
// The module's to choose, like the route's label: it names its own parts. Lowercase, and unique
|
||||
// within the module, so a reference to it is unambiguous. Empty is allowed and means an endpoint
|
||||
// nothing refers to by name, which is every endpoint in the catalogue until they are named.
|
||||
Name string `json:"name,omitempty"`
|
||||
|
||||
Port int `json:"port"`
|
||||
// Protocol is "tcp" or "udp". Absent means tcp, which is what almost everything is — and a
|
||||
// field that had to be written every time would be written wrongly some of the time.
|
||||
@@ -1280,8 +1250,6 @@ func ParseManifest(raw []byte) (Manifest, error) {
|
||||
"%s listens on %d over %q, which is tcp or udp", m.Module, l.Port, p))
|
||||
}
|
||||
}
|
||||
problems = append(problems, endpointNameProblems(m)...)
|
||||
problems = append(problems, RouteProblems(m)...)
|
||||
for _, port := range m.Guards {
|
||||
if port < 1 || port > 65535 {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
@@ -1706,53 +1674,3 @@ func (m Manifest) undeclaredMounts() []string {
|
||||
}
|
||||
return problems
|
||||
}
|
||||
|
||||
// endpointName is what an endpoint may be called: lowercase letters, digits and dashes, starting
|
||||
// with a letter. The same shape a label has, because both end up in something a person types.
|
||||
var endpointName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
|
||||
|
||||
// endpointNameProblems holds a module's endpoint names to being usable as references (novox/hq ADR
|
||||
// 0138).
|
||||
//
|
||||
// **Unique, because the point of a name is that it identifies one thing.** Two endpoints called the
|
||||
// same would make an assignment that configures one silently configure whichever the mesh read last
|
||||
// — the shape of fault this repository keeps finding, where a declaration appears to say something
|
||||
// and says something else.
|
||||
func endpointNameProblems(m Manifest) []string {
|
||||
var problems []string
|
||||
seen := map[string]int{}
|
||||
for _, l := range m.Listens {
|
||||
name := strings.TrimSpace(l.Name)
|
||||
if name == "" {
|
||||
continue
|
||||
}
|
||||
if !endpointName.MatchString(name) {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s calls the endpoint on port %d %q; a name is lowercase letters, digits and "+
|
||||
"dashes, starting with a letter", m.Module, l.Port, l.Name))
|
||||
continue
|
||||
}
|
||||
if before, already := seen[name]; already {
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s calls both port %d and port %d %q, so anything naming that endpoint could mean "+
|
||||
"either", m.Module, before, l.Port, name))
|
||||
continue
|
||||
}
|
||||
seen[name] = l.Port
|
||||
}
|
||||
return problems
|
||||
}
|
||||
|
||||
// EndpointPort is the port of the endpoint a module calls this, and whether it has one.
|
||||
func EndpointPort(m Manifest, name string) (int, bool) {
|
||||
want := strings.TrimSpace(name)
|
||||
if want == "" {
|
||||
return 0, false
|
||||
}
|
||||
for _, l := range m.Listens {
|
||||
if strings.TrimSpace(l.Name) == want {
|
||||
return l.Port, true
|
||||
}
|
||||
}
|
||||
return 0, false
|
||||
}
|
||||
|
||||
@@ -1,206 +0,0 @@
|
||||
package catalogue
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// a web module with one routed endpoint, the shape almost every routed module in the catalogue has.
|
||||
func aRoutedWeb() Manifest {
|
||||
return Manifest{
|
||||
Module: "web",
|
||||
Listens: []Listening{{Port: 3000, From: FromMesh}},
|
||||
Contributes: map[string]map[string]any{
|
||||
"route": {"label": "app", "port": 3000},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func reachSet(reach string) SettingsBy {
|
||||
return SettingsBy{"web": {{From: "node anchor",
|
||||
Values: map[string]any{ReachSetting: map[string]any{"3000": reach}}}}}
|
||||
}
|
||||
|
||||
// namesFor renders the contribution a routed module makes and returns the two names it carries.
|
||||
func namesFor(t *testing.T, m Manifest, settings SettingsBy) (public, internal string) {
|
||||
t.Helper()
|
||||
r := Resolution{Node: "anchor", Modules: []Manifest{m},
|
||||
PublicDomain: "example.test", At: "anchor.internal"}
|
||||
given, err := r.contributions(settings, nil, nil)
|
||||
if err != nil {
|
||||
t.Fatalf("contributions: %v", err)
|
||||
}
|
||||
for _, c := range given["route"] {
|
||||
p, _ := c.Values["name"].(string)
|
||||
i, _ := c.Values["internal-name"].(string)
|
||||
return p, i
|
||||
}
|
||||
t.Fatal("the module contributed no route")
|
||||
return "", ""
|
||||
}
|
||||
|
||||
// **Nothing said composes both names, exactly as before.** This is the assertion that keeps every
|
||||
// mesh already running identical until an assignment speaks, and it is the one that would break first
|
||||
// if reach were read where it should not be.
|
||||
func TestAnEndpointWithNoReachKeepsBothNames(t *testing.T) {
|
||||
public, internal := namesFor(t, aRoutedWeb(), nil)
|
||||
if public != "app.example.test" || internal != "app.anchor.internal" {
|
||||
t.Fatalf("names are %q and %q, want both composed as before", public, internal)
|
||||
}
|
||||
}
|
||||
|
||||
// An internal endpoint has an internal name and no public one — so the proxy serves it inside, and
|
||||
// the public authority is never asked for a name nobody wanted. This is what "must not be public"
|
||||
// could not say before.
|
||||
func TestAnInternalEndpointHasNoPublicName(t *testing.T) {
|
||||
public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachInternal))
|
||||
if public != "" {
|
||||
t.Fatalf("an internal endpoint composed the public name %q", public)
|
||||
}
|
||||
if internal != "app.anchor.internal" {
|
||||
t.Fatalf("internal name is %q, want app.anchor.internal", internal)
|
||||
}
|
||||
}
|
||||
|
||||
// And the mirror: a public endpoint gets the public name and not the internal one, so the mesh's own
|
||||
// authority is not asked to certify a name the service is not reached by.
|
||||
func TestAPublicEndpointHasNoInternalName(t *testing.T) {
|
||||
public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachPublic))
|
||||
if internal != "" {
|
||||
t.Fatalf("a public endpoint composed the internal name %q", internal)
|
||||
}
|
||||
if public != "app.example.test" {
|
||||
t.Fatalf("public name is %q, want app.example.test", public)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBothComposesBothNames(t *testing.T) {
|
||||
public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachBoth))
|
||||
if public == "" || internal == "" {
|
||||
t.Fatalf("both should compose both names, got %q and %q", public, internal)
|
||||
}
|
||||
}
|
||||
|
||||
// **The filter reads the same value — for an endpoint the proxy does not serve.**
|
||||
//
|
||||
// A routed endpoint's port is how the proxy reaches it and nothing else (ADR 0045): a public service
|
||||
// listens from the mesh, only the proxy reaches it, and it is exposed by name. So on a routed
|
||||
// endpoint the reach asks for a name and the port keeps what the manifest said.
|
||||
func TestAnUnroutedEndpointsPortFollowsItsReach(t *testing.T) {
|
||||
// The same module with its route taken away: now the port is the only way in, so reach governs it.
|
||||
bare := aRoutedWeb()
|
||||
bare.Contributes = nil
|
||||
|
||||
for _, c := range []struct{ reach, want string }{
|
||||
{ReachInternal, FromMesh},
|
||||
{ReachPublic, FromEverywhere},
|
||||
{ReachBoth, FromEverywhere},
|
||||
{ReachMachine, FromMachine},
|
||||
} {
|
||||
r := Resolution{Node: "anchor", Modules: []Manifest{bare}}
|
||||
rules, err := r.Rules(Rendering{Settings: reachSet(c.reach)})
|
||||
if err != nil {
|
||||
t.Fatalf("%s: rules: %v", c.reach, err)
|
||||
}
|
||||
found := false
|
||||
for _, rule := range rules {
|
||||
if rule.Port == 3000 {
|
||||
found = true
|
||||
if rule.From != c.want {
|
||||
t.Fatalf("reach %q made the filter say %q, want %q", c.reach, rule.From, c.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Fatalf("reach %q produced no rule for the port", c.reach)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **A public name does not open the machine's port**, which is the case that found this.
|
||||
//
|
||||
// A module whose routed name must be public and whose machine-side port must not be had no way to say
|
||||
// so while one value drove both. Under one value it could not be expressed; the port would reopen.
|
||||
func TestAPublicNameLeavesARoutedPortAsTheManifestSaid(t *testing.T) {
|
||||
r := Resolution{Node: "anchor", Modules: []Manifest{aRoutedWeb()},
|
||||
PublicDomain: "example.test", At: "anchor.internal"}
|
||||
rules, err := r.Rules(Rendering{Settings: reachSet(ReachPublic)})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, rule := range rules {
|
||||
if rule.Port == 3000 && rule.From != FromMesh {
|
||||
t.Fatalf("a public reach opened a routed port to %q; the proxy is how it is reached",
|
||||
rule.From)
|
||||
}
|
||||
}
|
||||
// And the name it asked for is there, so the reach was not simply ignored.
|
||||
public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachPublic))
|
||||
if public != "app.example.test" || internal != "" {
|
||||
t.Fatalf("names are %q and %q, want the public one only", public, internal)
|
||||
}
|
||||
}
|
||||
|
||||
// A reach for a port the module does not listen on reaches nothing, and is refused where it is
|
||||
// written rather than accepted and ignored.
|
||||
func TestAReachForAPortTheModuleDoesNotListenOnIsRefused(t *testing.T) {
|
||||
_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor",
|
||||
Values: map[string]any{ReachSetting: map[string]any{"9999": ReachInternal}}}})
|
||||
if err == nil || !strings.Contains(err.Error(), "reaches nothing") {
|
||||
t.Fatalf("a reach naming an undeclared port was accepted: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// A value that is not a reach is refused, and the refusal names the four so a reader is one edit from
|
||||
// right. "mesh" is the tempting wrong answer, because that is the filter's word for nearly the same
|
||||
// thing.
|
||||
func TestAValueThatIsNotAReachIsRefused(t *testing.T) {
|
||||
for _, wrong := range []string{"mesh", "anywhere", "private", "true"} {
|
||||
_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor",
|
||||
Values: map[string]any{ReachSetting: map[string]any{"3000": wrong}}}})
|
||||
if err == nil || !strings.Contains(err.Error(), "a reach is") {
|
||||
t.Fatalf("%q was accepted as a reach: %v", wrong, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **A port that says both reach and expose is refused.** They say the same thing in different words,
|
||||
// and accepting both would have the filter follow one while the names followed the other — the
|
||||
// disagreement ADR 0138 exists to remove, reintroduced by the migration away from the older word.
|
||||
func TestReachAndExposeForOnePortAreRefused(t *testing.T) {
|
||||
_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor", Values: map[string]any{
|
||||
ReachSetting: map[string]any{"3000": ReachInternal},
|
||||
ExposeSetting: map[string]any{"3000": FromEverywhere},
|
||||
}}})
|
||||
if err == nil || !strings.Contains(err.Error(), "same thing in different") {
|
||||
t.Fatalf("a port set both ways was accepted: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// A path-level refusal carries no port: it is a rule about a name, not an endpoint, and it inherits
|
||||
// whatever that name turned out to be. Narrowing the endpoint must not silently drop it.
|
||||
func TestARuleWithNoPortIsLeftAlone(t *testing.T) {
|
||||
m := aRoutedWeb()
|
||||
m.ContributesMany = map[string]map[string]map[string]any{
|
||||
"route": {"refused": {"label": "app", "path": "/internal", "deny": true}},
|
||||
}
|
||||
r := Resolution{Node: "anchor", Modules: []Manifest{m},
|
||||
PublicDomain: "example.test", At: "anchor.internal"}
|
||||
given, err := r.contributions(reachSet(ReachInternal), nil, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var sawDeny bool
|
||||
for _, c := range given["route"] {
|
||||
if deny, _ := c.Values["deny"].(bool); deny {
|
||||
sawDeny = true
|
||||
// It keeps both, because it named no endpoint to be narrowed by.
|
||||
if c.Values["name"] == nil || c.Values["internal-name"] == nil {
|
||||
t.Fatalf("the path rule lost a name it shadows: %v", c.Values)
|
||||
}
|
||||
}
|
||||
}
|
||||
if !sawDeny {
|
||||
t.Fatal("the path rule was dropped")
|
||||
}
|
||||
}
|
||||
@@ -186,12 +186,6 @@ func UnusedSettings(m Manifest, layers []Layer) []string {
|
||||
if key == PortsSetting {
|
||||
continue
|
||||
}
|
||||
// `reach` says how far one of this module's endpoints reaches (novox/hq ADR 0138) — the
|
||||
// filter's source, which names are composed, and therefore which authority certifies
|
||||
// them. Validated in Reaches, so not stray.
|
||||
if key == ReachSetting && len(m.Listens) > 0 {
|
||||
continue
|
||||
}
|
||||
unused = append(unused, fmt.Sprintf(
|
||||
"%s sets %q, and %s has no file or contribution to merge it into",
|
||||
layer.From, key, m.Module))
|
||||
|
||||
Reference in New Issue
Block a user