Compare commits

...
20 Commits
Author SHA1 Message Date
mesh-tools e3fff86f1a Merge pull request 'The artifact registry takes a publish whose reservation names no digest yet, and refuses a version it holds at another digest (H-A-387, H-A-393)' (#734) from fix/47-H1-registry-takes-unreserved into main 2026-11-21 23:24:04 +00:00
jschoubben 7765947476 The artifact registry refuses a held version published at another digest (H-A-393)
While the reserved digest is still empty, a second publish of the same
version with another digest passed the reservation check and the store's
Put moved the version's tag. Publish now refuses it in its held branch,
before the reservation is asked, naming both digests, with the publish's
finding and refused said as any refusal; the same digest is taken as before.
The store's Held answers the digest it holds at the version when it differs.

Builds: design 47 H H-A-393, design 47 G A-490j
2026-11-22 00:18:20 +01:00
jschoubben 69940d1019 The artifact registry takes a publish whose reservation names no digest yet (H-A-387)
The builder records a build's digests only at its end, while the Go build
module publishes during the build step with the reserved version (H-A-373),
so the distribution holder's strict digest check refused every archive-only
publish with "reserved ... for another digest". Recorded now takes an
artifact whose reserved digest is empty, as A-490j decided for every holder,
still refuses a different recorded digest, and its refusal names the case:
the digest reserved and the one published, or no reservation of the version.

Builds: design 47 H H-A-387, design 47 G A-490j
2026-11-22 00:14:30 +01:00
mesh-tools 7030e1420c Merge pull request 'The Go build module fetches an archive-only lane of a module without Go code; every publish of the Go and Node build modules names the ask's version (H-A-371, H-A-372, H-A-373)' (#733) from fix/47-H1-go-fetch-archive-only into main 2026-11-21 22:49:52 +00:00
jschoubben b5c05b326a Go build module: a bundle's and an archive's publish carry the version the ask reserved
Every bundle and archive was published with an empty version, a by-digest
publish, so the builder marked none against its reservation: the same kind
as the Node build module's bundles.

Builds: design 47 H H-A-373
2026-11-21 23:45:30 +01:00
jschoubben ebf4d9896b Node build module: a bundle's publish carries the version the ask reserved
Every bundle was published with an empty version, a by-digest publish, so
the builder never saw package-published and the bundle was not marked
against its reservation.

Builds: design 47 H H-A-372
2026-11-21 23:38:37 +01:00
jschoubben 02371b32de Go build module: a module directory that chooses no Go module is an empty scope
The builder sends a module's directory with every lane, and an archive is
packed by the Go build seat, so the fetch's refusal of a directory without
go.mod left every archive-only module without Go code unbuildable. Such a
directory is now an empty scope (the empty scope file written); a Go bundle
or package without go.mod still fails at its build step, naming it.

Builds: design 47 H H-A-371
2026-11-21 23:37:51 +01:00
mesh-tools 32e1ed6c55 Merge pull request 'The Node build module's integration tests supply the SDK the skipped fetch would place (design 47 G §571)' (#732) from fix/47-H1-build-node-tests-under-load into main 2026-11-21 21:44:31 +00:00
mesh-tools d7b23f50b4 Merge pull request 'Packet filter control verbs: the nftables holder serves the verbs, keeps allowances in its state and arms expiries (ADR 0683)' (#731) from feat/packet-filter-allow into main 2026-11-21 21:36:38 +00:00
jschoubben 6527ebd077 mesh-build-node: the real-toolchain tests' fixture holds the SDK where the fetch places it
Since the toolchain lock pins no SDK (design 47 G §571), only the fetch puts
@novox/mesh-sdk in a module's node_modules. The three tests that build with
the real tsc and esbuild skip the fetch, so they read the SDK from an older
installed toolchain that still carried one. Once a build node installed the
current lock (shanks 19:26, then g14), they failed with TS2307 (main.137,
main.155). The fixture now lays a minimal SDK of its own where the fetch
would, so the tests no longer depend on which toolchains a node still keeps.

Builds: design 47 G §571
2026-11-21 22:25:38 +01:00
jschoubben 31abcad907 nftables: test that a start waits for the watch's expiry; refuse a stale node-engine package
Review round 2 (1): the start's wait for the expiries the watch handed over
had no test that failed without it; the start test gains a store whose
deletes wait, and without the wait the key is said expired twice. The note:
a node-engine package naming no verb converged refuses the start loudly
instead of asking seat:node-engine.undefined.

Builds: design 33 control-verbs §10, §11, §14; design 47 H H-A-312
2026-11-21 22:05:47 +01:00
jschoubben f589b5af5c nftables: hold the verbs until the start ends; until with seconds; the seat's own forms
Review round 1 (1)-(3): an until without seconds was accepted, which the
node-engine's RFC 3339 read refuses, withholding every later compose; the
verbs answered before started was said and before the watch's expiries
ended; and the holder kept its own copies of the seat's names, key forms
and value forms, which had drifted from H-A-324. The holder now takes them
from the seat's generated package, the tools' inputs are checked against
its input types, and every seat verb waits for the start's end.

Builds: design 33 control-verbs §2, §3, §11, §12, §14; design 47 H H-A-324, H-A-330
2026-11-21 21:42:45 +01:00
jschoubben 38ea9ce25c nftables: allow names the outward link a kept allowance opens
An allowance with no interface never opens an outward link; one named in
interfaces does, and allow now says so: a kept allowance whose interface is
in the outward links of the converged answer asked for the call answers
with outward, that link. The holder reads no shape of the loaded table to
tell an outward link from the tunnel; the event carries no outward.

Builds: design 33 control-verbs §4, §14; design 47 H H-A-324, H-A-325
2026-11-21 21:19:03 +01:00
jschoubben 09d5758343 nftables: ask converged through the node-engine seat's generated package
The holder's ask of the node-engine's converged takes the seat's name, the
verb's name and the answer's form from the node-engine seat's TypeScript
package, as the holder says its own event through its seat's package.

Builds: design 33 control-verbs §10, §12; design 47 H H-A-316, H-A-321
2026-11-21 21:04:16 +01:00
jschoubben 83482a4513 nftables: allowances per machine, refused unproven or adopted, written in the hand-act log
The security and seams reviews of the packet filter's control verbs: the
allowances state is one bucket per machine whose keys carry the node, so a
holder lists and writes its own node's only; allow and disallow refuse an
unproven caller, an adopted node and a converged that does not answer within
10 s, and are written in the hand-act log before the state is; allow refuses a
port the loaded mesh table accepts from given sources only unless a source is
given, and more than the setting allowances-max; allowed answers none on an
adopted node and asks converged again while none answered; rules marks loaded
only on an equal at and lists loaded allowance comments nobody keeps. The event
is said through the seat's generated package; the claim says it, so emits
stays without it.

Builds: design 33 control-verbs §1-§11, §14; ADR 0683; design 47 H H-A-314 (3), (5), (6), H-A-315 (1)-(3), (5), (7), H-A-316, H-A-317, H-A-318, H-A-319
2026-11-21 20:52:34 +01:00
jschoubben 7bd1e74086 nftables: serve allow, disallow and allowed, keeping allowances as its own state
The operator, 2026-11-21 20:35: a firewall module has tools to control the
firewall beside the provisioning from declarations. The holder keeps one
allowance per protocol, port and interface in its state allowances, says every
change as allowances-changed, removes an allowance at its until by a timer on
its own state (and every expired one at its start, before started), and rules
marks each allowance loaded by its comment in the mesh's table. It writes no
rule: the node-engine renders the allowances.

Builds: ADR 0683; design 33 control-verbs §1-§7, §9; design 47 H H-A-304..310, H-A-312 (2)
2026-11-21 20:40:35 +01:00
mesh-tools 553bfb0ccf Merge pull request 'The forge's whole-seat test ends NOT RUN when its npm tooling is missing (H-A-294)' (#730) from fix/47-H1-gitea-whole-test-not-run into main 2026-11-21 18:30:10 +00:00
mesh-tools 3c27ea7a11 Merge pull request 'The zfs keeper test's race, and a non-root peer whose write is cut is told only root (A-37)' (#729) from fix/47-H1-zfs-keeper-test into main 2026-11-21 18:29:59 +00:00
jschoubben e2571a6468 gitea: the seat git's whole test says NOT RUN where node, npm or its npm packages are missing
The Go integration level fetches the forge module's tree without node_modules and
without network, so TestTheSeatGitWholeOverARealBus failed every pipeline carrying
the forge. It now checks its needs first and skips by name, as the Node build
module's realMachine does; with its needs present it runs whole as before.

Issue 1960 (H1).
Builds: design 47 H H-A-294
2026-11-21 19:26:31 +01:00
jschoubben 94bcc14a82 zfs: the keeper's socket test no longer races, and a refused peer is told so
The test switched the peer's uid in a plain variable the keeper's serving
goroutines read, a data race that fails it under -race; it is an atomic now.
A peer the keeper refuses could also get "broken pipe" instead of the
refusal, when the keeper closed before the request was written: the client
now reads the refusal that waits on the socket. A request larger than the
socket's buffer makes that case happen every time.

Builds: A-37 (only root opens the keeper's socket; a non-root peer is told so); design 47 H section 10 rows 165 and 167 (hq branch design/47-H1-answers-59, 81fa1ee4)
2026-11-21 19:26:14 +01:00
25 changed files with 1214 additions and 88 deletions
@@ -62,8 +62,9 @@ func (b fakeBuilder) Recorded(string, string, string) (bool, string, error) {
}
type fakeStore struct {
has map[string]bool
put []map[string][]byte
has map[string]bool
held map[string]string // name@version to the digest the store holds there
put []map[string][]byte
}
func (s *fakeStore) Has(_, d string) (bool, error) { return s.has[d], nil }
@@ -71,8 +72,17 @@ func (s *fakeStore) Put(t PublishRequest, parts map[string][]byte) (string, erro
s.put = append(s.put, parts)
return t.Name + "@" + t.Digest, nil
}
func (s *fakeStore) Held(string, string, string) (string, bool, error) { return "", false, nil }
func (s *fakeStore) Holds(r PublishRequest) (bool, error) { return s.has[r.Digest], nil }
func (s *fakeStore) Held(name, version, digest string) (string, string, error) {
switch d := s.held[name+"@"+version]; d {
case "":
return "", "", nil
case digest:
return name + "@" + d, "", nil
default:
return "", d, nil
}
}
func (s *fakeStore) Holds(r PublishRequest) (bool, error) { return s.has[r.Digest], nil }
type said struct {
seat, event string
@@ -317,6 +327,16 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
_, err := b.h.Publish(ArtifactSeat, builder, req("t"))
return err
}, "the builder did not reserve it"},
{"a version the store holds at another digest", func(b *bed) error {
b.store.held = map[string]string{"m/program@0.1.4": "sha256:bb"}
r := req("t")
r.Digest = "sha256:aa"
_, err := b.h.Publish(ArtifactSeat, builder, r) // the reservation names no digest yet: the bed's builder says yes
if !b.findings["publish-refused m/program@0.1.4"] || len(b.store.put) != 0 {
return errors.New("not refused loudly, or stored")
}
return err
}, "the store holds m/program@0.1.4 at digest sha256:bb, not sha256:aa"},
{"an image on the artifact seat", func(b *bed) error {
r := req("t")
r.Kind = KindImage
+4 -4
View File
@@ -208,15 +208,15 @@ func (o *OCI) layerSize(t PublishRequest, parts map[string][]byte) (int64, error
}
// Held is the reference of name at version when the store holds digest under it.
func (o *OCI) Held(name, version, digest string) (string, bool, error) {
func (o *OCI) Held(name, version, digest string) (string, string, error) {
d, err := o.Digest(name, version)
if err != nil || d == "" {
return "", false, err
return "", "", err
}
if d != digest {
return "", false, nil
return "", d, nil
}
return name + "@" + d, true, nil
return name + "@" + d, "", nil
}
// Holds is whether the store holds what r's digest names under r's name: an image's manifest by its digest, or a bundle's
@@ -3,13 +3,14 @@ package holder
import (
"encoding/json"
"fmt"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
)
// Reserved is the holder's check of a publish against the builder's reservation (novox/hq design 47 §381, §478, §504): it asks the
// seat mesh-builds' verb reserved with the publish's name and version, a package's name in its ecosystem, and accepts the publish
// only when that version is the one reserved and an artifact of it has the publish's digest. It reads no catalog and a publish gains
// only when that version is the one reserved and an artifact of it has the publish's digest or none recorded yet (A-490j). It reads no catalog and a publish gains
// no field. It is the Builder the holder's Check asks.
type Reserved struct {
// Ask is the runtime's request and reply over the bus (mesh-sdk stdio.Ask).
@@ -31,12 +32,20 @@ func (r Reserved) Recorded(name, version, digest string) (bool, string, error) {
return false, "", fmt.Errorf("%s answered no reservation for %s@%s: %s", Address, name, version, raw)
}
if a.Version != version {
return false, fmt.Sprintf("%s reserved %s for %s, not %s", a.Module, a.Version, name, version), nil
return false, fmt.Sprintf("%s has no reservation of version %s of %s (it reserved %s)", a.Module, version, name, a.Version), nil
}
var reserved []string
for _, art := range a.Artifacts {
if art.Digest == digest {
// An artifact whose build has not recorded its digest yet takes the publish: the builder records a build's digests only when
// the build ends, while the build module publishes during it with the reserved version (design 47 G §369, A-415, A-490j,
// H-A-387). A digest the build then records that differs from what the holder holds fails the build.
if art.Digest == digest || art.Digest == "" {
return true, "", nil
}
reserved = append(reserved, art.Digest)
}
return false, fmt.Sprintf("%s reserved %s@%s for another digest than %s", a.Module, name, version, digest), nil
if len(reserved) == 0 {
return false, fmt.Sprintf("%s reserved %s@%s with no artifact, so no digest takes %s", a.Module, name, version, digest), nil
}
return false, fmt.Sprintf("%s reserved %s@%s for digest %s, not %s", a.Module, name, version, strings.Join(reserved, ", "), digest), nil
}
@@ -19,8 +19,10 @@ func reservedChecksAPublishAgainstTheReservation(t *testing.T) {
}{
{name: "the reserved version and digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:aa"}]}`, ok: true},
{name: "another artifact of it carries the digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:aux"},{"artifact":"mesh-image:image","digest":"sha256:aa"}]}`, ok: true},
{name: "another digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:bb"}]}`, why: "another digest than sha256:aa"},
{name: "another version reserved", answer: `{"module":"mesh-image","version":"0.1.8","artifacts":[]}`, why: "reserved 0.1.8 for registry/mesh-image, not 0.1.7"},
{name: "no digest recorded yet", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image"}]}`, ok: true},
{name: "another digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:bb"}]}`, why: "reserved registry/mesh-image@0.1.7 for digest sha256:bb, not sha256:aa"},
{name: "no artifact reserved", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[]}`, why: "with no artifact, so no digest takes sha256:aa"},
{name: "another version reserved", answer: `{"module":"mesh-image","version":"0.1.8","artifacts":[]}`, why: "no reservation of version 0.1.7 of registry/mesh-image (it reserved 0.1.8)"},
{name: "the builder refused the name", err: errors.New("no entry carries registry/mesh-image"), why: "no entry carries registry/mesh-image"},
{name: "an answer that is none", answer: `{"error":"x"}`, why: "answered no reservation"},
} {
@@ -141,8 +141,9 @@ type Store interface {
// Put stores a publish's parts under its name and version and answers the reference's path (SeatReference).
Put(r PublishRequest, parts map[string][]byte) (reference string, err error)
// Held is the reference's path of name at version when the store already holds digest under it: a rebuild of a held
// fingerprint answers it and stores nothing.
Held(name, version, digest string) (reference string, ok bool, err error)
// fingerprint answers it and stores nothing. When the store holds the version at another digest, other names that digest
// and reference is empty; neither is set when the store holds no such version.
Held(name, version, digest string) (reference, other string, err error)
// Holds says whether the store holds what a publish's digest names under its name: an image's manifest, or a bundle's or
// an archive's blob. The store is the artifact store (A-50): `artifact-store://<name>/blobs/<digest>` is that blob.
Holds(r PublishRequest) (bool, error)
@@ -266,15 +267,19 @@ func (h *Holder) Publish(seat, caller string, r PublishRequest) (PublishAnswer,
}
// A rebuild of a held fingerprint answers the held version and stores nothing.
if r.Version != "" {
var ref string
var ok bool
var ref, other string
err := h.timed("the store's read of what it holds (the program's registry)", func() (err error) {
ref, ok, err = h.Store.Held(r.Name, r.Version, r.Digest)
ref, other, err = h.Store.Held(r.Name, r.Version, r.Digest)
return err
})
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s@%s: %w", r.Name, r.Version, err)
} else if ok {
} else if other != "" {
// A second publish of a held version with another digest is refused before the reservation is asked, as the forge
// holds the first (A-490j, H-A-393): while the reserved digest is still empty it would pass, and the store's Put
// would move the version's tag.
return h.refusePublish(seat, r, fmt.Sprintf("the store holds %s@%s at digest %s, not %s", r.Name, r.Version, other, r.Digest))
} else if ref != "" {
return PublishAnswer{Transfer: r.Transfer, Ended: true}, h.timed("the published event on the seat", func() error {
return h.Say(seat, EventPublished, h.eventOf(seat, r, SeatReference(seat, ref), ""))
})
@@ -298,6 +303,16 @@ func (h *Holder) Publish(seat, caller string, r PublishRequest) (PublishAnswer,
return answerOf(got), nil
}
// refusePublish ends a publish refused before anything is stored: its finding raised, refused said on the seat, the reason
// answered.
func (h *Holder) refusePublish(seat string, r PublishRequest, reason string) (PublishAnswer, error) {
h.Finding("publish-refused", r.Name+"@"+r.Version, reason, true)
if err := h.Say(seat, EventRefused, h.eventOf(seat, r, "", reason)); err != nil {
return PublishAnswer{}, fmt.Errorf("publish: %s, and the refused is not said: %w", reason, err)
}
return PublishAnswer{Transfer: r.Transfer, Ended: true}, errors.New("publish: " + reason)
}
// tagHeld is a publish with a version, a digest and no parts (design 47 G A-417, A-73, A-50): what the store holds of that
// digest under the name (the build's untagged publish, the artifact store's blob) is checked against the builder's reservation
// and tagged with the version, and published is said; when the store holds none of it, the publish is refused as not stored,
@@ -311,13 +326,7 @@ func (h *Holder) tagHeld(seat string, r PublishRequest) (PublishAnswer, error) {
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s of %s: %w", r.Digest, r.Name, err)
}
refuse := func(reason string) (PublishAnswer, error) {
h.Finding("publish-refused", r.Name+"@"+r.Version, reason, true)
if err := h.Say(seat, EventRefused, h.eventOf(seat, r, "", reason)); err != nil {
return PublishAnswer{}, fmt.Errorf("publish: %s, and the refused is not said: %w", reason, err)
}
return PublishAnswer{Transfer: r.Transfer, Ended: true}, errors.New("publish: " + reason)
}
refuse := func(reason string) (PublishAnswer, error) { return h.refusePublish(seat, r, reason) }
if !held {
return refuse(fmt.Sprintf("not stored: the store holds no %s of %s, so version %s names nothing", r.Digest, r.Name, r.Version))
}
@@ -344,14 +344,27 @@ func numbers(v any) []float64 {
return out
}
// needTheModulesPackages ends the test NOT RUN, never failed, where what it builds and runs with is missing: node and npm
// on the PATH and the module's installed SDK package under node_modules. The Go integration level is given the tree
// without its npm packages and no network (issue 1960, H-A-294), as the Node build module's realMachine skips by name.
func needTheModulesPackages(t *testing.T, dir string) {
t.Helper()
for _, p := range []string{"node", "npm"} {
if _, err := exec.LookPath(p); err != nil {
t.Skipf("NOT RUN: no %s installed where this check runs; proven in a working copy of the module after npm install", p)
}
}
if _, err := os.Stat(filepath.Join(dir, "node_modules", "@novox", "mesh-sdk")); err != nil {
t.Skipf("NOT RUN: the forge module's npm packages are not installed in %s (%v); proven in a working copy of the module after npm install", dir, err)
}
}
func TestTheSeatGitWholeOverARealBus(t *testing.T) {
dir, err := filepath.Abs(filepath.Join("..", ".."))
if err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(dir, "node_modules", "@novox", "mesh-sdk")); err != nil {
t.Fatalf("the forge module's packages are not installed in %s (npm install first): %v", dir, err)
}
needTheModulesPackages(t, dir)
build := exec.Command("npm", "run", "build")
build.Dir = dir
if out, err := build.CombinedOutput(); err != nil {
@@ -46,9 +46,9 @@ func (m *Module) httpClient() *http.Client {
// buildArchive packs one archive artifact of the module in dir: a pinned file when it names a url, else the directory
// `from` of the module's tree.
func (m *Module) buildArchive(ctx context.Context, workspace, module, name, dir string, art catalogue.Artifact, keep *sdkstep.KeptFor) (any, error) {
func (m *Module) buildArchive(ctx context.Context, workspace, module, name, dir string, art catalogue.Artifact, version string, keep *sdkstep.KeptFor) (any, error) {
if art.URL != "" {
return m.pinnedArchive(ctx, workspace, module, name, art, keep)
return m.pinnedArchive(ctx, workspace, module, name, art, version, keep)
}
from := strings.Trim(path.Clean("/"+filepath.ToSlash(art.From)), "/")
if strings.TrimSpace(art.From) == "" {
@@ -80,12 +80,12 @@ func (m *Module) buildArchive(ctx context.Context, workspace, module, name, dir
if !within(realDir, realRoot) {
return nil, fmt.Errorf("the archive %s is taken from %q, which lies outside the module: it resolves to %s, and the module is %s", art.Name, art.From, realRoot, realDir)
}
return m.packInto(ctx, workspace, module, name, art.Name, "archive", root, keep)
return m.packInto(ctx, workspace, module, name, art.Name, "archive", version, root, keep)
}
// pinnedArchive fetches the file an artifact is pinned to, checks it against the pin, lays it out as the artifact says
// (kept whole as `file`, or unpacked from `within`) and packs it.
func (m *Module) pinnedArchive(ctx context.Context, workspace, module, name string, art catalogue.Artifact, keep *sdkstep.KeptFor) (any, error) {
func (m *Module) pinnedArchive(ctx context.Context, workspace, module, name string, art catalogue.Artifact, version string, keep *sdkstep.KeptFor) (any, error) {
file, err := m.pinnedFile(ctx, workspace, art)
if err != nil {
return nil, fmt.Errorf("%s: %w", art.Name, err)
@@ -114,7 +114,7 @@ func (m *Module) pinnedArchive(ctx context.Context, workspace, module, name stri
} else if err := unpackUpstream(file, laid, art.Within); err != nil {
return nil, fmt.Errorf("%s: %s (%s): %w", art.Name, art.URL, art.Version, err)
}
return m.packInto(ctx, workspace, module, name, art.Name, "archive", laid, keep)
return m.packInto(ctx, workspace, module, name, art.Name, "archive", version, laid, keep)
}
// pinnedFile is the path of the pinned file in the workspace: kept from an earlier build when its bytes are still the
@@ -6,6 +6,7 @@ import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"io"
"net"
@@ -305,3 +306,66 @@ func TestAnArchiveOfALinkedModuleDirectoryIsRefused(t *testing.T) {
t.Errorf("an archive of outside files was left: %v", entries)
}
}
// H-A-371: an archive-only lane of a module with no Go code fetches (its directory chooses no Go module: an empty
// scope, never a refusal) and packs its archive.
func TestAnArchiveOnlyLaneOfAModuleWithNoGoCodeFetchesAndPacks(t *testing.T) {
files := map[string]string{}
fixture := filepath.Join("testdata", "repos", "archive")
err := filepath.Walk(fixture, func(p string, info os.FileInfo, err error) error {
if err != nil || info.IsDir() {
return err
}
body, err := os.ReadFile(p)
rel, _ := filepath.Rel(fixture, p)
files[strings.TrimSuffix(filepath.ToSlash(rel), ".fixture")] = string(body)
return err
})
if err != nil {
t.Fatal(err)
}
// Another module of the repository holds Go code; the archive module's directory holds none.
f := &fakeStep{gomods: "modules/other/go.mod\n", files: files}
m, states := fetchModule(t, f)
withStore(t, m)
if _, err := fetchTool(t, m)(map[string]any{"repository": "novox/mesh-catalog", "commit": commitSHA, "dir": "modules/demo"}); err != nil {
t.Fatal(err)
}
st := states.waitEnd(t)
if st.State != sdkstep.StepPassed {
t.Fatalf("the fetch ended %s: %s", st.State, st.Reason)
}
var fetched FetchResult
if err := json.Unmarshal(st.Result, &fetched); err != nil {
t.Fatal(err)
}
if len(fetched.Modules) != 0 {
t.Errorf("the fetch chose the Go modules %v, want none", fetched.Modules)
}
if b, err := os.ReadFile(filepath.Join(m.Work, fetched.Workspace, scopeMark)); err != nil || len(b) != 0 {
t.Errorf("the scope beside the tree is %q, %v; want the empty scope", b, err)
}
for _, l := range f.lines() {
if strings.HasPrefix(l, "go ") {
t.Errorf("a fetch that chose no Go module ran %s", l)
}
}
for _, tool := range m.Tools(m.StepTools()) {
if tool.Name == "build_go_build" {
if _, err := tool.Run(map[string]any{"workspace": fetched.Workspace, "module": "modules/demo", "artifact": "files"}); err != nil {
t.Fatal(err)
}
}
}
st = states.waitEnd(t)
if st.State != sdkstep.StepPassed {
t.Fatalf("the build ended %s: %s", st.State, st.Reason)
}
var res BuildResult
if err := json.Unmarshal(st.Result, &res); err != nil {
t.Fatal(err)
}
if res.Artifact != "files" || res.Size == 0 || res.Reference == "" || len(archiveOf(t, res)) != res.Size {
t.Errorf("the archive was not packed and published: %+v", res)
}
}
@@ -129,7 +129,7 @@ func (m *Module) build(ctx context.Context, args map[string]any) (any, error) {
return m.buildGoPackage(ctx, workspace, dir, *art, version, seat)
}
if art.Kind == "archive" {
return m.buildArchive(ctx, workspace, module, manifest.Module, dir, *art, keep)
return m.buildArchive(ctx, workspace, module, manifest.Module, dir, *art, version, keep)
}
if art.Kind != "bundle" || art.Language != "go" {
return nil, fmt.Errorf("the artifact %s of %s is a %s of language %q: this module builds Go bundles and archives", name, manifest.Module, art.Kind, art.Language)
@@ -176,7 +176,7 @@ func (m *Module) build(ctx context.Context, args map[string]any) (any, error) {
if err := m.insideModule(workspace, dir, out); err != nil {
return nil, fmt.Errorf("the output directory of %s: %w", art.Name, err)
}
res, err := m.packInto(ctx, workspace, module, manifest.Module, art.Name, "bundle", out, keep)
res, err := m.packInto(ctx, workspace, module, manifest.Module, art.Name, "bundle", version, out, keep)
if err != nil {
return nil, err
}
@@ -186,16 +186,17 @@ func (m *Module) build(ctx context.Context, args map[string]any) (any, error) {
// packInto packs a directory with mesh-sdk's Pack, as the build agent packs every artifact, and publishes the archive
// on the seat oci-artifact-registry from this process, after the build step ended (design 51 *Publishing*; publish.go):
// a candidate's as a trunk build's, under <module>/<artifact> by its digest, of kind (bundle or archive). The step
// answers the reference; a publish the seat refuses fails the step `not stored:`, unless keep names the build of the
// artifact store's holder, which this node then keeps and answers as kept (keptbuilds.go). The packed bytes never stay on
// the node: they are held in this process until the publish answered (the lead's decision L9).
func (m *Module) packInto(ctx context.Context, workspace, module, name, artifact, kind, root string, keep *sdkstep.KeptFor) (BuildResult, error) {
// a candidate's as a trunk build's, under <module>/<artifact> by its digest and the ask's version (H-A-373), of kind
// (bundle or archive). The step answers the reference; a publish the seat refuses fails the step `not stored:`, unless
// keep names the build of the artifact store's holder, which this node then keeps and answers as kept (keptbuilds.go).
// The packed bytes never stay on the node: they are held in this process until the publish answered (the lead's
// decision L9).
func (m *Module) packInto(ctx context.Context, workspace, module, name, artifact, kind, version, root string, keep *sdkstep.KeptFor) (BuildResult, error) {
archive, digest, err := steprun.Pack(root)
if err != nil {
return BuildResult{}, fmt.Errorf("packing %s: %w", artifact, err)
}
if err := m.publishArchive(ctx, name, artifact, kind, digest, archive); err != nil {
if err := m.publishArchive(ctx, name, artifact, kind, version, digest, archive); err != nil {
if keep == nil {
return BuildResult{}, fmt.Errorf("%s%s: %w", builds.NotStored, artifact, err)
}
@@ -57,10 +57,16 @@ func buildModule(t *testing.T, manifest, content string) (*Module, *keptStates,
}
func runBuild(t *testing.T, m *Module, states *keptStates, artifact string) (BuildResult, sdkstep.Step) {
t.Helper()
return runBuildArgs(t, m, states, map[string]any{"workspace": "ws1", "module": "modules/demo", "artifact": artifact})
}
// runBuildArgs runs the build tool with args, such as an ask's version, and answers what its step ended with.
func runBuildArgs(t *testing.T, m *Module, states *keptStates, args map[string]any) (BuildResult, sdkstep.Step) {
t.Helper()
for _, tool := range m.Tools(m.StepTools()) {
if tool.Name == "build_go_build" {
if _, err := tool.Run(map[string]any{"workspace": "ws1", "module": "modules/demo", "artifact": artifact}); err != nil {
if _, err := tool.Run(args); err != nil {
t.Fatal(err)
}
}
@@ -691,8 +691,8 @@ func cleanDir(dir string) string {
// scopedDirs are the go.mod directories of all that a module directory dir chooses: dir itself and each directory its
// go.mod replaces with a local path, followed through their own replaces (design 47 G, A-447), in order. A directory
// the tree holds no go.mod for is left out. A directory holding no go.mod chooses every go.mod under it, and one that
// chooses no Go module at all is an error naming it (A-447a).
// the tree holds no go.mod for is left out. A directory holding no go.mod chooses every go.mod under it (A-447a), and one that
// chooses no Go module at all is an empty scope (H-A-371).
func scopedDirs(tree, dir string, paths, all []string) ([]string, error) {
have := map[string]bool{}
for _, d := range all {
@@ -752,8 +752,8 @@ func scopedDirs(tree, dir string, paths, all []string) ([]string, error) {
out = append(out, d)
}
}
if len(out) == 0 {
return nil, fmt.Errorf("the module directory %q holds no Go module (no go.mod in it or under it)", dir)
}
// A directory that chooses no Go module (a module with an archive artifact and no Go code) is an empty scope, never
// a refusal: the builder sends its directory with every lane, and its archive is packed here. A Go bundle or package
// whose directory holds no go.mod fails at its build step, naming it (design 47 H, H-A-371).
return out, nil
}
@@ -58,7 +58,7 @@ func TestAFetchAskedWithADirectoryChoosesItsModuleAndWhatItReplacesAlone(t *test
{"seats", []string{"seats/a", "seats/b"}}, // a go.mod per seat, none in seats itself
{".", []string{"."}}, // the root holds a go.mod
{"rootless/x", []string{"rootless/x/go"}}, // Go code lies in go/
{"modules/none", nil}, // chooses no Go module: an error naming it
{"modules/none", []string{}}, // chooses no Go module: an empty scope (H-A-371)
} {
tree := t.TempDir()
for d, body := range mods {
@@ -70,12 +70,6 @@ func TestAFetchAskedWithADirectoryChoosesItsModuleAndWhatItReplacesAlone(t *test
}
}
got, err := scopedDirs(tree, cleanDir(c.dir), nil, all)
if c.want == nil {
if err == nil || !strings.Contains(err.Error(), c.dir) {
t.Errorf("dir %q chose %v, %v; want an error naming it", c.dir, got, err)
}
continue
}
if err != nil || !reflect.DeepEqual(got, c.want) {
t.Errorf("dir %q chooses %v, %v; want %v", c.dir, got, err, c.want)
}
@@ -23,9 +23,10 @@ func transferName(module, artifact, digest string) string {
return steprun.TransferName(module, artifact, digest)
}
// publishArchive publishes body, of digest, as <module>/<artifact> of kind (bundle or archive) on the artifact seat.
func (m *Module) publishArchive(ctx context.Context, module, artifact, kind, digest string, body []byte) error {
return m.publishOn(ctx, ArtifactSeat, module+"/"+artifact, kind, "", digest, transferName(module, artifact, digest), body)
// publishArchive publishes body, of digest, as <module>/<artifact> of kind (bundle or archive) on the artifact seat, under
// the version the ask reserved, so the builder marks it against its reservation (design 47 H, H-A-373).
func (m *Module) publishArchive(ctx context.Context, module, artifact, kind, version, digest string, body []byte) error {
return m.publishOn(ctx, ArtifactSeat, module+"/"+artifact, kind, version, digest, transferName(module, artifact, digest), body)
}
// publishOn publishes body through steprun.PublishOne: through Call when a test set it, else the runtime's request
@@ -102,11 +102,12 @@ func archiveOf(t *testing.T, res BuildResult) []byte {
}
// 1587-S2 (ADR 0498 §1): a done build answers a reference of the stated form whose tail is the build's digest, and the
// store holds the archive there; a bundle and an archive alike.
// store holds the archive there; a bundle and an archive alike. Each publish names the version the ask reserved, so the
// builder marks it against its reservation (design 47 H, H-A-373).
func TestADoneBuildAnswersTheReferenceOfTheArchiveItPushed(t *testing.T) {
m, states, _ := buildModule(t, manifestWith(goBundle), "the program")
store := withStore(t, m)
res, st := runBuild(t, m, states, "tools")
res, st := runBuildArgs(t, m, states, map[string]any{"workspace": "ws1", "module": "modules/demo", "artifact": "tools", "version": "1.4.3"})
if st.State != sdkstep.StepPassed {
t.Fatalf("the step ended %s: %s", st.State, st.Reason)
}
@@ -116,12 +117,18 @@ func TestADoneBuildAnswersTheReferenceOfTheArchiveItPushed(t *testing.T) {
if store.blobs["demo/tools@"+res.Digest] == nil || store.asked[0] != "seat:oci-artifact-registry.publish" {
t.Errorf("the seat was asked %v and holds %d blobs, not demo/tools@%s", store.asked, len(store.blobs), res.Digest)
}
if len(store.published) != 1 || store.published[0].Version != "1.4.3" {
t.Errorf("the bundle was published as %+v, want the ask's version 1.4.3", store.published)
}
a, states2, _ := archiveModule(t, "")
withStore(t, a)
arch, st := runBuild(t, a, states2, "files")
astore := withStore(t, a)
arch, st := runBuildArgs(t, a, states2, map[string]any{"workspace": "ws1", "module": "modules/demo", "artifact": "files", "version": "1.4.3"})
if st.State != sdkstep.StepPassed || arch.Reference != "oci-artifact-registry/demo/files@"+arch.Digest {
t.Errorf("the archive artifact: %s %q, reference %q", st.State, st.Reason, arch.Reference)
}
if len(astore.published) != 1 || astore.published[0].Version != "1.4.3" {
t.Errorf("the archive was published as %+v, want the ask's version 1.4.3", astore.published)
}
}
// 1587-S3 (ADR 0498 §2), CAT-BG1: a publish the seat's holder refuses fails the step `not stored: <artifact>: <the
@@ -198,8 +198,9 @@ func (m *Module) build(ctx context.Context, args map[string]any) (any, error) {
return nil, fmt.Errorf("packing %s: %w", a.Name, err)
}
// Published from this process once the build ended, a candidate's as a trunk build's (ADR 0498 §1 §2; CAT-BN3): the
// step answers the seat's reference, or fails not stored. The packed bytes are never written to the node (L9).
if err := m.publishOn(ctx, steprun.ArtifactSeat, a.module+"/"+a.Name, "bundle", "", digest, archive); err != nil {
// step answers the seat's reference, or fails not stored. The packed bytes are never written to the node (L9). The
// publish carries the version the ask reserved, so the builder marks the bundle against its reservation (H-A-372).
if err := m.publishOn(ctx, steprun.ArtifactSeat, a.module+"/"+a.Name, "bundle", version, digest, archive); err != nil {
return nil, fmt.Errorf("%s%s: %w", builds.NotStored, a.Name, err)
}
files := []string{}
@@ -58,17 +58,33 @@ func realMachine(t *testing.T) (*Module, string) {
t.Fatalf("the toolchain copied from %s cannot be used: %v", from, err)
}
for _, id := range []string{"w1", "w2", "w3"} {
for p, body := range map[string]string{
files := map[string]string{
"modules/m/module.json": `{"module":"m","build":{"artifacts":[{"name":"tools","kind":"bundle","language":"typescript","entrypoints":["tools/index.js"]}]}}`,
"modules/m/package.json": `{"name":"m","type":"module","scripts":{"test":"node -e \"process.exit(0)\""}}`,
"modules/m/tools/index.ts": "import { serveRegisteredOverStdio } from \"@novox/mesh-sdk/stdio\";\nexport const f: () => Promise<void> = serveRegisteredOverStdio as () => Promise<void>;\n",
} {
}
for p, body := range fetchedSDK {
files["modules/m/node_modules/@novox/mesh-sdk/"+p] = body
}
for p, body := range files {
write(t, filepath.Join(work, id, "tree", filepath.FromSlash(p)), body, 0o644)
}
}
return m, work
}
// fetchedSDK is the SDK the fixture's workspaces hold where the fetch step places it, in the module's node_modules
// (fetch.go, placeSDK: the latest published release, ADR 0573 §2; design 47 G §571), made here because the integration
// level has no registry to fetch it from. The toolchain's lock names no SDK since §571, so a fixture that leaves it out
// reads one only from a toolchain installed before (main.137 and main.155: TS2307 once a build node installed the
// lock). It holds the one export the fixture and the launchers import.
var fetchedSDK = map[string]string{
"package.json": `{"name":"@novox/mesh-sdk","version":"9.9.9","type":"module",` +
`"exports":{"./stdio":{"types":"./dist/stdio.d.ts","default":"./dist/stdio.js"}}}`,
"dist/stdio.js": "export async function serveRegisteredOverStdio() {}\n",
"dist/stdio.d.ts": "export declare function serveRegisteredOverStdio(): Promise<void>;\n",
}
// 1490/AC2, 1491 and issue 1869, in one test so the toolchain is copied once: the real type-check and test script of the
// fixture pass the unit level; a package whose test imports its own build output (as mesh-sdk's do) passes the unit level,
// the test step emitting it with the real tsc, shut off, before the test script runs; and the fixture TypeScript bundle
@@ -94,11 +94,14 @@ func archiveOf(t *testing.T, r BuildResult) []byte {
}
// 1587-S6 (ADR 0498 §1; CAT-BN3): a done bundle is published through oci-artifact-registry and answers the seat's
// reference of its archive, under the manifest's module.
// reference of its archive, under the manifest's module. Its publish names the version the ask reserved, so the bundle
// is marked against its reservation (design 47 H, H-A-372).
func TestADoneBundleAnswersTheReferenceOfTheArchiveItPushed(t *testing.T) {
m, _, _ := builtMachine(t, ``)
store := withStore(t, m)
out, err := m.build(context.Background(), buildArgs())
args := buildArgs()
args["version"] = "1.4.3"
out, err := m.build(context.Background(), args)
if err != nil {
t.Fatal(err)
}
@@ -109,6 +112,9 @@ func TestADoneBundleAnswersTheReferenceOfTheArchiveItPushed(t *testing.T) {
if store.blobs["m/tools@"+r.Digest] == nil || len(store.seats) != 1 || store.seats[0] != steprun.ArtifactSeat {
t.Errorf("the holder holds %d files through %v, not m/tools@%s through %s", len(store.blobs), store.seats, r.Digest, steprun.ArtifactSeat)
}
if len(store.published) != 1 || store.published[0].Version != "1.4.3" {
t.Errorf("the bundle was published as %+v, want the ask's version 1.4.3", store.published)
}
}
// 1587-S7 and S8 (ADR 0498 §2, the lead's decision L9): a publish the holder refuses fails the step `not stored:
+464
View File
@@ -0,0 +1,464 @@
// The operator's allowances (ADR 0683; design 33 control-verbs): a port opened by hand on this machine, beside the
// ports derived from the modules' listens. An allowance is this module's own state on the bus, one key per protocol,
// port and interface (allow.<protocol>.<port>[.<interface>]), kept one bucket per machine under its node's keys
// (<node>.allow.…, H-A-317), so a holder reads and writes its own node's only; the node-engine asks `allowed` at every compose of a
// converged node's filter and renders it into the inet mesh table's input chain (design 08 control-verbs), so this
// code writes no rule. Every change is said as the seat's event allowances-changed, which the node-engine hears to
// compose the filter again; at its until an allowance is removed by a timer this module keeps per key from watching
// its own state, said and journalled, so no expired entry is kept or answered.
import { isIP } from "node:net";
import type { ConvergedAnswer } from "@novox/mesh-contracts-node-engine";
import {
allowancesByNodeAllowProtocolPortInterfaceKey, allowancesByNodeAllowProtocolPortKey,
parseAllowancesByNodeAllowProtocolPortInterfaceKey, parseAllowancesByNodeAllowProtocolPortKey, states,
type Allowance, type AllowanceValue, type AllowancesChanged, type Kept,
} from "@novox/mesh-connectivity-contracts-node-packet-filter";
// The seat's names, key forms and value forms are its generated package's (design 33 control-verbs §2, §7, §12): this
// module writes no copy of them.
export type { Allowance, AllowanceValue, AllowancesChanged, Kept };
/** The state the allowances are kept in, as the seat's definition names it (§7). */
export const STATE = states.allowances;
/** The most allowances one node keeps when the setting allowances-max says none (§3, H-A-314 (5)). */
export const MOST = 100;
/** How long the holder waits for the node-engine's converged (§10; a value, H-A-330). */
export const CONVERGED_BOUND_MS = 10_000;
/** The caller of a call the runtime named no caller for (the SDK's callers.UNPROVEN). */
export const UNPROVEN = "unproven";
type Protocol = AllowanceValue["protocol"];
/** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316, H-A-321, H-A-325). */
export type Convergence = ConvergedAnswer;
/** One act by hand, as the seat mesh-hand-acts' hand-act takes it (ADR 0565 §10): the SDK's views.HandAct. */
export interface HandAct {
what: string;
why: string;
cause: string;
verb: string;
}
/** What the holder asks beside its state: the node's convergence, the hand-act log and its setting allowances-max. */
export interface Asks {
converged: () => Promise<Convergence>;
handAct: (act: HandAct) => Promise<void>;
most: () => Promise<number>;
/** The mesh's table as loaded (`nft list table inet mesh`). */
meshTable: () => Promise<string>;
}
/** What the allowances need of the module's state: the SDK's `state()` serves it, keys from a watch of the node's own. */
export interface Store {
get(key: string): Promise<{ value: AllowanceValue } | null>;
put(key: string, value: AllowanceValue): Promise<number>;
delete(key: string): Promise<void>;
keys(): Promise<string[]>;
}
/** One change of the state as its watch hands it over: the SDK's `StateChange`. */
export interface Watched {
key: string;
op: "put" | "delete";
value?: AllowanceValue;
}
/** Says the event. */
export type Say = (body: AllowancesChanged) => Promise<void>;
/** Runs `fire` after `ms` milliseconds, answering how to cancel it: `setTimeout` on the machine, a fake in tests. */
export type Schedule = (ms: number, fire: () => void) => () => void;
/** The longest one timer waits (Node's setTimeout holds 2^31-1 ms); a later until is waited for in steps. */
export const LONGEST_WAIT_MS = 2 ** 31 - 1;
export const timers: Schedule = (ms, fire) => {
const t = setTimeout(fire, ms);
return () => clearTimeout(t);
};
/** The state's key of an allowance on node, in the seat's key forms (§7, H-A-317): <node>.allow.<protocol>.<port>, and
* .<interface> when it names one. */
function stateKeyOf(node: string, protocol: Protocol, port: number, iface?: string): string {
return iface
? allowancesByNodeAllowProtocolPortInterfaceKey(node, protocol, String(port), iface)
: allowancesByNodeAllowProtocolPortKey(node, protocol, String(port));
}
/** An allowance's key in every answer, the event and the rule's comment: its state's key without the node (§7). */
export function keyOf(protocol: Protocol, port: number, iface?: string): string {
return stateKeyOf("", protocol, port, iface).slice(1);
}
const IFACE = /^[A-Za-z0-9_.-]{1,15}$/;
function refuse(argument: string, why: string): never {
throw new Error(`${argument}: ${why}; nothing is written`);
}
function only(args: Record<string, unknown>, known: string[]): void {
for (const k of Object.keys(args)) {
if (!known.includes(k)) refuse(k, `not an argument of this verb (${known.join(", ") || "none"})`);
}
}
function portOf(v: unknown): number {
if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > 65535) {
refuse("port", `${JSON.stringify(v)} is not an integer from 1 to 65535`);
}
return v;
}
function protocolOf(v: unknown): Protocol {
if (v === undefined) return "tcp";
if (v === "tcp" || v === "udp") return v;
refuse("protocol", `${JSON.stringify(v)} is neither tcp (the default) nor udp`);
}
function interfacesOf(v: unknown): (string | undefined)[] {
if (v === undefined) return [undefined];
if (!Array.isArray(v)) refuse("interfaces", "a list of interface names");
if (v.length === 0) return [undefined];
for (const i of v) {
if (typeof i !== "string" || !IFACE.test(i)) {
refuse("interfaces", `${JSON.stringify(i)} is not 1 to 15 letters, digits, _ . or -`);
}
}
return [...new Set(v as string[])];
}
function sourceOf(v: unknown): string | undefined {
if (v === undefined) return undefined;
const s = typeof v === "string" ? v : "";
const [addr, bits, more] = s.split("/");
const family = isIP(addr);
const max = family === 4 ? 32 : 128;
if (family === 0 || more !== undefined || (bits !== undefined && !(/^\d+$/.test(bits) && Number(bits) <= max))) {
refuse("source", `${JSON.stringify(v)} is not one IPv4 or IPv6 CIDR`);
}
return s;
}
function untilOf(v: unknown, now: Date): string | undefined {
if (v === undefined) return undefined;
const s = typeof v === "string" ? v : "";
const t = Date.parse(s);
// A full RFC 3339 time, seconds included: the node-engine reads it with Go's time.RFC3339, which refuses a time
// without them, and would withhold every later compose of the filter (§2).
if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(Z|[+-]\d\d:\d\d)$/.test(s) || Number.isNaN(t)) {
refuse("until", `${JSON.stringify(v)} is not an RFC 3339 time with seconds, such as 2026-11-22T08:00:00Z`);
}
if (t <= now.getTime()) refuse("until", `${s} is not in the future`);
return s;
}
function whyOf(v: unknown): string {
if (typeof v !== "string" || v.length < 1 || v.length > 500) refuse("why", "required, 1 to 500 characters");
return v;
}
function answered(key: string, value: AllowanceValue): Allowance {
return { key, ...value };
}
export class Allowances {
private readonly pending = new Map<string, () => void>();
private readonly store: Store;
private readonly node: string;
private readonly say: Say;
private readonly now: () => Date;
private readonly schedule: Schedule;
private readonly journal: (line: string) => void;
private readonly asks: Asks;
/** The last answer of converged; undefined while none answered. */
private convergence: Convergence | undefined;
/** The expiries running now (track). */
private readonly expiring = new Set<Promise<boolean>>();
constructor(
store: Store,
node: string,
say: Say,
asks: Asks,
now: () => Date = () => new Date(),
schedule: Schedule = timers,
journal: (line: string) => void = (line) => console.log(`[nftables] ${line}`),
) {
this.store = store;
this.node = node;
this.say = say;
this.asks = asks;
this.now = now;
this.schedule = schedule;
this.journal = journal;
}
/** The state's key of an allowance's key: under this node's (H-A-317). */
private stored(key: string): string {
return `${this.node}.${key}`;
}
/** The allowance's key of a state's key of this node, or undefined for another node's or another form. */
private own(stateKey: string): string | undefined {
const parts = parseAllowancesByNodeAllowProtocolPortInterfaceKey(stateKey) ?? parseAllowancesByNodeAllowProtocolPortKey(stateKey);
return parts?.node === this.node ? stateKey.slice(this.node.length + 1) : undefined;
}
/** Ask converged, bound 10 s, keeping its answer; refused, naming why, when it does not answer (§10). */
private async askConverged(verb: string): Promise<Convergence> {
let stop: () => void = () => {};
const late = new Promise<never>((_, no) => {
stop = this.schedule(CONVERGED_BOUND_MS, () => no(new Error(`no answer within ${CONVERGED_BOUND_MS / 1000} s`)));
});
try {
const c = await Promise.race([this.asks.converged(), late]);
if (c?.state !== "adopted" && c?.state !== "converged") throw new Error(`it answered no convergence state (${JSON.stringify(c)})`);
this.convergence = c;
return c;
} catch (err) {
throw new Error(`${verb}: refused: the node-engine's converged did not answer (${err instanceof Error ? err.message : String(err)}), ` +
"and the holder never assumes the node converged; nothing is written");
} finally {
stop();
}
}
private refuseAdopted(verb: string, c: Convergence): void {
if (c.state !== "adopted") return;
const about = [c.found ? `the found firewall ${c.found}` : "", c.since ? `since ${c.since}` : ""].filter(Boolean).join(", ");
throw new Error(`${verb}: refused: this node is adopted${about ? ` (${about})` : ""}, and the mesh speaks the found firewall's terms: ` +
"no allowance is kept on an adopted node; nothing is written");
}
/** The caller as the runtime proved it; an unproven one is refused (§3, H-A-315 (3)). */
private proven(verb: string, by: string): void {
if (!by || by === UNPROVEN) throw new Error(`${verb}: refused: the request carries no caller the tool runner proved; nothing is written`);
}
/** Every allowance kept for this node, by its key, sorted. */
private async ownKeys(): Promise<string[]> {
return (await this.store.keys()).map((k) => this.own(k)).filter((k): k is string => k !== undefined).sort();
}
/** Said once each time the holder starts serving the seat, with every allowance (§8): converged asked first, every
* key past its until removed first (§11). */
async started(): Promise<void> {
try {
await this.askConverged("start");
} catch (err) {
this.journal(`${err instanceof Error ? err.message : String(err)}; allowed asks it again`);
}
// Every expiry the watch handed over ends before started is said (§11).
await Promise.all([...this.expiring]);
const allowances = await this.kept();
await this.say({ node: this.node, change: "started", allowances: this.convergence?.state === "adopted" ? [] : allowances, at: this.now().toISOString() });
}
/** One change of the module's own state, from its watch: a key with an until gets its timer, a removed key loses it. */
async watched(change: Watched): Promise<void> {
const key = this.own(change.key);
if (key === undefined) return;
this.pending.get(key)?.();
this.pending.delete(key);
if (change.op !== "put" || !change.value?.until) return;
this.arm(key, change.value.until);
}
private arm(key: string, until: string): void {
const left = Date.parse(until) - this.now().getTime();
if (left <= 0) {
this.track(this.expire(key, until));
return;
}
const step = Math.min(left, LONGEST_WAIT_MS);
this.pending.set(key, this.schedule(step, () => {
this.pending.delete(key);
if (step < left) this.arm(key, until);
else this.track(this.expire(key, until));
}));
}
/** An expiry the watch or a timer started, kept until it ends so a start waits for it (§11). */
private track(expiring: Promise<boolean>): void {
this.expiring.add(expiring);
expiring.finally(() => this.expiring.delete(expiring)).catch(() => {});
}
/** Remove a key at its until, when it still holds that until (a later allow replaced it otherwise) (§4). */
async expire(key: string, until: string): Promise<boolean> {
try {
const entry = await this.store.get(this.stored(key));
if (!entry || entry.value.until !== until || Date.parse(until) > this.now().getTime()) return false;
await this.store.delete(this.stored(key));
const a = answered(key, entry.value);
await this.say({ node: this.node, change: "expired", allowances: [a], at: this.now().toISOString() });
this.journal(`the allowance ${key} (${a.protocol} ${a.port}${a.interface ? ` on ${a.interface}` : ""}${a.source ? ` from ${a.source}` : ""}, ` +
`set by ${a.by} at ${a.at}: ${a.why}) expired at ${until} and is removed`);
return true;
} catch (err) {
this.journal(`the allowance ${key} expired at ${until} and could not be removed: ${err instanceof Error ? err.message : String(err)}`);
return false;
}
}
/** Open a port (§2): one key per named interface, or the default set's one key; a key there already is replaced
* whole and answered. */
async allow(args: Record<string, unknown>, by: string): Promise<{ allowances: Kept[]; said: boolean }> {
this.proven("allow", by);
only(args, ["port", "protocol", "interfaces", "source", "until", "why"]);
const convergence = await this.askConverged("allow");
this.refuseAdopted("allow", convergence);
// The outward links as the node-engine classifies them for its render, from the converged answer of this call; the
// loaded table's shape is never read to tell one from the tunnel (§4, H-A-325).
const outward = new Set(convergence.outward);
const now = this.now();
const port = portOf(args.port);
const protocol = protocolOf(args.protocol);
const interfaces = interfacesOf(args.interfaces);
const source = sourceOf(args.source);
const until = untilOf(args.until, now);
const why = whyOf(args.why);
if (!source && privateOnly(await this.asks.meshTable(), protocol, port)) {
refuse("port", `${protocol} ${port} is admitted by a derived rule of the loaded mesh table from given sources only (the private network's, such as the store's ` +
"port or the broker's management port); an allowance from any source would widen it: give a source");
}
const most = await this.asks.most();
const kept = await this.ownKeys();
const after = new Set([...kept, ...interfaces.map((i) => keyOf(protocol, port, i))]).size;
if (after > most) refuse("port", `${after} allowances would be kept on this node, more than allowances-max ${most}`);
const at = now.toISOString();
const keys = interfaces.map((i) => keyOf(protocol, port, i));
await this.recorded({ what: `allowed ${keys.join(", ")} on ${this.node}${source ? ` from ${source}` : ""}${until ? ` until ${until}` : ""}`,
why: `${why} (${by})`, cause: "allowance-set", verb: "allow" });
const out: Kept[] = [];
for (const iface of interfaces) {
const key = keyOf(protocol, port, iface);
const value: AllowanceValue = {
port, protocol,
...(iface ? { interface: iface } : {}),
...(source ? { source } : {}),
...(until ? { until } : {}),
why, by, at,
};
const before = await this.store.get(this.stored(key));
await this.store.put(this.stored(key), value);
out.push({
...answered(key, value),
...(iface && outward.has(iface) ? { outward: iface } : {}),
...(before ? { replaced: answered(key, before.value) } : {}),
});
}
await this.say({ node: this.node, change: "allowed", allowances: out.map(({ replaced: _, outward: __, ...a }) => a), by, why, at });
return { allowances: out, said: true };
}
/** Take back allowances (§3): every key named is deleted, or, when one does not exist, it is refused by name and
* none is deleted. */
async disallow(args: Record<string, unknown>, by: string): Promise<{ allowances: Allowance[]; said: boolean }> {
this.proven("disallow", by);
only(args, ["port", "protocol", "interfaces", "why"]);
this.refuseAdopted("disallow", await this.askConverged("disallow"));
const port = portOf(args.port);
const protocol = protocolOf(args.protocol);
const interfaces = interfacesOf(args.interfaces);
const why = whyOf(args.why);
const found: Allowance[] = [];
for (const iface of interfaces) {
const key = keyOf(protocol, port, iface);
const entry = await this.store.get(this.stored(key));
if (!entry) throw new Error(`no allowance ${key} is kept on this node; nothing is deleted`);
found.push(answered(key, entry.value));
}
await this.recorded({ what: `disallowed ${found.map((a) => a.key).join(", ")} on ${this.node}`, why: `${why} (${by})`, cause: "allowance-taken-back", verb: "disallow" });
for (const a of found) await this.store.delete(this.stored(a.key));
await this.say({ node: this.node, change: "disallowed", allowances: found, by, why, at: this.now().toISOString() });
return { allowances: found, said: true };
}
/** Written in the hand-act log before the state is written; not written, the call is refused (§4, ADR 0565 §10). */
private async recorded(act: HandAct): Promise<void> {
try {
await this.asks.handAct(act);
} catch (err) {
throw new Error(`${act.verb}: the hand act was not recorded, so nothing is written: ${err instanceof Error ? err.message : String(err)}`);
}
}
/** Every allowance kept for this node only, sorted by key (§6); none on an adopted node, and refused while converged
* has never answered and does not answer now (H-A-318). One whose until passed before its timer fired is removed,
* said and left out, so none answered has expired. */
async allowed(args: Record<string, unknown> = {}): Promise<{ allowances: Allowance[] }> {
only(args, []);
const c = this.convergence ?? (await this.askConverged("allowed"));
if (c.state === "adopted") return { allowances: [] };
return { allowances: await this.kept() };
}
/** This node's allowances, every one past its until removed first (§11). */
private async kept(): Promise<Allowance[]> {
const now = this.now().getTime();
const allowances: Allowance[] = [];
for (const key of await this.ownKeys()) {
const entry = await this.store.get(this.stored(key));
if (!entry) continue;
if (entry.value.until && Date.parse(entry.value.until) <= now) {
await this.expire(key, entry.value.until);
continue;
}
allowances.push(answered(key, entry.value));
}
return allowances;
}
}
/** A seat verb held until the holder's start ends (§8, §11): the watch has handed every key over, every expiry it
* started has ended and started is said, so no verb answers before started; a start that failed refuses it with
* the start's error. */
export function held<A extends unknown[], R>(start: Promise<unknown>, run: (...args: A) => Promise<R>): (...args: A) => Promise<R> {
return async (...args) => {
await start;
return run(...args);
};
}
/** Each allowance marked loaded only when a rule of the mesh's table carries its comment `allowance <key> <at>` with
* an equal at, and every such comment whose key is not kept: loaded, not kept (§7, H-A-315 (5)). */
export function markLoaded(allowances: Allowance[], meshTable: string): {
allowances: (Allowance & { loaded: boolean })[];
loadedNotKept: { key: string; at: string }[];
} {
const comments = [...meshTable.matchAll(/comment "allowance (\S+) (\S+)"/g)].map((m) => ({ key: m[1], at: m[2] }));
const kept = new Set(allowances.map((a) => a.key));
const seen = new Set<string>();
const loadedNotKept = comments.filter((c) => !kept.has(c.key) && !seen.has(c.key) && seen.add(c.key));
return {
allowances: allowances.map((a) => ({ ...a, loaded: comments.some((c) => c.key === a.key && c.at === a.at) })),
loadedNotKept,
};
}
/** Whether the loaded mesh table's input chain accepts `protocol` `port` only with a source match (`ip saddr` or `ip6
* saddr`) and never from any source: a port a derived rule admits from the private network only (§3, H-A-315 (7),
* H-A-319). */
export function privateOnly(meshTable: string, protocol: Protocol, port: number): boolean {
const input = /chain input \{([\s\S]*?)\n\t?\}/.exec(meshTable)?.[1] ?? "";
let withSource = false;
for (const line of input.split("\n")) {
if (!/\baccept\b/.test(line) || !line.includes(`${protocol} dport `)) continue;
const ports = /dport (\{[^}]*\}|\S+)/.exec(line)?.[1] ?? "";
const names = ports.replace(/[{}]/g, "").split(",").map((p) => p.trim()).filter(Boolean);
const named = names.some((p) => {
const [lo, hi] = p.split("-").map(Number);
return hi === undefined ? lo === port : lo <= port && port <= hi;
});
if (!named) continue;
if (!/\bip6? saddr\b/.test(line)) return false;
withSource = true;
}
return withSource;
}
+27 -1
View File
@@ -15,10 +15,28 @@
"serves": [
"rules",
"reload",
"remove"
"remove",
"allow",
"disallow",
"allowed"
]
}
],
"requires": [
{
"name": "allowances",
"storage": "key-value",
"template": "state",
"options": {
"history": 1,
"per-machine": true
}
}
],
"invokes": [
"seat:node-engine.converged",
"seat:mesh-hand-acts.hand-act"
],
"filtering": {
"into": "/etc/nftables.conf"
},
@@ -71,6 +89,14 @@
"tools": [
"firewall_rules"
],
"config": {
"allowances-max": {
"type": "number",
"description": "The most allowances this machine keeps, which allow refuses past (design 33 control-verbs §3): it keeps the rendered chain readable and allowed in one answer.",
"trusted": false,
"default": 100
}
},
"build": {
"artifacts": [
{
+5 -3
View File
@@ -1,15 +1,17 @@
{
"name": "@novox/module-nftables",
"version": "0.1.0",
"description": "nftables — loads the mesh's packet filter and holds the node-packet-filter seat: its verbs rules, reload and remove (novox/hq ADR 0045, ADR 0170).",
"description": "nftables — loads the mesh's packet filter and holds the node-packet-filter seat: its verbs rules, reload, remove, allow, disallow and allowed (novox/hq ADR 0045, ADR 0170; design 47 H-A-304).",
"type": "module",
"private": true,
"scripts": {
"build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
"build": "tsc client.ts allowances.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
"test": "node --test --experimental-strip-types 'test/*.test.ts'"
},
"dependencies": {
"@novox/mesh-sdk": "^0.1.1"
"@novox/mesh-sdk": "^0.1.1",
"@novox/mesh-connectivity-contracts-node-packet-filter": "^0.1.0",
"@novox/mesh-contracts-node-engine": "^0.1.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
+345
View File
@@ -0,0 +1,345 @@
// The operator's allowances against a state in memory (ADR 0683; design 33 control-verbs §14; design 47 H-A-315,
// H-A-317, H-A-318, H-A-319).
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import {
Allowances, CONVERGED_BOUND_MS, LONGEST_WAIT_MS, MOST, STATE, held, markLoaded, privateOnly,
type AllowanceValue as Value, type AllowancesChanged as Changed, type Convergence, type HandAct, type Schedule, type Store,
} from "../allowances.ts";
interface Timer { ms: number; fire: () => void; cancelled: boolean }
// The loaded mesh table: the store's port from the private network only, 80 from anywhere and 8443 from both.
const TABLE = 'table inet mesh {\n\tchain input {\n\t\ttype filter hook input priority filter; policy drop;\n' +
'\t\tip saddr { 10.77.0.1, 10.77.0.2 } tcp dport 5432 accept\n\t\tip6 saddr { fd77::1 } tcp dport 5432 accept\n' +
'\t\ttcp dport 80 accept\n\t\tip saddr { 10.77.0.1 } tcp dport { 8443, 9500-9600 } accept\n\t\ttcp dport 8443 accept\n\t}\n}\n';
// gate, when given, holds every delete until it opens, and every get waits a turn of the event loop: a slow store.
function fake(at = "2026-11-21T20:00:00Z", node = "shanks", kept = new Map<string, Value>(), gate?: Promise<void>) {
const said: Changed[] = [];
const journal: string[] = [];
const timers: Timer[] = [];
const clock = { now: new Date(at) };
const schedule: Schedule = (ms, fire) => {
const t = { ms, fire, cancelled: false };
timers.push(t);
return () => { t.cancelled = true; };
};
const store: Store = {
get: async (k) => {
if (gate) await new Promise((r) => setImmediate(r));
return kept.has(k) ? { value: kept.get(k)! } : null;
},
put: async (k, v) => { kept.set(k, v); return kept.size; },
delete: async (k) => { await gate; kept.delete(k); },
keys: async () => [...kept.keys()],
};
const acts: HandAct[] = [];
const asks = {
convergence: { state: "converged", since: "2026-11-01T00:00:00Z" } as Convergence | "silent",
asked: 0,
most: MOST,
table: TABLE,
};
const a = new Allowances(store, node, async (b) => { said.push(b); }, {
converged: () => {
asks.asked++;
return asks.convergence === "silent" ? new Promise<Convergence>(() => {}) : Promise.resolve(asks.convergence);
},
handAct: async (act) => { acts.push(act); },
most: async () => asks.most,
meshTable: async () => asks.table,
}, () => clock.now, schedule, (l) => journal.push(l));
return { a, kept, said, clock, timers, journal, acts, asks };
}
/** The state's key of an allowance's key on shanks (H-A-317). */
const k = (key: string) => `shanks.${key}`;
const settle = () => new Promise((r) => setImmediate(r));
test("allow keeps one key per interface, and with none the default set's key, which names no interface", async () => {
const cases: { name: string; args: Record<string, unknown>; keys: string[] }[] = [
{ name: "defaults", args: { port: 8000, why: "the operator's dev server" }, keys: ["allow.tcp.8000"] },
{ name: "two interfaces", args: { port: 5353, protocol: "udp", interfaces: ["enp6s0", "wlan0"], source: "192.168.1.0/24", why: "w" },
keys: ["allow.udp.5353.enp6s0", "allow.udp.5353.wlan0"] },
{ name: "an interface with a dot", args: { port: 1, interfaces: ["enp6s0.10"], why: "w" }, keys: ["allow.tcp.1.enp6s0.10"] },
];
for (const c of cases) {
const { a, kept, said } = fake();
const got = await a.allow(c.args, "lead@shanks");
assert.deepEqual(got.allowances.map((x) => x.key), c.keys, c.name);
assert.equal(got.said, true, c.name);
assert.deepEqual([...kept.keys()].sort(), c.keys.map(k), c.name);
assert.deepEqual(said.map((b) => [b.change, b.node, b.by, b.why, b.allowances.map((x) => x.key)]),
[["allowed", "shanks", "lead@shanks", c.args.why, c.keys]], c.name);
for (const v of kept.values()) {
assert.equal(v.by, "lead@shanks", c.name);
assert.equal(v.at, "2026-11-21T20:00:00.000Z", c.name);
assert.equal(v.source, c.args.source, c.name);
if (!c.args.interfaces) assert.equal("interface" in v, false, "the private network's interface is never in the defaults");
}
}
});
test("allow naming an outward link answers it as outward, as converged lists them; another interface and the default set do not (H-A-325)", async () => {
const { a, asks, said } = fake();
asks.convergence = { state: "converged", since: "2026-11-01T00:00:00Z", tunnel: "mesh0", outward: ["eth1"] };
const named = await a.allow({ port: 8000, interfaces: ["eth1", "enp6s0"], why: "w" }, "lead@shanks");
assert.deepEqual(named.allowances.map((x) => [x.key, x.outward]), [["allow.tcp.8000.eth1", "eth1"], ["allow.tcp.8000.enp6s0", undefined]]);
assert.equal("outward" in named.allowances[1], false, "an interface that is no outward link answers without the field");
const none = await a.allow({ port: 8001, why: "w" }, "lead@shanks");
assert.equal("outward" in none.allowances[0], false, "the default set opens no outward link");
assert.equal(said.flatMap((b) => b.allowances).some((x) => "outward" in x), false, "the event's allowances carry no outward");
});
test("allow and disallow refuse what is not an allowance, writing nothing", async () => {
const bad: [string, Record<string, unknown>, RegExp][] = [
["port 0", { port: 0, why: "w" }, /port: /],
["port 65536", { port: 65536, why: "w" }, /port: /],
["port 80a", { port: "80a", why: "w" }, /port: /],
["protocol icmp", { port: 80, protocol: "icmp", why: "w" }, /protocol: /],
["interface", { port: 80, interfaces: ["a b"], why: "w" }, /interfaces: /],
["interface too long", { port: 80, interfaces: ["abcdefghijklmnop"], why: "w" }, /interfaces: /],
["source", { port: 80, source: "10.0.0.0/33", why: "w" }, /source: /],
["until in the past", { port: 80, until: "2026-11-21T19:00:00Z", why: "w" }, /until: .*not in the future/],
["until not a time", { port: 80, until: "tomorrow", why: "w" }, /until: /],
["until without seconds", { port: 80, until: "2026-11-22T08:00Z", why: "w" }, /until: .* with seconds/],
["empty why", { port: 80, why: "" }, /why: /],
["long why", { port: 80, why: "x".repeat(501) }, /why: /],
["unknown argument", { port: 80, why: "w", comment: "x" }, /comment: not an argument/],
["the store's port with no source", { port: 5432, why: "w" }, /port: tcp 5432 is admitted .* from given sources only/],
];
for (const [name, args, want] of bad) {
const { a, kept, said, acts } = fake();
await assert.rejects(a.allow(args, "x"), want, name);
assert.equal(kept.size, 0, name);
assert.equal(said.length, 0, name);
assert.equal(acts.length, 0, name);
}
const { a, kept } = fake();
await assert.rejects(a.allow({ port: 80, why: "w" }, "unproven"), /allow: refused: the request carries no caller the tool runner proved/);
await assert.rejects(a.disallow({ port: 80, why: "w" }, "unproven"), /disallow: refused: the request carries no caller/);
await a.allow({ port: 5432, source: "192.168.1.0/24", why: "the store from the home network" }, "x");
assert.deepEqual([...kept.keys()], [k("allow.tcp.5432")]);
await assert.rejects(a.disallow({ port: 80, why: "w", source: "10.0.0.1" }, "x"), /source: not an argument/);
await assert.rejects(a.disallow({ port: 80 }, "x"), /why: /);
await assert.rejects(a.allowed({ port: 80 }), /port: not an argument/);
});
test("a 101st allowance is refused at the default allowances-max; a replacement at the bound is not", async () => {
const { a, kept } = fake();
for (let p = 1; p <= MOST; p++) await a.allow({ port: p, why: "w" }, "x");
await assert.rejects(a.allow({ port: 1000, why: "w" }, "x"), /101 allowances would be kept on this node, more than allowances-max 100/);
assert.equal(kept.size, MOST);
await a.allow({ port: 1, why: "again" }, "x");
assert.equal(kept.get(k("allow.tcp.1"))!.why, "again");
});
test("an allowance kept on one node is absent from another node's allowed, and counts not toward its bound", async () => {
const shared = new Map<string, Value>();
const shanks = fake(undefined, "shanks", shared);
const ace = fake(undefined, "ace", shared);
ace.asks.most = 1;
await shanks.a.allow({ port: 8000, why: "w" }, "x");
assert.deepEqual((await ace.a.allowed()).allowances, []);
await ace.a.allow({ port: 9000, why: "w" }, "x");
assert.deepEqual([...shared.keys()].sort(), ["ace.allow.tcp.9000", "shanks.allow.tcp.8000"]);
assert.deepEqual((await shanks.a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000"]);
await assert.rejects(ace.a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /);
});
test("on an adopted node allow and disallow are refused naming the adoption and allowed answers none; a silent converged refuses both", async () => {
const { a, kept, asks, timers, said } = fake();
await a.allow({ port: 8000, why: "w" }, "x");
asks.convergence = { state: "adopted", since: "2026-11-20T10:00:00Z", found: "ufw" };
await assert.rejects(a.allow({ port: 9000, why: "w" }, "x"), /allow: refused: this node is adopted \(the found firewall ufw, since 2026-11-20T10:00:00Z\)/);
await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /disallow: refused: this node is adopted/);
assert.deepEqual((await a.allowed()).allowances, []);
assert.deepEqual([...kept.keys()], [k("allow.tcp.8000")]);
asks.convergence = "silent";
const pending = a.allow({ port: 9000, why: "w" }, "x");
const bound = timers.at(-1)!;
assert.equal(bound.ms, CONVERGED_BOUND_MS);
bound.fire();
await assert.rejects(pending, /allow: refused: the node-engine's converged did not answer \(no answer within 10 s\)/);
const gone = a.disallow({ port: 8000, why: "w" }, "x");
timers.at(-1)!.fire();
await assert.rejects(gone, /disallow: refused: the node-engine's converged did not answer/);
assert.equal(said.length, 1);
});
test("allowed asks converged again while none answered, and refuses when it does not answer (H-A-318)", async () => {
const { a, asks, timers, said, journal } = fake();
asks.convergence = "silent";
const start = a.started();
timers.at(-1)!.fire();
await start;
assert.match(journal.join("\n"), /start: refused: the node-engine's converged did not answer/);
assert.equal(said.at(-1)!.change, "started");
const asked = asks.asked;
const pending = a.allowed();
timers.at(-1)!.fire();
await assert.rejects(pending, /allowed: refused: the node-engine's converged did not answer/);
assert.equal(asks.asked, asked + 1);
asks.convergence = { state: "converged" };
assert.deepEqual((await a.allowed()).allowances, []);
await a.allowed();
assert.equal(asks.asked, asked + 2, "an answer held is not asked again");
});
test("privateOnly: a port accepted only with a source match, never from any source", () => {
assert.equal(privateOnly(TABLE, "tcp", 5432), true);
assert.equal(privateOnly(TABLE, "tcp", 9550), true, "a range of a set");
assert.equal(privateOnly(TABLE, "tcp", 80), false);
assert.equal(privateOnly(TABLE, "tcp", 8443), false, "accepted from anywhere too");
assert.equal(privateOnly(TABLE, "udp", 5432), false);
assert.equal(privateOnly(TABLE, "tcp", 8000), false, "no derived rule");
});
test("allow then disallow writes the key, then deletes it, saying allowed and disallowed, with two hand-act log lines", async () => {
const { a, kept, said, acts } = fake();
const got = await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "open" }, "x");
assert.equal(got.said, true);
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
const gone = await a.disallow({ port: 8000, interfaces: ["enp6s0"], why: "done" }, "y");
assert.deepEqual(gone.allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
assert.equal(gone.said, true);
assert.equal(kept.size, 0);
assert.deepEqual(said.map((b) => [b.change, b.by, b.why]), [["allowed", "x", "open"], ["disallowed", "y", "done"]]);
assert.deepEqual(acts, [
{ what: "allowed allow.tcp.8000.enp6s0 on shanks", why: "open (x)", cause: "allowance-set", verb: "allow" },
{ what: "disallowed allow.tcp.8000.enp6s0 on shanks", why: "done (y)", cause: "allowance-taken-back", verb: "disallow" },
]);
});
test("disallow is all or nothing: a key not kept is refused by name and none is deleted", async () => {
const { a, kept, said } = fake();
await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "w" }, "x");
await assert.rejects(a.disallow({ port: 8000, interfaces: ["enp6s0", "wlan0"], why: "w" }, "x"), /no allowance allow\.tcp\.8000\.wlan0/);
assert.deepEqual([...kept.keys()], [k("allow.tcp.8000.enp6s0")]);
// no interfaces names the default set's key, never one of an interface
await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /);
assert.equal(said.length, 1);
});
test("a second allow of one key replaces it whole and answers what it replaced; the source is no part of the key", async () => {
const { a, kept } = fake();
await a.allow({ port: 8000, source: "192.168.1.0/24", until: "2026-11-22T00:00:00Z", why: "first" }, "x");
const got = await a.allow({ port: 8000, source: "10.0.0.5", why: "second" }, "y");
assert.deepEqual(got.allowances.map((x) => [x.key, x.source, x.replaced?.source, x.replaced?.why]),
[["allow.tcp.8000", "10.0.0.5", "192.168.1.0/24", "first"]]);
assert.deepEqual([...kept.entries()].map(([key, v]) => [key, v.source, v.by, v.until]), [[k("allow.tcp.8000"), "10.0.0.5", "y", undefined]]);
});
test("at its until an allowance is deleted by its timer, says expired, is journalled, and allowed answers without it", async () => {
const { a, kept, said, clock, timers, journal } = fake();
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "for an hour" }, "x");
await a.allow({ port: 9000, why: "w" }, "x");
await a.watched({ key: k("allow.tcp.8000"), op: "put", value: kept.get(k("allow.tcp.8000"))! });
const live = timers.filter((t) => !t.cancelled);
assert.equal(live.length, 1, "one expiry timer; every converged bound is cancelled once answered");
assert.equal(live[0].ms, 3600_000);
clock.now = new Date("2026-11-21T21:00:00Z");
live[0].fire();
await settle();
assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]);
assert.deepEqual([said.at(-1)!.change, said.at(-1)!.allowances.map((x) => x.key)], ["expired", ["allow.tcp.8000"]]);
assert.match(journal.join("\n"), /the allowance allow\.tcp\.8000 .*for an hour\) expired at 2026-11-21T21:00:00Z and is removed/);
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.9000"]);
});
test("the expiry timers follow the state: a delete cancels, a far until waits in steps, a stale timer removes nothing", async () => {
const { a, kept, clock, timers } = fake();
const v: Value = { port: 1, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T22:00:00Z" };
await a.watched({ key: k("allow.tcp.1"), op: "put", value: v });
await a.watched({ key: k("allow.tcp.1"), op: "delete" });
assert.equal(timers.at(-1)!.cancelled, true);
const armed = timers.length;
await a.watched({ key: "ace.allow.tcp.1", op: "put", value: v });
assert.equal(timers.length, armed, "another node's key arms no timer");
await a.watched({ key: k("allow.tcp.2"), op: "put", value: { ...v, until: "2027-06-01T00:00:00Z" } });
assert.equal(timers.at(-1)!.ms, LONGEST_WAIT_MS);
await a.allow({ port: 9000, until: "2026-11-21T21:30:00Z", why: "w" }, "x");
await a.allow({ port: 9000, until: "2026-11-21T23:00:00Z", why: "w" }, "x");
clock.now = new Date("2026-11-21T21:30:00Z");
assert.equal(await a.expire("allow.tcp.9000", "2026-11-21T21:30:00Z"), false);
assert.ok(kept.has(k("allow.tcp.9000")));
// at a start, a key already past its until is removed at once
clock.now = new Date("2026-11-22T00:00:00Z");
await a.watched({ key: k("allow.tcp.9000"), op: "put", value: kept.get(k("allow.tcp.9000"))! });
await settle();
assert.ok(!kept.has(k("allow.tcp.9000")));
});
test("at a start every expired allowance is removed before started is said (H-A-312 (2))", async () => {
const { a, kept, said, clock } = fake();
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "w" }, "x");
await a.allow({ port: 9000, why: "w" }, "x");
clock.now = new Date("2026-11-21T22:00:00Z");
await a.started();
assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]);
assert.deepEqual(said.slice(-2).map((b) => [b.change, b.allowances.map((x) => x.key)]),
[["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]);
// §11, §14: a key past its until that the watch hands over while the start runs, through a store whose get and delete
// wait: the start waits for that expiry, so it is removed and said once, and started after it.
let open!: () => void;
const waits = new Promise<void>((r) => { open = r; });
const slow = fake("2026-11-21T22:00:00Z", "shanks", new Map(), waits);
const past: Value = { port: 7000, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T21:00:00Z" };
slow.kept.set(k("allow.tcp.7000"), past);
await slow.a.watched({ key: k("allow.tcp.7000"), op: "put", value: past });
const start = slow.a.started();
for (let i = 0; i < 10; i++) await settle(); // the start runs as far as it goes while the expiry's delete waits
open();
await start;
assert.deepEqual(slow.said.map((b) => [b.change, b.allowances.map((x) => x.key)]),
[["expired", ["allow.tcp.7000"]], ["started", []]]);
});
test("started is said before the first allowed: the verbs are held until the start ends, a failed start refuses them", async () => {
const { a, asks, said, timers } = fake();
asks.convergence = "silent";
const start = a.started();
let answered = false;
const first = held(start, () => a.allowed())().then((r) => { answered = true; return r; });
await settle();
assert.equal(answered, false, "allowed answered while the start still waits on converged");
assert.equal(said.length, 0);
asks.convergence = { state: "converged", tunnel: "mesh0", outward: [] };
timers.find((t) => t.ms === CONVERGED_BOUND_MS && !t.cancelled)!.fire();
await first;
assert.deepEqual(said.map((b) => b.change), ["started"], "started was said before allowed answered");
const failed = Promise.reject(new Error("the allowances did not start: no bus"));
failed.catch(() => {});
await assert.rejects(held(failed, () => a.allowed())(), /did not start: no bus/);
});
test("a start says started with every allowance", async () => {
const { a, said } = fake();
await a.allow({ port: 8000, why: "w" }, "x");
await a.started();
assert.deepEqual([said.at(-1)!.change, said.at(-1)!.node, said.at(-1)!.allowances.map((x) => x.key)], ["started", "shanks", ["allow.tcp.8000"]]);
});
test("rules marks an allowance loaded only on a comment with an equal at, and lists a comment with no kept key as loaded, not kept", () => {
const table = 'table inet mesh {\n\tchain input {\n' +
'\t\tiifname != "mesh0" tcp dport 8000 accept comment "allowance allow.tcp.8000 2026-11-21T20:00:00.000Z"\n' +
'\t\tiifname != "mesh0" tcp dport 8001 accept comment "allowance allow.tcp.8001 2026-11-21T19:00:00.000Z"\n' +
'\t\tiifname != "mesh0" tcp dport 7000 accept comment "allowance allow.tcp.7000 2026-11-20T08:00:00.000Z"\n\t}\n}\n';
const base: Value = { port: 8000, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00.000Z" };
const got = markLoaded([{ key: "allow.tcp.8000", ...base }, { key: "allow.tcp.8001", ...base, port: 8001 }, { key: "allow.tcp.9000", ...base, port: 9000 }], table);
assert.deepEqual(got.allowances.map((x) => [x.key, x.loaded]), [["allow.tcp.8000", true], ["allow.tcp.8001", false], ["allow.tcp.9000", false]]);
assert.deepEqual(got.loadedNotKept, [{ key: "allow.tcp.7000", at: "2026-11-20T08:00:00.000Z" }]);
});
test("the manifest serves the six verbs, requires the state per machine, invokes converged and the hand-act log, and sets allowances-max", () => {
const m = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8"));
assert.deepEqual(m.claims[0].serves, ["rules", "reload", "remove", "allow", "disallow", "allowed"]);
assert.deepEqual(m.requires, [{ name: STATE, storage: "key-value", template: "state", options: { history: 1, "per-machine": true } }]);
assert.deepEqual(m.invokes, ["seat:node-engine.converged", "seat:mesh-hand-acts.hand-act"]);
assert.equal(m.emits, undefined, "the claim says the seat's event (H-A-317)");
assert.equal(m.config["allowances-max"].default, MOST);
});
+131 -10
View File
@@ -1,35 +1,102 @@
// The packet filter's tools: the node-packet-filter seat's three verbs — what the machine enforces,
// reload the mesh's own, remove one thing the mesh did not write — and the module's own reading of
// the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0170).
// The packet filter's tools: the node-packet-filter seat's six verbs — what the machine enforces, reload the
// mesh's own, remove one thing the mesh did not write, and the operator's allowances (allow, disallow, allowed) —
// and the module's own reading of the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0170, ADR 0683; design 33
// control-verbs).
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
import { callerOf } from "@novox/mesh-sdk/callers";
import { broker } from "@novox/mesh-sdk/messaging";
import { config, seatPublish } from "@novox/mesh-sdk/runtime";
import { keeps, state } from "@novox/mesh-sdk/state";
import {
allowancesChangedSubject, seat as packetFilter, verbs,
type AllowInput, type AllowedInput, type DisallowInput,
} from "@novox/mesh-connectivity-contracts-node-packet-filter";
import { seat as nodeEngine, verbs as nodeEngineVerbs } from "@novox/mesh-contracts-node-engine";
import { FirewallClient } from "../client.js";
import { Allowances, MOST, STATE, held, markLoaded, type AllowanceValue, type Convergence, type Store } from "../allowances.js";
export function getSeatVerbs(firewall: FirewallClient): ToolDefinition[] {
const port = { type: "integer", description: "the port, 1-65535" };
const protocol = { type: "string", description: "tcp (the default) or udp" };
const interfaces = {
type: "array",
items: { type: "string" },
description: "the input interfaces, each 1-15 letters, digits, _ . - (optional; none: every input interface that is neither the private network's tunnel nor an outward link, so an outward link is opened only when named)",
};
const why = { type: "string", description: "why, in words the operator reads (1-500 characters)" };
// The seat's verbs, held until the holder's start ends (§8, §11): started is said before any answers. The inputs' types
// name exactly the arguments of the seat's generated inputs; the holder validates every value itself.
export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances, start: Promise<unknown> = Promise.resolve()): ToolDefinition[] {
const allowed = held(start, () => allowances.allowed());
return [
{
name: "rules",
name: verbs.rules,
description:
"The packet filter as this machine enforces it now: the nftables ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or chain when asked.",
"The packet filter as this machine enforces it now: the nftables ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or chain when asked. " +
"Beside it every allowance, marked loaded only when a rule of the mesh's table carries its comment allowance <key> <at> with an equal at, " +
"and every loaded allowance comment whose key is not kept, listed as loaded, not kept.",
input: {
table: { type: "string", description: "one nftables table, as `family name` (optional)" },
chain: { type: "string", description: "one chain of that table (optional)" },
},
run: async (args) => firewall.rules(args.table ? String(args.table) : undefined, args.chain ? String(args.chain) : undefined),
run: async (args) => {
const table = args.table ? String(args.table) : undefined;
const seen = await firewall.rules(table, args.chain ? String(args.chain) : undefined);
// The mark reads the mesh's own table whole, whatever the listing was narrowed to.
const mesh = !table && !args.chain ? seen.nftables : await firewall.ruleset();
const marked = markLoaded((await allowed()).allowances, mesh);
return { ...seen, allowances: marked.allowances, "loaded-not-kept": marked.loadedNotKept };
},
},
{
name: "reload",
name: verbs.reload,
description: "Load the mesh's own filter again from the file the mesh writes, and answer with the mesh's table as loaded.",
input: {},
run: async () => firewall.reload(),
},
{
name: "remove",
name: verbs.remove,
description:
"Remove one rule set the mesh did not write, named exactly as `node show` lists it: `chain X (iptables-legacy)` or `table ip6 filter, chain DOCKER-USER`. " +
"Refuses the mesh's tables, the runtime's own chains, a built-in chain and an active found firewall's chains. An operator's act, by name, never a flush.",
input: { where: { type: "string", description: "the rule set, as `node show` lists it" } },
run: async (args) => firewall.remove(String(args.where ?? "")),
},
{
name: verbs.allow,
description:
"Open a port by hand on this machine, beside the ports derived from the modules' listens: one allowance per protocol, port and interface, " +
"kept as this module's state and rendered by the node-engine into the inet mesh table's input chain at its next compose of the filter. " +
"Who set it is the caller the bus proved. A key that exists is replaced whole and answered. Written in the hand-act log. " +
"Refuses, naming the argument and writing nothing, an unproven caller, an adopted node or a converged that does not answer, a bad port, protocol, interface, source or until, " +
"an empty or longer why, an unknown argument, a port the loaded mesh table admits from given sources only unless a source is given, " +
"and more allowances on the node than the setting allowances-max (default 100). Whether the loaded chain carries it is read with rules.",
input: {
port,
protocol,
interfaces,
source: { type: "string", description: "one IPv4 or IPv6 CIDR it is opened to (optional; none: any)" },
until: { type: "string", description: "when it expires, an RFC 3339 time with seconds in the future (optional)" },
why,
} satisfies Record<keyof AllowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.allow({ ...args }, callerOf(args))),
},
{
name: verbs.disallow,
description:
"Take back allowances: the keys the protocol, port and interfaces name (none: the default set's key) are deleted, or, when one does not exist, " +
"it is refused by name and none is deleted. Written in the hand-act log. Refuses as allow does an unproven caller, an adopted node and a converged that does not answer.",
input: { port, protocol, interfaces, why } satisfies Record<keyof DisallowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.disallow({ ...args }, callerOf(args))),
},
{
name: verbs.allowed,
description:
"Every allowance kept for this machine only, with its key, port, protocol, interface, source, until, why, by and at; none on an adopted node. " +
"An allowance is removed at its until, so none answered has expired.",
input: {} satisfies Record<keyof AllowedInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.allowed({ ...args })),
},
];
}
@@ -45,7 +112,61 @@ export function getFirewallTools(firewall: FirewallClient): ToolDefinition[] {
}
const firewall = FirewallClient.onThisMachine();
// The allowances are this module's own state, announced as kept (ADR 0495), one bucket per machine whose keys carry
// the node, so this holder watches and lists its own node's keys only (H-A-317); every change is said as the seat's
// event allowances-changed of this node; watching its own state gives every key with an until its timer, at every
// start too; and a start asks the node-engine's converged and says started, so a node-engine that refused a compose
// for want of an answer composes again.
const node = process.env.MESH_NODE ?? "";
const kept = state<AllowanceValue>(STATE);
const own = new Set<string>();
// The node's keys are known once the watch handed every current value over; a start that failed refuses every listing.
let watched!: { done: () => void; failed: (err: unknown) => void };
const watching = new Promise<void>((done, failed) => { watched = { done, failed }; });
watching.catch(() => {});
const store: Store = {
get: (key) => kept.get(key),
put: (key, value) => kept.put(key, value),
delete: (key) => kept.delete(key),
keys: async () => {
await watching;
return [...own];
},
};
const allowances = new Allowances(store, node, (body) => seatPublish(allowancesChangedSubject(node), body), {
converged: async () => (await broker().request<object, Convergence>(`seat:${nodeEngine}.${nodeEngineVerbs.converged}@${node}`, {})),
handAct: async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); },
most: async () => {
const v = await config("allowances-max");
if (v === undefined || v === null || v === "") return MOST;
const n = Number(v);
if (!Number.isInteger(n) || n < 1) throw new Error(`the setting allowances-max is ${JSON.stringify(v)}, not a whole number of allowances`);
return n;
},
meshTable: () => firewall.ruleset(),
});
const start = (async () => {
// A node-engine package older than the verb converged names none: refused here, loudly, never asked as
// seat:node-engine.undefined (H-A-312).
if (!nodeEngineVerbs.converged) {
throw new Error("the node-engine seat's package names no verb converged (a package older than design 33 control-verbs §10)");
}
await keeps([{ name: STATE }]);
await kept.watch(async (change) => {
if (change.op === "put") own.add(change.key);
else own.delete(change.key);
await allowances.watched(change);
}, { key: `${node}.**` });
watched.done();
await allowances.started();
})().catch((err) => {
const failed = new Error(`the allowances did not start: ${err}`);
watched.failed(failed);
console.error(`[nftables] the allowances did not start (no expiry timers, no started said): ${err}`);
throw failed;
});
start.catch(() => {});
// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
// module holds it (ADR 0159, 0160). The module's own under its own.
registerModuleTools("node-packet-filter", () => getSeatVerbs(firewall));
registerModuleTools(packetFilter, () => getSeatVerbs(firewall, allowances, start));
registerModuleTools("nftables", () => getFirewallTools(firewall));
+2 -1
View File
@@ -10,6 +10,7 @@
},
"include": [
"client.ts",
"allowances.ts",
"tools/index.ts"
]
}
}
+5
View File
@@ -328,6 +328,11 @@ func (c keeperClient) exchange(r KeeperRequest) (a KeeperAnswer, err error, unan
defer conn.Close()
_ = conn.SetDeadline(time.Now().Add(KeeperTimeout))
if err := json.NewEncoder(conn).Encode(r); err != nil {
// A keeper that refuses the peer answers and closes without reading, so the write can meet a closed socket
// (broken pipe) while the refusal already waits to be read: the refusal is the answer (issue 1960).
if derr := json.NewDecoder(conn).Decode(&a); derr == nil && a.Error != "" {
return a, errors.New(a.Error), false
}
return KeeperAnswer{}, err, true
}
if err := json.NewDecoder(conn).Decode(&a); err != nil {
+17 -4
View File
@@ -8,6 +8,7 @@ import (
"os"
"path/filepath"
"strings"
"sync/atomic"
"testing"
)
@@ -91,10 +92,12 @@ func shortTempDir(prefix string) (string, error) {
// keeper answering it acts as with the bus down, with a warning (A-8).
func TestOnlyRootOpensTheKeepersSocketAndANeedlessKeeperIsTheBusDown(t *testing.T) {
st := memStates{}
uid := 0
// The peer's uid is read by the keeper's serving goroutines and switched by the test: an atomic, so no connection
// sees it half-written (issue 1960: a data race failed the test under -race).
var uid atomic.Int32
k := &Keeper{Emit: func(string, any) error { return nil }, States: st,
Call: func(string, any) (json.RawMessage, error) { return nil, errors.New("down") },
PeerOf: func(net.Conn) (int, error) { return uid, nil }}
PeerOf: func(net.Conn) (int, error) { return int(uid.Load()), nil }}
dir, err := shortTempDir("zk")
if err != nil {
t.Fatal(err)
@@ -121,13 +124,21 @@ func TestOnlyRootOpensTheKeepersSocketAndANeedlessKeeperIsTheBusDown(t *testing.
if _, err := c.call(ToolSchedule, map[string]any{}); err == nil || !strings.Contains(err.Error(), "down") {
t.Errorf("an invoke that failed: %v", err)
}
uid = 1000
uid.Store(1000)
if err := c.Put(StateSchedule, "x", 1); err == nil || !strings.Contains(err.Error(), "only root") {
t.Errorf("a peer that is not root: %v", err)
}
// A request larger than the socket's buffer: the keeper refuses and closes before it is written whole, so the write
// meets a closed socket every time; the peer is still told it is not root (issue 1960).
if err := c.Put(StateSchedule, "y", strings.Repeat("x", 1<<20)); err == nil || !strings.Contains(err.Error(), "only root") {
t.Errorf("a peer that is not root, its write cut: %v", err)
}
if _, left := st["schedule/x"]; left {
t.Errorf("a refused peer's call was read")
}
if _, left := st["schedule/y"]; left {
t.Errorf("a refused peer's cut call was read")
}
// No socket variable: the machine keeps no bus and says so.
t.Setenv(KeeperSocketEnv, "")
m := newFake(t).machine()
@@ -151,6 +162,8 @@ func TestOnlyRootOpensTheKeepersSocketAndANeedlessKeeperIsTheBusDown(t *testing.
if err != nil {
t.Fatal(err)
}
// The socket is bound before the call below, so the call waits in its backlog until Serve accepts it: the keeper
// is up from the moment Listen returns, whenever its goroutine runs.
lctx, lcancel := context.WithCancel(context.Background())
defer lcancel()
go (&Keeper{Emit: func(string, any) error { return nil }, States: memStates{}, PeerOf: func(net.Conn) (int, error) { return 0, nil },
@@ -159,7 +172,7 @@ func TestOnlyRootOpensTheKeepersSocketAndANeedlessKeeperIsTheBusDown(t *testing.
t.Errorf("a keeper that came up later is not used: %v", err)
}
t.Setenv(KeeperSocketEnv, sock)
uid = 0
uid.Store(0)
m2 := newFake(t).machine()
m2.JoinBus()
if m2.Emit == nil || m2.States == nil || m2.Call == nil || m2.keeper == nil {